You are viewing a plain text version of this content. The canonical link for it is here.
Posted to general@xml.apache.org by Jason van Zyl <jv...@apache.org> on 2001/07/20 18:20:08 UTC
Using C2 for docs
Hi,
I'm working on the xmlrpc docs, and I would like to be a C2 guinea pig :-)
I will take a look at the avalon docs as an example and go from there.
Berin, can you put something in place for xml.apache.org so I can
transform the xml docs when I'm done? I'm in no real rush, and I'm
willing to try the dogfood.
I've never used C2 so I can't say how it compares to Anakia, but
I won't know until I go through the process. I am willing to
give it a shot.
Have we arrived at a location for the documentation? I've looked
at xerces, xml-axis and c2 and they all have different setups:
docs/ with xml inside
docs/ with html inside
xdocs/ with xml inside
I would assume that xdocs/ with xml inside will be the standard?
I'm willing to try the system whenever it is in place.
--
jvz.
Jason van Zyl
http://tambora.zenplex.org
http://jakarta.apache.org/turbine
http://jakarta.apache.org/velocity
http://jakarta.apache.org/alexandria
http://jakarta.apache.org/commons
---------------------------------------------------------------------
In case of troubles, e-mail: webmaster@xml.apache.org
To unsubscribe, e-mail: general-unsubscribe@xml.apache.org
For additional commands, e-mail: general-help@xml.apache.org
Re: Using C2 for docs
Posted by Arved Sandstrom <Ar...@chebucto.ns.ca>.
At 02:41 PM 7/20/01 -0400, Berin Loritsch wrote:
>Call to FOP guys:
>
>If you can come up with a DocBook to XSL:FO markup stylesheet that is
>standard to all projects, it would help out tremendously. Start with
>the docbook2xhtml.xsl stylesheet I have in Avalon's CVS (as it has the
>subset of DocBook we would most be concerned with).
>
>Why did I come up with my own stylesheet instead of using Norman Walsh's?
>Because for me it was easier. I have looked at Norman's stylesheets, and
>I quickly get lost due to all the logic he puts in there to automatically
>spit out transformed files. 90% of what we need can be produced with 10%
>of the effort that goes into Norman's sheets. The remaining 10% (that
>takes up the remaining 90% of the effort) can be added as we need it.
Can do. I'll put it out as another request on fop-dev, because, after all,
not everyone is on this list.
There are 2 reasons we need a somewhat customized stylesheet:
1) FOP is immature: it will not handle everything that Norm's DocBook->FO
stylesheets produce, although with your simplified/reduced docbook2xhtml.xsl
stylesheet this may not be too bad; and
2) the DocBook -> XSL-FO stylesheets are themselves immature at this point;
there are a number of DocBook elements that, once transformed, produce FO
that doesn't look all that hot even with AntennaHouse XSLFormatter or
RenderX XEP, let alone FOP.
Regards,
Arved Sandstrom
Fairly Senior Software Type
e-plicity (http://www.e-plicity.com)
Wireless * B2B * J2EE * XML --- Halifax, Nova Scotia
---------------------------------------------------------------------
In case of troubles, e-mail: webmaster@xml.apache.org
To unsubscribe, e-mail: general-unsubscribe@xml.apache.org
For additional commands, e-mail: general-help@xml.apache.org
Re: Using C2 for docs
Posted by cm...@yahoo.com.
On Fri, 20 Jul 2001, Berin Loritsch wrote:
> Why DocBook? Asside from being a standard, there are numerous tools
> that work with the DocBook standard (including writing documentation
> in a WYSIWYG environment). I hope to get PDF generation of the site
> working as well.
Until this is done you can of course use db2pdf, db2rtf, db2dvi, db2ps -
on any linux machine ( I suppose most unixes as well ).
Costin
---------------------------------------------------------------------
In case of troubles, e-mail: webmaster@xml.apache.org
To unsubscribe, e-mail: general-unsubscribe@xml.apache.org
For additional commands, e-mail: general-help@xml.apache.org
Re: Using C2 for docs
Posted by Berin Loritsch <bl...@apache.org>.
Jason van Zyl wrote:
>
> Hi,
>
> I'm working on the xmlrpc docs, and I would like to be a C2 guinea pig :-)
>
> I will take a look at the avalon docs as an example and go from there.
>
> Berin, can you put something in place for xml.apache.org so I can
> transform the xml docs when I'm done? I'm in no real rush, and I'm
> willing to try the dogfood.
There is a file called site2xhtml.xsl. This is in XHTML markup with
a couple of tags to transform the menu and the body. Start by getting
the source for xml.apache.org, and hollow it out so that you know
where the menu goes, and where the body goes. You will have to make
sure that the markup is proper XHTML.
The next process is to convert the book2menu.xsl file to produce the
proper fragment that goes in there.
The problem with xml.apache.org is that it is very graphics intensive,
and even has some generated images. I am no expert in SVG, but you
would use that to create the images.
> I've never used C2 so I can't say how it compares to Anakia, but
> I won't know until I go through the process. I am willing to
> give it a shot.
Well, I will admint that Cocoon's command line opperation can be
improved a little bit--and a very important an necessary feature
will be added soon. This is the ability to list the URLs in a file
and have Cocoon transform them.
As to performance:
Cocoon can run ant, start up a new VM and execute Cocoon, compile the
sitemap, and transform the entire Avalon site in less than 30 seconds
on my machine. It will slow down considerably when you include SVG
image generation to the mix--but hey, that's something Anakia can't
do anyway.
> Have we arrived at a location for the documentation? I've looked
> at xerces, xml-axis and c2 and they all have different setups:
>
> docs/ with xml inside
> docs/ with html inside
> xdocs/ with xml inside
When using Cocoon, I would advocate creating a "pseudo-context" for
your documentation.
documentation/xdocs (with xml inside)
documentation/stylesheets (with stylesheets for the site)
documentation/resources (with images/whatever else)
Note that the sitemap included in the Avalon documentation directory
won't need to change much to accomodate the xml.apache.org site.
> I would assume that xdocs/ with xml inside will be the standard?
I believe that this is best. The name of the directory infers xml
documentation.
> I'm willing to try the system whenever it is in place.
The Avalon site has the system in place--using both the "document"
markup associated with Stylebook, and the official DocBook 4.1
markup. In fact, there is a stylesheet to convert stylebook markup
to DocBook markup included!
The Avalon project just hasn't gotten around to converting all the
docs to DocBook.
Why DocBook? Asside from being a standard, there are numerous tools
that work with the DocBook standard (including writing documentation
in a WYSIWYG environment). I hope to get PDF generation of the site
working as well.
Call to FOP guys:
If you can come up with a DocBook to XSL:FO markup stylesheet that is
standard to all projects, it would help out tremendously. Start with
the docbook2xhtml.xsl stylesheet I have in Avalon's CVS (as it has the
subset of DocBook we would most be concerned with).
Why did I come up with my own stylesheet instead of using Norman Walsh's?
Because for me it was easier. I have looked at Norman's stylesheets, and
I quickly get lost due to all the logic he puts in there to automatically
spit out transformed files. 90% of what we need can be produced with 10%
of the effort that goes into Norman's sheets. The remaining 10% (that
takes up the remaining 90% of the effort) can be added as we need it.