Re: Docbook notes

Hi Bram

> I suppose I'll be looking for a tool to do the conversion then.

I don't *think* you need to change anything in the markup itself.
Hopefully only the DOCTYPE at the top of the file. 

> XML is a nice format for computers, not for humans!

Agreed, although writing DocBook XML is miles away from machine-
oriented XML like SOAP.  Bibliographies and complicated tables
can get pretty hairy, but I found the markup was mostly quite 
light; lighter than HTML, certainly. 

You probably don't really need to write the docs directly in 
full-blown DocBook anyway. There are some alternatives. I'll 
list a couple. 

1. StructuredText

The Zope Book 
  http://www.zope.org/Documentation/Books/ZopeBook/
is written in StructuredText and converted from there to DocBook,
among other formats. 

Here is a very short recipe for converting STX to DocBook:
http://vsbabu.org/mt/archives/2002/11/12/docbook_for_programmers.html
Basically::

 st=StructuredText.Basic(raw)
 doc=StructuredText.Document(st)
 html=StructuredText.HTML(doc)
 docbook = StructuredText.DocBookArticle(doc)

Here is the Zope Book project at SourceForge:
  http://sourceforge.net/projects/zope-book
  http://cvs.zope.org/Packages/StructuredText/

There's another implementation of this idea, called 
reStructuredText. Here's an article about that, including mention
of conversion to DocBook:
  http://www-106.ibm.com/developerworks/library/x-matters24/?ca=dnt-45

Going from DocBook -> StructuredText will be a bit of a pain,
if you decide to go that route, certainly. But I think you'll
like StructuredText. Do you know it? It's similar to the 
plaintext-with-conventions of the Vim helpfiles. 

2. DocBook Lite

DocBookLite is a DocBook subset. It's used by O'Reilly to format
its books. It is also used by the subversion project.
  http://www.docbook.org/wiki/moin.cgi/DocBookLite

-- 
Jean Jordaan
http://www.upfrontsystems.co.za



-------------------------------------------------------
This SF.Net email sponsored by: Free pre-built ASP.NET sites including
Data Reports, E-commerce, Portals, and Forums are available now.
Download today and enter to win an XBOX or Visual Studio .NET.
http://aspnet.click-url.com/go/psa00100003ave/direct;at.aspnet_072303_01/01