On Fri, 2002-10-25 at 16:49, Victor Mote wrote:
Joerg is probably the key person to answer this, but I would like to throw
in 2 cents worth. First, AFAIK, all of our current documentation flows out
of XML files. If this is not totally true (and it may not be), then it
probably should be (I think they call it eating your own dog food). So,
docs/xml-docs seems redundant. Perhaps a concept of sources and output would
be helpful here. Second, one of my goals with the doc is to explicitly
delineate between user doc and developer doc, so that we can generate
manuals and web-site areas that are appropriate for each -- specifically to
keep developer issues out of the user doc. I have been treating the
documents in docs/xml-docs/design as being developer doc, although there are
a few documents in the docs/xml-docs/fop directory that are
developer-oriented as well. I think it would be helpful to have our source
XML documents organized around that concept as well.
Thanks for the ideas.
I have had a look around and other projects us src/documentation for the
docs, so I will put them in their. Keep it consistent.
I will commit the files and you will be able to see what forrest does so
then you will see how it fits together. Essentially it goes like so:
- docs are in src/documentation (can be somewhere else)
- settings are specified in forrest.properties for location of docs,
sitemap etc.
- you setup an installation of ant+forrest
- run forrest from the xml-fop directory
- the docs are converted across to the build/site directory
My recommended structure for the docs directory is as follows:
source
source/dev See note 1
source/user
buildSee note 2
build/pdf
build/html
transient (or temp) See note 3
stylesheet
(the other directories there now are ok -- graphics, examples, etc.)
Forrest specifies many of these things, try it out and see how it works.
You need to get forrest cvs then do build dist. Follow the instructions.
Note 1 -- for stuff currently in design + the documents you are asking
about and the other developer documents. In my mind design is a subset of
dev. It might be useful to have design as a subdirectory under dev.
I was thinking of dev as in the user+design documentation of the current
fop development. This is on a tab. Then the design documentation (which
only appplies to the development) is a sub directory thing from the dev
tab menu.
Note 2 -- perhaps this should be in xml-fop/build/docs instead. It is
important to have this be in a build or output directory so that no one
is tempted to, for example, edit the html files directly
see above
Note 3 -- for transient transforms when doing builds, including the fo file.
The build could probably delete the contents, but sometimes it is nice to be
able to see the intermediate results.
Thats forrest internals...
All of this, of course, is contingent on Forrest requirements.
Sorry -- you asked a pretty simple question that was probably directed at
Joerg. I have been trying to document (and fix where possible) these
annoyances as they come up, hoping to use my still-mostly-newbie perspective
to lower the cost of bringing new newbies (??) on board.
I just want to get things in place so that I can get some information
down and let others dive in.
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, email: [EMAIL PROTECTED]
