xmlgraphics-fop-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Peter B. West" <pbw...@powerup.com.au>
Subject Re: Documentation woes
Date Mon, 06 Jan 2003 00:32:00 GMT
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


Mime
View raw message