You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by "J.Pietschmann" <j3...@yahoo.de> on 2002/06/23 20:13:12 UTC
Stylebook transition
Hi,
I'm currently reorganizing the FOP docs. The actual
version uses stylebook. I thought I replace this by
Ant's style task. This proved a bit more complicated
than expected, because of the transformation pipelines.
General questions:
- How are users building Apache software at home from
scratch supposed to generate documentation? Using
Cocoon CLI seems to be a bit large to expect.
- Should projects always provide prebuilt HTML even in
sourcce distributions?
- Should projects provide XDocs in binary distributions?
Apart fron this, I ended up with the following Ant target:
<target name="html-fop" depends="prepare-docs">
<mkdir dir="${build.htmldocs}"/>
<copy todir="${build.xdocs}">
<fileset dir="${xdocs}"
excludes="**/changes*,**/contributors*,**/faq*,**/howto*,**/todo*"/>
</copy>
<style basedir="${xdocs}"
destdir="${build.xdocs}"
includes="**/changes*.xml"
extension="xml"
style="${xdocs}/dtd/changes2document.xsl"/>
<style basedir="${xdocs}"
destdir="${build.xdocs}"
includes="**/contributors*.xml"
extension="xml"
style="${xdocs}/dtd/contributors2document.xsl"/>
<style basedir="${xdocs}"
destdir="${build.xdocs}"
includes="**/faq*.xml"
extension="xml"
style="${xdocs}/dtd/faq2document.xsl"/>
<style basedir="${xdocs}"
destdir="${build.xdocs}"
includes="**/howto*.xml"
extension="xml"
style="${xdocs}/dtd/howto2document.xsl"/>
<style basedir="${xdocs}"
destdir="${build.xdocs}"
includes="**/todo*.xml"
extension="xml"
style="${xdocs}/dtd/todo2document.xsl"/>
<style basedir="${build.xdocs}/fop"
destdir="${build.htmldocs}"
includes="*.xml"
style="${skin}/stylesheets/document2html.xsl"/>
</target>
This seems to be rather verbose and redundant. At least,
the naming conventions fit.
Question:
- Is it a good idea to tie processing to document name
conventions?
- Alternative ideas?
I could probably use Ant <echo> to simulate Cocoons directory
generator and do something useful with it.
Further questions:
- What is the canonical directory structure for xdocs?
changes, todo, contributors, faqs, howtos, specifications
(what is the intention for this?), other documentation.
Should subdirectories represent a project structure and
have their own changes, todos etc? Should subdirectories
represent document categories?
- What skins are projects supposed to distribute?
- What is the default skin (unless the project decides to
build its own skin, of course)?
J.Pietschmann
Re: Stylebook transition
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Steven Noels wrote:
> Nicola Ken Barozzi wrote:
>
>> Sure, the Centipede plugin is exactly that, a way to make Forrest easy
>> to use.
>> It will be made and distributed by this project, and usable by
>> centipede automatically.
>
>
> Nicola,
>
> what would be the impact for projects to integrate Centipede in their
> build process just for this purpose? I.e. a project using Maven or plain
> Ant and wanting to use Forrest for its local documentation builds and
> adding docs to their distributions. We can't make Centipede a necessity
> for people interested in Forrest but already using some other build
> environment.
I agree.
I said: " the Centipede plugin is exactly that,** a ** way to make
Forrest easy to use."
There will be other.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: Stylebook transition
Posted by Steven Noels <st...@outerthought.org>.
Nicola Ken Barozzi wrote:
> Sure, the Centipede plugin is exactly that, a way to make Forrest easy
> to use.
> It will be made and distributed by this project, and usable by centipede
> automatically.
Nicola,
what would be the impact for projects to integrate Centipede in their
build process just for this purpose? I.e. a project using Maven or plain
Ant and wanting to use Forrest for its local documentation builds and
adding docs to their distributions. We can't make Centipede a necessity
for people interested in Forrest but already using some other build
environment.
Regards,
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
stevenn@outerthought.org stevenn@apache.org
Re: Stylebook transition
Posted by Steven Noels <st...@outerthought.org>.
Nicola Ken Barozzi wrote:
>>>> Is there an HOWTO-easy-switch-to-forrest? In particular,
>>>> is there a package which can be distributed with a project
>>>> so that users can build their docs at home?
>>>
>> No, but we should definately make an effort to make one available from
>> this very project.
>
>
> Sure, the Centipede plugin is exactly that, a way to make Forrest easy
> to use.
> It will be made and distributed by this project, and usable by centipede
> automatically.
>
> Anyway, this will have to be voted on, the main point though is that
> Forrest will have this feature :-)
Forrest's main operational mode is server-side/cron-based right now, as
is Gump. I'm not sure on the deployment mode of Maven nor Anakia, but I
prefer to provide Forrest mainly as a centralized service, as the
forrestbot currently is. Forrest creating it's own forrest.cent has been
long on my wishlist, too, but I'd prefer to move forward in one
direction instead of being sidetracked in yet another direction. I
believe we will never end up with some sanitized and standardized
documentation tool if we don't lift the documentation build process out
of the concerned projects. Otherwise, people will fetch their copy of
Forrest, integrate it into their own project, patch it locally as
needed/to their liking and forget to give back to us. I'm not sure
whether cents will avoid this problem, while I see their usefullness.
Not sure however if we can expect from people to adopt Centipede for
doing some local docs building.
That being said, I'm -0 (gee, what a long explanation for a non-veto :-)
I agree we should compose some how-to as to how people can migrate their
documentation sources towards Forrest-compliancy, and that we should
upgrade forrestbot until it works for several projects, maybe adding the
option to build to a temporary location and giving projects the ability
to trigger a documentation run manually. I'm not so sure whether
projects would be interested in adding a hefty cocoon.jar to their lib
directory just for building docs, nor that Cocoon can be considerably
tuned down in size without losing required functionalities (and I
remember someone adding even more megabytes of fop stuff to CVS with the
message that that was also core to forrest ;-)
But maybe my -0 will change once I have enough free time to finish some
outstanding issues and work seriously on the Ant scripts (or Joerg goes
the extra mile, creates patches for his remarks on DTDs and XSLT instead
of mails, and I only have to apply them ;-)
OK - back to work now :-|
I'll be back!
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
stevenn@outerthought.org stevenn@apache.org
Re: Stylebook transition
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Stefano Mazzocchi wrote:
> Nicola Ken Barozzi wrote:
>
>>J.Pietschmann wrote:
>>>Is there an HOWTO-easy-switch-to-forrest? In particular,
>>>is there a package which can be distributed with a project
>>>so that users can build their docs at home?
>>
>
> No, but we should definately make an effort to make one available from
> this very project.
Sure, the Centipede plugin is exactly that, a way to make Forrest easy
to use.
It will be made and distributed by this project, and usable by centipede
automatically.
Anyway, this will have to be voted on, the main point though is that
Forrest will have this feature :-)
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: Stylebook transition
Posted by "J.Pietschmann" <j3...@yahoo.de>.
Stefano Mazzocchi wrote:
>>>I am bothered with stylebook, one issue being that I don't
>>>know anything about how it works.
>>
>
> Yes, I know that feeling.
Another isssue is that stylebook doesn't like Xerces 2.
> No, but we should definately make an effort to make one available from
> this very project.
Good!
J.Pietschmann
Re: Stylebook transition
Posted by Stefano Mazzocchi <st...@apache.org>.
Nicola Ken Barozzi wrote:
>
> J.Pietschmann wrote:
> > Stefano Mazzocchi wrote:
> >
> >> Then you start seeing why Cocoon is not just ant++ for xml.
> >
> >
> > I knew this already. The point was what follows:
> >
> >>> - How are users building Apache software at home from
> >>> scratch supposed to generate documentation? Using
> >>> Cocoon CLI seems to be a bit large to expect.
> >>
> >>
> >> Granted. But we could package a very simple cocoon-light.jar file which
> >> would not be bigger than 200Kb and requires you Xerces and Xalan, just
> >> like your ant scripts would.
> >
> > Do you have such a package at hand? Or some guidelines
> > how to get it (other than trial-and-error). Is avalon
> > included in the size calculation? FOP uses LogKit and
> > A-Framework, only Excalibur appears to be in need to be
> > added, but what about other projects?
>
> This is the list of jars used in the Forrest cent:
> http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/krysalis/krysalis-centipede/tools/cents/forrest.cent/lib/
>
> the biggest is cocoon with 1Mb, but taking out non-compulsory features
> it becomes much smaller.
Oh, totally. The scratchpad itself is 300Kb (and we don't use those in
Forrest), we also use just a very few sitemap components and we don't
use XSP and a bunch of those big avalon components that Cocoon has.
I think it's entirely possible to have a cocoon-light.jar package for
forrest which is just around 400Kb including Avalon Framework and the
components of Avalon Excalibur that we need.
I think that the forrest build file should create that cocoon-light.jar
package by itself and redistribute that.
> >> Why do you want to rewrite something that is already available? You were
> >> using stylebook and that didn't bother you that much, why switching to
> >> forrest is that painful?
> >
> > I am bothered with stylebook, one issue being that I don't
> > know anything about how it works.
Yes, I know that feeling.
> > Is there an HOWTO-easy-switch-to-forrest? In particular,
> > is there a package which can be distributed with a project
> > so that users can build their docs at home?
No, but we should definately make an effort to make one available from
this very project.
> Currently Centipede has a Forrest plugin(ie cent) that has this purpose,
> but it's of an older version.
> We are planning to use the newer Forrest as soon as the DTD is agreed on.
>
> --
> Nicola Ken Barozzi nicolaken@apache.org
> - verba volant, scripta manent -
> (discussions get forgotten, just code remains)
> ---------------------------------------------------------------------
--
Stefano Mazzocchi One must still have chaos in oneself to be
able to give birth to a dancing star.
<st...@apache.org> Friedrich Nietzsche
--------------------------------------------------------------------
Re: Stylebook transition
Posted by Nicola Ken Barozzi <ni...@apache.org>.
J.Pietschmann wrote:
> Stefano Mazzocchi wrote:
>
>> Then you start seeing why Cocoon is not just ant++ for xml.
>
>
> I knew this already. The point was what follows:
>
>>> - How are users building Apache software at home from
>>> scratch supposed to generate documentation? Using
>>> Cocoon CLI seems to be a bit large to expect.
>>
>>
>> Granted. But we could package a very simple cocoon-light.jar file which
>> would not be bigger than 200Kb and requires you Xerces and Xalan, just
>> like your ant scripts would.
>
> Do you have such a package at hand? Or some guidelines
> how to get it (other than trial-and-error). Is avalon
> included in the size calculation? FOP uses LogKit and
> A-Framework, only Excalibur appears to be in need to be
> added, but what about other projects?
This is the list of jars used in the Forrest cent:
http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/krysalis/krysalis-centipede/tools/cents/forrest.cent/lib/
the biggest is cocoon with 1Mb, but taking out non-compulsory features
it becomes much smaller.
>> Why do you want to rewrite something that is already available? You were
>> using stylebook and that didn't bother you that much, why switching to
>> forrest is that painful?
>
> I am bothered with stylebook, one issue being that I don't
> know anything about how it works.
>
> Is there an HOWTO-easy-switch-to-forrest? In particular,
> is there a package which can be distributed with a project
> so that users can build their docs at home?
Currently Centipede has a Forrest plugin(ie cent) that has this purpose,
but it's of an older version.
We are planning to use the newer Forrest as soon as the DTD is agreed on.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
How-To switch to Forrest
Posted by Ross Gardler <ro...@wkwyw.net>.
Diana Shannon wrote:
>
> On Tuesday, June 25, 2002, at 05:53 PM, J.Pietschmann wrote:
>
>> Is there an HOWTO-easy-switch-to-forrest? In particular,
>> is there a package which can be distributed with a project
>> so that users can build their docs at home?
>
>
> I recently discovered such a how-to (along with others) within Krysalis.
> It's a great start. I'm sure when Cocoon completes the transition
> process we'll have a lot of helpful content to add to such a doc. I
> know I have some ideas.
I am the author of the How-To's in Krysalis, if you want to take any
from there and stick them into Forrest I have no objects (and I am sure
Nicola won't either). However, at present, they are very simple and
cover the old version of Forrest in Centipede. I have not had the time
to keep up with the changes over here (DTD changes, tabs, libre etc.),
perhaps someone can help me along by updating them to reflect the
changes over here.
The how-to's in question are not yet live so if you want to read them
you need to get Centipede from CVS and look at them locally (Nicola, any
chance of updating the Centipede web site to save people the hassle?).
Ross
Re: Stylebook transition
Posted by Diana Shannon <sh...@apache.org>.
On Tuesday, June 25, 2002, at 05:53 PM, J.Pietschmann wrote:
> Is there an HOWTO-easy-switch-to-forrest? In particular,
> is there a package which can be distributed with a project
> so that users can build their docs at home?
I recently discovered such a how-to (along with others) within Krysalis.
It's a great start. I'm sure when Cocoon completes the transition
process we'll have a lot of helpful content to add to such a doc. I
know I have some ideas.
-- Diana
Re: Stylebook transition
Posted by "J.Pietschmann" <j3...@yahoo.de>.
Stefano Mazzocchi wrote:
> Then you start seeing why Cocoon is not just ant++ for xml.
I knew this already. The point was what follows:
>>- How are users building Apache software at home from
>> scratch supposed to generate documentation? Using
>> Cocoon CLI seems to be a bit large to expect.
>
> Granted. But we could package a very simple cocoon-light.jar file which
> would not be bigger than 200Kb and requires you Xerces and Xalan, just
> like your ant scripts would.
Do you have such a package at hand? Or some guidelines
how to get it (other than trial-and-error). Is avalon
included in the size calculation? FOP uses LogKit and
A-Framework, only Excalibur appears to be in need to be
added, but what about other projects?
> Why do you want to rewrite something that is already available? You were
> using stylebook and that didn't bother you that much, why switching to
> forrest is that painful?
I am bothered with stylebook, one issue being that I don't
know anything about how it works.
Is there an HOWTO-easy-switch-to-forrest? In particular,
is there a package which can be distributed with a project
so that users can build their docs at home?
J.Pietschmann
Re: Stylebook transition
Posted by Stefano Mazzocchi <st...@apache.org>.
"J.Pietschmann" wrote:
>
> Hi,
> I'm currently reorganizing the FOP docs. The actual
> version uses stylebook. I thought I replace this by
> Ant's style task. This proved a bit more complicated
> than expected, because of the transformation pipelines.
Then you start seeing why Cocoon is not just ant++ for xml.
> General questions:
> - How are users building Apache software at home from
> scratch supposed to generate documentation? Using
> Cocoon CLI seems to be a bit large to expect.
Granted. But we could package a very simple cocoon-light.jar file which
would not be bigger than 200Kb and requires you Xerces and Xalan, just
like your ant scripts would.
> - Should projects always provide prebuilt HTML even in
> sourcce distributions?
Each project decides that.
> - Should projects provide XDocs in binary distributions?
Same as above.
> Apart fron this, I ended up with the following Ant target:
>
> <target name="html-fop" depends="prepare-docs">
> <mkdir dir="${build.htmldocs}"/>
> <copy todir="${build.xdocs}">
> <fileset dir="${xdocs}"
> excludes="**/changes*,**/contributors*,**/faq*,**/howto*,**/todo*"/>
> </copy>
> <style basedir="${xdocs}"
> destdir="${build.xdocs}"
> includes="**/changes*.xml"
> extension="xml"
> style="${xdocs}/dtd/changes2document.xsl"/>
> <style basedir="${xdocs}"
> destdir="${build.xdocs}"
> includes="**/contributors*.xml"
> extension="xml"
> style="${xdocs}/dtd/contributors2document.xsl"/>
> <style basedir="${xdocs}"
> destdir="${build.xdocs}"
> includes="**/faq*.xml"
> extension="xml"
> style="${xdocs}/dtd/faq2document.xsl"/>
> <style basedir="${xdocs}"
> destdir="${build.xdocs}"
> includes="**/howto*.xml"
> extension="xml"
> style="${xdocs}/dtd/howto2document.xsl"/>
> <style basedir="${xdocs}"
> destdir="${build.xdocs}"
> includes="**/todo*.xml"
> extension="xml"
> style="${xdocs}/dtd/todo2document.xsl"/>
> <style basedir="${build.xdocs}/fop"
> destdir="${build.htmldocs}"
> includes="*.xml"
> style="${skin}/stylesheets/document2html.xsl"/>
> </target>
>
> This seems to be rather verbose and redundant. At least,
> the naming conventions fit.
>
> Question:
> - Is it a good idea to tie processing to document name
> conventions?
> - Alternative ideas?
>
> I could probably use Ant <echo> to simulate Cocoons directory
> generator and do something useful with it.
Why do you want to rewrite something that is already available? You were
using stylebook and that didn't bother you that much, why switching to
forrest is that painful?
--
Stefano Mazzocchi One must still have chaos in oneself to be
able to give birth to a dancing star.
<st...@apache.org> Friedrich Nietzsche
--------------------------------------------------------------------