I agree 100% with the two requirements listed below.
DocBook, which was designed largely for technical documentation,
articles, and books, is also used by O'Reilly for many of their
technical books, and is widely supported by XML tools. The stylesheets
for conversion to HTML and PDF are widely available and are
customizable. The Boost folks have created a DTD called BoostBook [1]
which extends DocBook to provide explicit support for C++ libraries,
specifically to add support for C++ constructs such as namespaces,
classes, overloaded functions, templates, and specializations. It also
has some support for coordinating program examples with test suites. I'm
not sure whether we should use the BoostBook extensions or not, but we
should look into that question. I'm not sure whether BoostBook currently
has stylesheets for generating PDF - these are widely available for DocBook.
With either DocBook or BoostBook, we may want to consider simplifying
the DTD by creating a subset - that will make it simpler for authors,
and result in better document consistency by preventing people from
doing the same thing in different ways.
We should probably divide the document into entities to make version
control easier.
I don't think Forrest is an alternative to DocBook, DocBook is one
format you can use when generating documents with Forrest. Forrest is an
integration and publishing framework, and it may be overkill for our
documentation project. I'd be inclined to start just using ant files to
build documents, and get fancier if we need to.
Do we plan to publish API documentation with this system too, or will we
rely on doxygen / javadoc / pydoc / whatever Ruby or other languages use?
Jonathan
Hi all,
I think it is perhaps worth reconsidering how we generate our
documentation. I think it would be good to have an approach that
supported the following:
1) storing the documentation "source" in svn, with the code. That
means it can be versioned and diffed easily
2) ability to generate at high quality HTML and PDF versions of the
documentation
The Hibernate and Spring projects use docbook as a format and IMO
their documentation is excellent.
One other option I have heard mentioned is Forrest
(http://forrest.apache.org) but I don't have any experience of that.
Can anyone share any opinions of it?
RG
