Documentation woes

[Joerg Pietschmann <j3...@yahoo.de>]

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.

In general, having both a docs and src/documentation is a permanent
source of confusion for me. If possible, this should be cleaned up a bit:
- Move docs/examples to examples.
- Move docs/graphics somewhere into src/documentation/content (it is
  content after all, or isn't it?).
- Somehow get rid of docs/xml-docs, in particular move docs/xml-docs/data
  into src/documentation/content.
- Move docs/foschema somewhere else, perhaps to the toplevel like examples
  or to src/documentation/resources.
- The docs/design/fo_impl could probably be deleted. Are there reasons
  to keep it?

Further, why do we have two xml2pdf.xsl and, even more confusing, an
additional FAQ in src/documentation/content/xdocs/dev which seems to be
more or less the same as the "regular" FAQ? In fact, the complete
src/documentation/content/xdocs/dev directory is a mystery to me.
Also there are fo directories in src/documentation/content/xdocs and
src/documentation/content/xdocs/dev. Are they supposed to be resources
for download? I'd rather find a way to link into the examples directory.

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.

I'd be glad to hear comments.

Ah, I've committed a validation task for the xdocs. This won't work without
an Ant 1.5 optional.jar, and probably the path to the xml-forrest check out
must be adjusted for others. I'm not proud of copying the whole forrest
catalog.xcat (<- another file extension I've reasons to object) into the build
file, perhaps I should use an XSLT task to generate a task specific buildfile
and use <ant> to call it.

J.Pietschmann

---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org

Re: Documentation woes

["Peter B. West" <pb...@powerup.com.au>]

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