documentation

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

FOP Developers:

I submitted a patch (through Bugzilla, for trunk) that fixes some problems
in the pdfdoc build. I realize that Joerg is doing some work in that area as
well, and I don't mean to step on any of that, but I am not sure exactly
what that work involves, so I pressed forward. (BTW, my apologies to
Joerg -- I think I have mis-Romanized his name in some previous postings).
My purpose here is to be able to generate a downloadable PDF that is the
"FOP User Documentation". I haven't touched the content yet.

Item 1: The 0.20.4 release does not seem to have the fo.pdf file included,
probably because the xmldoc files aren't in the maintenance branch (to build
the pdfdocs, use the FOP classes from the maintenance branch on the xml-docs
files in the trunk). Since we don't plan to do many more releases from the
maintenance branch, I don't know whether it is easier to a) copy the files
from trunk to maintenance, b) just generate the pdf from the trunk & include
it with the maintenance release, or c) not include the document in the
release.

Item 2: I intend to spend some more time on the doc, contingent upon whether
I am interfering with Joerg's efforts. There are still some infrastructure
things that need to be fixed (internal links in the pdf need to be fixed,
for example). Equally important, I want to beef up some of the content
areas, especially the FAQ. (It has been well-documented on this list that
nobody reads the FAQ, but I need a place to write such things just for my
own benefit :-)  ).

Item 3: This is really a question about content organization. I would like
to split the documentation into two groups, user and developer, and in
addition to the document mentioned above, generate an "FOP Developer
Documentation" pdf. This would involve pulling some of the doc out of the
current directory (docs/xml-docs/fop) and moving it to a new one
(docs/xml-docs/fop-dev). The benefits of this approach seem clear to me, but
please let me know if you have general objections. Also, this may have web
site and Forrest ramifications (I am unclear on how our web site is
currently generated), so there may be implementation objections as well.

Vic


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

Re: documentation

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

On Thu, 2002-10-10 at 00:00, J.Pietschmann wrote:
> Christian Geisert wrote:
> > Ok. IMHO the next step should be the migration of the current docs
> > to forrest (Joerg?)
> 
> Migration to forrest DTDs. I seem to have lost track of recent changes,
> and I'm still unwilling to force everyone to use forrest, which includes
> Cocoon, simply to build the docs, which is unfortunately required if
> you want to use forrest's XSLT unchanged. I'm almost done, only a few
> small issues remain (one is that I'm in horror of doing large additions
> and deletions to the source tree).

I wouldn't think that many people do or need to create the html from the
source docs. I think it is reasonable to ask those that do to use
forrest.

We could let them download a forrest runtime, set up the path and call
"forrest", the docs would then be created.

I really want the new docs in cvs so we can start to clear up many of
the issues that keep getting asked on the lists.


Keiron.


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

Re: documentation

["J.Pietschmann" <j3...@yahoo.de>]

Christian Geisert wrote:
> Ok. IMHO the next step should be the migration of the current docs
> to forrest (Joerg?)

Migration to forrest DTDs. I seem to have lost track of recent changes,
and I'm still unwilling to force everyone to use forrest, which includes
Cocoon, simply to build the docs, which is unfortunately required if
you want to use forrest's XSLT unchanged. I'm almost done, only a few
small issues remain (one is that I'm in horror of doing large additions
and deletions to the source tree).

J.Pietschmann


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

Re: documentation

[Christian Geisert <ch...@isu-gmbh.de>]

Victor Mote schrieb:
> Christian Geisert wrote:

[..]

> Well, in the meantime, unless my patch or approach messes up Joerg's work
> somehow, it seems reasonable to do what we can with what we have.

I tried to apply your patch but it failed (no time to analyse).
Maybe someone else can have a look at it.

> Vic

Christian


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

RE: documentation

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

Christian Geisert wrote:

> Forrest offers one PDF per page at the moment
> (see http://outerthought.net/forrest/ for example)

One PDF per page is fine, but it is inconvenient to download or print the
whole.

> > Item 1: The 0.20.4 release does not seem to have the fo.pdf
> file included,
> > probably because the xmldoc files aren't in the maintenance
> branch (to build
>
> Because pdf generation was broken..

You must be talking about on the trunk, because I don't see xmldocs in the
maint branch at all. The patch that I submitted should substantially fix the
pdf generation that was broken in the trunk (I have more work here to submit
as well).

> I'm too not sure what's the best ..
> Some time ago we decided to maintain the docs in the trunk only.
> For the 0.20.3 release I copied the xml-sources to the maintenance
> branch and build the docs there.

You must mean in your local sandbox, just to get the build done?

> We already have some kind of developer documentation (called design
> docs). See http://xml.apache.org/fop/design/index.html, sources are in
> docs/design.

Yep. That's most of the stuff that went into it, although there are a couple
of other documents that are in docs/xmldocs/fop that went in as well (when I
say "went in", that is past tense for me, but I have not submitted that work
yet). Eventually, I think some developer-oriented content should be culled
from the user docs & moved over to design/developer docs.

> It's quite complicated at the moment and Forrest should improve this
> but I don't see how this will happen at the moment.

Well, in the meantime, unless my patch or approach messes up Joerg's work
somehow, it seems reasonable to do what we can with what we have.

Vic


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

Re: documentation

[Christian Geisert <ch...@isu-gmbh.de>]

Victor Mote schrieb:
> FOP Developers:
> 
> I submitted a patch (through Bugzilla, for trunk) that fixes some problems
> in the pdfdoc build. I realize that Joerg is doing some work in that area as
> well, and I don't mean to step on any of that, but I am not sure exactly
> what that work involves, so I pressed forward. (BTW, my apologies to
> Joerg -- I think I have mis-Romanized his name in some previous postings).
> My purpose here is to be able to generate a downloadable PDF that is the

Forrest offers one PDF per page at the moment
(see http://outerthought.net/forrest/ for example)

> Item 1: The 0.20.4 release does not seem to have the fo.pdf file included,
> probably because the xmldoc files aren't in the maintenance branch (to build

Because pdf generation was broken..

> the pdfdocs, use the FOP classes from the maintenance branch on the xml-docs
> files in the trunk). Since we don't plan to do many more releases from the
> maintenance branch, I don't know whether it is easier to a) copy the files
> from trunk to maintenance, b) just generate the pdf from the trunk & include
> it with the maintenance release, or c) not include the document in the
> release.

I'm too not sure what's the best ..
Some time ago we decided to maintain the docs in the trunk only.
For the 0.20.3 release I copied the xml-sources to the maintenance
branch and build the docs there.
For FOP 0.20.4 I did build the html-docs within the trunk and
copied the html to the distribution because stylebook was (and still is)
broken in the maintenance branch (I think xerces1 is needed)

> for example). Equally important, I want to beef up some of the content
> areas, especially the FAQ. (It has been well-documented on this list that
> nobody reads the FAQ, but I need a place to write such things just for my
> own benefit :-)  ).

IIRC Joerg has done some work on the (new) FAQ.
(And I'm sure at least some people will read the FAQ)

> Item 3: This is really a question about content organization. I would like
> to split the documentation into two groups, user and developer, and in

We already have some kind of developer documentation (called design 
docs). See http://xml.apache.org/fop/design/index.html, sources are in 
docs/design.

> please let me know if you have general objections. Also, this may have web
> site and Forrest ramifications (I am unclear on how our web site is
> currently generated), so there may be implementation objections as well.

It's quite complicated at the moment and Forrest should improve this
but I don't see how this will happen at the moment.


Ok. IMHO the next step should be the migration of the current docs
to forrest (Joerg?)

Christian


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

RE: documentation

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

Victor Mote wrote:

> Item 3: This is really a question about content organization. I would like
> to split the documentation into two groups, user and developer, and in
> addition to the document mentioned above, generate an "FOP Developer
> Documentation" pdf. This would involve pulling some of the doc out of the
> current directory (docs/xml-docs/fop) and moving it to a new one
> (docs/xml-docs/fop-dev).

I should also have mentioned that the documents in the docs/design folder
would go into the developer documentation pdf.

Vic


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