You are viewing a plain text version of this content. The canonical link for it is here.
Posted to fop-dev@xmlgraphics.apache.org by Jeff Turner <je...@apache.org> on 2003/09/11 13:30:41 UTC
[PATCH] Building docs with Forrest 0.5
Hi,
The attached patch will get FOP documentation building cleanly with the
imminent Forrest 0.5 release. There are two changes:
- It creates a new file, src/documentation/sitemap-0.5.xmap, which is a
0.5-specific version of FOP's overridden sitemap. This means the site
can continue to be built with the old Forrest, and everyone doesn't
have to upgrade at once.
- It comments out the DOCTYPE declarations from the SVG image files.
This is a workaround for what appears to be a Cocoon bug
(ClassCastExceptions when looking up the DTD).
Incidentally, I noticed a recent discussion about creating a unified PDF
manual for FOP. Forrest 0.5 has a 'site.pdf' matcher, which generates a
PDF of the whole site. It would be quite simple to modify the relevant
sitemap (aggregate.xmap) to only merge the subset of XML docs comprising
the manual. This would require adopting a unified site.xml menu file,
instead of the per-directory book.xml's that FOP currently uses.
Cheers,
--Jeff
RE: [PATCH] Building docs with Forrest 0.5
Posted by Victor Mote <vi...@outfitr.com>.
Jeff Turner wrote:
> The attached patch will get FOP documentation building cleanly with the
> imminent Forrest 0.5 release. There are two changes:
>
> - It creates a new file, src/documentation/sitemap-0.5.xmap, which is a
> 0.5-specific version of FOP's overridden sitemap. This means the site
> can continue to be built with the old Forrest, and everyone doesn't
> have to upgrade at once.
>
> - It comments out the DOCTYPE declarations from the SVG image files.
> This is a workaround for what appears to be a Cocoon bug
> (ClassCastExceptions when looking up the DTD).
>
>
> Incidentally, I noticed a recent discussion about creating a unified PDF
> manual for FOP. Forrest 0.5 has a 'site.pdf' matcher, which generates a
> PDF of the whole site. It would be quite simple to modify the relevant
> sitemap (aggregate.xmap) to only merge the subset of XML docs comprising
> the manual. This would require adopting a unified site.xml menu file,
> instead of the per-directory book.xml's that FOP currently uses.
Thanks, Jeff. I should be able to get to this later today or tomorrow.
Victor Mote
Re: [PATCH] Building docs with Forrest 0.5
Posted by Clay Leeds <cl...@medata.com>.
You're right. I'll let them know.
Clay
Victor Mote wrote:
> Clay Leeds wrote:
>
>
>>BTW, I just noticed they upgraded their fop back-end from fop-0.20.4 to
>>fop-0.20.5rc3a. Any chance they can get that updated to fop-0.20.5
>>before they release? I'm hoping someone on that list can submit the
>>request correctly, so I don't have to sign up for their mail list just
>>to make the request...
>
>
> I don't mind doing it, but, as per my previous message, you probably want to
> join that list anyway, and it would be good for Jeff et al to know of your
> increased involvement here.
>
> Victor Mote
RE: [PATCH] Building docs with Forrest 0.5
Posted by Victor Mote <vi...@outfitr.com>.
Clay Leeds wrote:
> BTW, I just noticed they upgraded their fop back-end from fop-0.20.4 to
> fop-0.20.5rc3a. Any chance they can get that updated to fop-0.20.5
> before they release? I'm hoping someone on that list can submit the
> request correctly, so I don't have to sign up for their mail list just
> to make the request...
I don't mind doing it, but, as per my previous message, you probably want to
join that list anyway, and it would be good for Jeff et al to know of your
increased involvement here.
Victor Mote
Re: [PATCH] Building docs with Forrest 0.5
Posted by Clay Leeds <cl...@medata.com>.
BTW, I just noticed they upgraded their fop back-end from fop-0.20.4 to
fop-0.20.5rc3a. Any chance they can get that updated to fop-0.20.5
before they release? I'm hoping someone on that list can submit the
request correctly, so I don't have to sign up for their mail list just
to make the request...
Web Maestro Clay
;-p
RE: [PATCH] Building docs with Forrest 0.5
Posted by Victor Mote <vi...@outfitr.com>.
Clay Leeds wrote:
> Sounds good to me.
>
> Having never played around with Forrest, I'd like a little help getting
> up to speed. Victor (et al), could you give me any pointers or links to
> things I should pay attention to in building this? In particular, tips
> on how to get started, as well as any links that will help get me on my
> way (such as FOP's site.xml in CVS, and any other such links), as well
> as perhaps showing me (if you know) how to change one of the sections
> and/or links, I'll do what it takes to extrapolate that to the rest of
> the site.
I haven't gone to the trouble of becoming an expert, but kind of follow a
"need to know" approach -- if I need to know, I'll go find out. The basics
are documented at:
http://xml.apache.org/fop/dev/doc.html
which you may want to supplement as you learn more.
Other general things:
1. Forrest uses Apache Cocoon for its processing, so a rudimentary
understanding of Cocoon is very helpful. I purchased Mozcar & Aston's
"Cocoon Developer's Handbook", which was of some help.
2. The big gotcha on the FOP site is compliance.xml, which requires (AFAICT)
a custom processing step as it uses a specialized DTD, its own stylesheet
etc.
3. One of the things we had asked for was a site-wide way of describing the
FOP web site, especially one that was not directory-structure dependent. I
think they have implemented this, and I think that is what Jeff is referring
to in his email. The main benefit to us is that we should be able to
rearrange our web site doc without having to move files around as much.
4. The last time I used it (circa January), the Forrest web site assumed
that I knew more than I did, and it was of limited use to me. This was
partly because things are changing on that project pretty fast. It may be
much better now, I just don't know. The good news is that they give
excellent support & you will probably want to join the mailing list for that
purpose.
5. Our doc is generated by forrestbot, which is essentially a snapshot of
Forrest that is set up to run automatically on the Apache server(s). See the
above link for more details. You will not ordinarily need to work with a
copy of Forrest on your local machine. (Christian probably has to for
creating the release documentation).
6. I probably know more than I am telling here, but that is all I can think
of ATM. Feel free to ask specific questions if you have them.
> I've taken a gander at http://xml.apache.org/forrest/changes.html for
> some ideas, and that's helpful. I'll also spend some time going through
> their docs. BTW, I notice that 0.5 is still unreleased... Anyway, I'd be
> happy to check some of this stuff out...
The key thing here is that forrestbot is using a 0.5 release candidate, and
forrestbot is what drives our concerns.
> Web Maestro Clay
>
> p.s. I'll be going to Kaua'i for my birthday (at the end of next
> week--lucky me!) Hopefully I'll be far along in the process by then... ;-p
AFAIK, there is no rush. Thanks for jumping in to help here.
Victor Mote
Re: [PATCH] Building docs with Forrest 0.5
Posted by Clay Leeds <cl...@medata.com>.
Victor Mote wrote:
>>Incidentally, I noticed a recent discussion about creating a unified PDF
>>manual for FOP. Forrest 0.5 has a 'site.pdf' matcher, which generates a
>>PDF of the whole site. It would be quite simple to modify the relevant
>>sitemap (aggregate.xmap) to only merge the subset of XML docs comprising
>>the manual. This would require adopting a unified site.xml menu file,
>>instead of the per-directory book.xml's that FOP currently uses.
>
> Unless anyone thinks this is urgent, I'm going to defer working on this
> until we get, er, the technology that Forrest uses to create PDFs, working a
> bit, ahem, better. OTOH, perhaps Clay or someone else would like to jump in
> & digest the new features of 0.5.
>
> Victor Mote
Sounds good to me.
Having never played around with Forrest, I'd like a little help getting
up to speed. Victor (et al), could you give me any pointers or links to
things I should pay attention to in building this? In particular, tips
on how to get started, as well as any links that will help get me on my
way (such as FOP's site.xml in CVS, and any other such links), as well
as perhaps showing me (if you know) how to change one of the sections
and/or links, I'll do what it takes to extrapolate that to the rest of
the site.
I've taken a gander at http://xml.apache.org/forrest/changes.html for
some ideas, and that's helpful. I'll also spend some time going through
their docs. BTW, I notice that 0.5 is still unreleased... Anyway, I'd be
happy to check some of this stuff out...
Web Maestro Clay
p.s. I'll be going to Kaua'i for my birthday (at the end of next
week--lucky me!) Hopefully I'll be far along in the process by then... ;-p
RE: [PATCH] Building docs with Forrest 0.5
Posted by Victor Mote <vi...@outfitr.com>.
Glen Mazza wrote:
> Sometime tomorrow--I just added Andreas' name to our
> teampage (he OK'ed it) so it will take awhile to get
> to the Forrestbot stage area--please republish the
> website. Thanks.
Sorry to be so slow. We have some cosmetic issues related to the Forrest
upgrade that I would like to resolve before republishing, so that we can
keep the current look as a reference point. I'll republish as quickly after
that as possible.
Thanks for adding Andreas to the page -- it is definitely well-deserved.
Victor Mote
RE: [PATCH] Building docs with Forrest 0.5
Posted by Glen Mazza <gr...@yahoo.com>.
Victor,
Sometime tomorrow--I just added Andreas' name to our
teampage (he OK'ed it) so it will take awhile to get
to the Forrestbot stage area--please republish the
website. Thanks.
Thanks,
Glen
--- Victor Mote <vi...@outfitr.com> wrote:
> Jeff Turner wrote:
>
> > The attached patch will get FOP documentation
> building cleanly with the
> > imminent Forrest 0.5 release. There are two
> changes:
__________________________________
Do you Yahoo!?
Yahoo! SiteBuilder - Free, easy-to-use web site design software
http://sitebuilder.yahoo.com
RE: [PATCH] Building docs with Forrest 0.5
Posted by Victor Mote <vi...@outfitr.com>.
Jeff Turner wrote:
> The attached patch will get FOP documentation building cleanly with the
> imminent Forrest 0.5 release. There are two changes:
>
> - It creates a new file, src/documentation/sitemap-0.5.xmap, which is a
> 0.5-specific version of FOP's overridden sitemap. This means the site
> can continue to be built with the old Forrest, and everyone doesn't
> have to upgrade at once.
>
> - It comments out the DOCTYPE declarations from the SVG image files.
> This is a workaround for what appears to be a Cocoon bug
> (ClassCastExceptions when looking up the DTD).
I have applied this patch. Thanks, Jeff, very much for your efforts in
reducing the impact of the upgrade.
> Incidentally, I noticed a recent discussion about creating a unified PDF
> manual for FOP. Forrest 0.5 has a 'site.pdf' matcher, which generates a
> PDF of the whole site. It would be quite simple to modify the relevant
> sitemap (aggregate.xmap) to only merge the subset of XML docs comprising
> the manual. This would require adopting a unified site.xml menu file,
> instead of the per-directory book.xml's that FOP currently uses.
Unless anyone thinks this is urgent, I'm going to defer working on this
until we get, er, the technology that Forrest uses to create PDFs, working a
bit, ahem, better. OTOH, perhaps Clay or someone else would like to jump in
& digest the new features of 0.5.
Victor Mote