location of docs

[Keiron Liddle <ke...@aftexsw.com>]

Where will the docs be located.

I am writing/updating some docs for fop development and was wondering
where I could put the docs.

maybe docs/xml-docs as the base?




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

RE: location of docs

[Keiron Liddle <ke...@aftexsw.com>]

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
>     build                        See 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: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org

RE: location of docs

[Victor Mote <vi...@outfitr.com>]

Keiron Liddle wrote:

> Where will the docs be located.
>
> I am writing/updating some docs for fop development and was wondering
> where I could put the docs.
>
> maybe docs/xml-docs as the base?

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.

My recommended structure for the docs directory is as follows:

    source
    source/dev                   See note 1
    source/user
    build                        See note 2
    build/pdf
    build/html
    transient (or temp)          See note 3
    stylesheet
    (the other directories there now are ok -- graphics, examples, etc.)

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".

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

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.

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.

It will require someone with commit abilities to do all of this, but, if
approved, I'll be glad to do the fixes and cleanup of the builds to match
the new structure.

Victor Mote


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