Joerg Pietschmann wrote:
> Hi all,
> I think there are still some problems with regard to our documentation.
> 1. There is a src/documentation/content/design/alt.design with some
> HTML files
> 2. There's also a src/documentation/content/xdocs/design/alt.design
> with some more XML files
> 3. Furthermore there is a docs/design/alt.design with even more files,
> apparently diagrams and figures.
> This keeps confusing me: is it forrest which forces these files to be
> scattered all over the directory structure? I'd think they could be
> a) better grouped together
> b) better separated from the other documentation files.
>
> If this is all caused by Forrest, I'm disappointed with this tool. Having a
> foul mix of docs for HEAD and the maintenance code is bad enough, but
> having examples, downloadable ressources, graphics and SVG and finally
> the docs for another code branch scattered all over the place is too much
> for me.
Joerg,
The current state of the alt.design docs is partially a result of my
pressuring Keiron to migrate the docs across. I am in the process of
updating and extending that documentation. I will look to removing the
remaining files from docs/design/alt.design in the next week. At the
moment these are source files for dia, which I was using to generate
some diagrams. Most of them will be removed, but some will survive, and
will have to find a home, with other diagram sources (e.g. OpenOffice
drawing files) in the src/documentation tree.
The HTML files in src/documentation/design/alt.design will remain as
part of the alt.design documentation, taking advantage of the recent
resolutions in forrest-dev. They are generated with htmlize.el plus a
short perl script which was necessary because of my lack of elisp
skills. It's the only way I can see to achieve the documentation
results that I want, but I'm not the only one to require files generated
outside forrest.
So,
1) Yes, as explained above, and necessary whenever forrest cannot
generate the particular file you want;
2) The standard approach which provides the framework for the alt.design
documentation;
3) A historical artefact, which will soon go away.
Peter
--
Peter B. West pbwest@powerup.com.au http://www.powerup.com.au/~pbwest/
"Lord, to whom shall we go?"
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org
|