Yea I've seen other projects use this. What would be nice is if we
could write using a word processor instead of an xml editor and have
it converted to DocBook. I'll have to check into this but if someone
has experience doing this sort of thing, it would be good to know.
Jim
On Jul 20, 2006, at 2:07 AM, Eric Le Goff wrote:
Let's try and summarize docbook features :
DocBook is an XML vocabulary designed for computer
documentation.DocBook has historically been SGML, but DocBook 4 is
supported in XML and SGML DTDs.
It is the work product of an OASIS Technical Committee [1]
I started learning it from [2], just like writing a simple book :
<book id="simple_book">
<title>Very simple book</title>
<chapter id="simplechapter">
<title>Chapter 1</title>
<para>Hello world!</para>
</chapter>
</book>
then learned more advanced syntax fro a reference card [3].
You can write technical documents with Open Office, and save them in
html or pdf.
But the interest of DocBook is in separating data and presenting, the
possibility to create automatically documents, and the ability to
generate documents from databases. Can convert them to html or pdf
also.
You can also process the data in several ways (extracting, multiple
views, etc...)
DocBook is now used for the documentation of Linux and FreeBSD.
I think people wrote a maven plugin for docbook generation [4]
A text may be edited directly, or with a graphical editor (see [5],
[6]). I personnaly use Emacs with psgml mode as described here [8],
but I also know some people using OpenOffice as an editor [8]
For a manual conversion process, some tools are required:
* The DocBook DTD
* The XSL DocBook style sheet.
* The XSLT processor.
Some style sheet allows to produce HTML or XSL-FO from a DocBook
document.
With the FOP program and the XSL-FO [9] , a pdf file is created with
this command (in one line):
java org.apache.fop.apps.Fop
-xml myfile.xml
-xsl DocBook-xsl/fo/DocBook.xsl
-pdf myfile.pdf
Aaron Mulder from the Apache Geronimo team wrote a book available in
several formats [10] and I suppose he had used Docbook. He might
confirm how useful it is to use this format to generate docs...or give
us hid feedback, pros and cons of such a tool in the context of an
incubating Apache project...
Regards
[1] http://www.oasis-open.org/docbook/
[2] http://camille.begnis.org/publications/DocBook/DocBook-Starter-
Kit.tar.bz2
[3] http://www.dpawson.co.uk/docbook/docbookref.pdf
[4] http://mojo.codehaus.org/docbook-maven-plugin/
[5] http://www.xmlmind.com/
[6] http://www.lyx.org/
[7] http://fedora.redhat.com/docs/documentation-guide/
[8] http://xml.openoffice.org/xmerge/docbook/UserGuide.html
[9] http://xmlgraphics.apache.org/fop/
[10] http://chariotsolutions.com/geronimo/
--
Eric LE GOFF
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
