ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jful...@ruminate.co.uk
Subject Re: Ant documentation
Date Wed, 09 Mar 2005 10:20:47 GMT
> > The main problem here is that there is no unique answer 8-)
> > 
> > My guess is the following is more or less true:
> > 
> > (1) autogenerate as much of the docs as possible from the Java sources.

yes within reason

> > (2) throw in additional information in an easy to edit format.

I would further seperate this;

I have proposed for tasks a task xml markup, will be posting my results soon on this.

perhaps with libraries, there is a need for a minimal libary ,metadata as well.
 
Note, after all this discussion, I am going to opt for a minimal subset of docbook to mark
these up. IMHO its very easy to start marking up with limited docbook set of elements...also
I would contend that there are much more people using docbook then xdocs on the planet...though
we would have to ask NWALSH this question.

> > (3) create HTML and PDF versions of the docs from a single source.

I would suggest to achieve maximum flexibility e.g. ability to work in both docbook and xdocs
whilst being able to generate PDF to follow Forrests recc. on this.

A) there is a docbook -> xdocs transform for those who want to work in a limited subset
of docbook.

or

B) you could configure forrest to work with native docbook.

I would scale the effort and initially go for option A) which means that some of the docs
can be in limited docbook format and some in native xdoc. Perhaps the natural breakdown is
that xdoc deals with core Ant, with limited docbook with tasks, library metadata....going
to pdf could be end result of xdoc processing by Forrest.

-- Jim Fuller

--------------------------------------------------------------------------------

FYI: from Forrest site FAQ
http://forrest.apache.org/faq.html#docbook

Forrest can transform the DocBook format into the Forrest "xdocs" format on-the-fly and then
render that as normal Forrest documents. Be aware that the stylesheet that does this transformation
is deliberately very limited and does not attempt to deal with all DocBook elements.

The other way is to use the full DocBook stylesheets directly. The DocBook DTDs are shipped
with Forrest and automatically handled. However, you will need to have the DocBook stylesheets
on your system (they are too massive to ship with Forrest) and configure Forrest accordingly.
You will need to create a project sitemap as explained in Using Forrest and add matches to
handle your DocBook documents. Here is an example. Note that you need to change it to suit
your situation. The match must be very specific so that only the DocBook documents are matched.
The rest of the documents will be handled by Forrest core. Powerful regex capabilities are
available.

<?xml version="1.0"?>
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
 <map:pipelines>
  <map:pipeline>
   <map:match pattern="resolver-*.html">
    <map:generate src="{project:content.xdocs}resolver-{1}.xml"/>
    <map:transform
      src="file:///usr/share/sgml/docbook/xsl-stylesheets/xhtml/docbook.xsl"/>
    <map:serialize type="xhtml"/>
   </map:match>
  </map:pipeline>
 </map:pipelines>
</map:sitemap>
        

You can also use a mixture of the two methods, some handled automatically by Forrest and some
directly using DocBook stylesheets. You can also have a mixture of source files as "document-v*"
DTD and DocBook.

Ensure that the document type declaration in your xml instance is well specified. Use a public
identifier. The DTD will then be properly resolved by Forrest. If you need to use different
DTDs, then see Using Forrest for configuration guidance.


Mime
View raw message