[Doc-SIG] Docbook output

[David Goodger]

Dethe Elza wrote:
> Has any work been done to create DocBook output from reST input?

I don't think so.  Welcome!

> If not, where would I begin if I wanted to tackle such a thing?

First, make sure you're using the latest Docutils from CVS.  Either
get the files directly from CVS (instructions here:
http://sourceforge.net/cvs/?group_id=38414), or get the latest
snapshot (http://docutils.sourceforge.net/docutils-snapshot.tgz).

Second, take a look at docutils/writers/html4css1.py, which is the
only complete output writer so far.  It uses the "Visitor" design
pattern to do walk the document tree.

Third, join the Docutils-specific mailing lists:

- docutils-develop, for implementation discussions:
  http://lists.sf.net/lists/listinfo/docutils-develop/

- docutils-checkins, for CVS checkin messages (normally read-only):
  http://lists.sf.net/lists/listinfo/docutils-checkins/

(Join Doc-SIG too; high-level discussions take place here.)

Finally, ask lots of questions.  The internals are not well documented
yet; your questions will help to fill the gaps.

> I'm actually interested in three output formats ... :
>
> * DocBook
> * Simplified DocBook
> * XMLspec (the format W3C docs are written in)

Great!  I know DocBook quite well (as do many others, I'm sure), so we
will be able to help conceptually map Docutils nodes to DocBook
elements.  It should be easy.  I don't know anything about XMLspec.

> (in addition to XHTML and PDF, which appear to be well in hand)

Englebert Gruber began work on PDF (via ReportLabs), but it still
needs a lot of work.  Englebert, what are your plans?

Oliver Rutherfurd wrote:
> I just started on a docbook writer yesterday evening.
...
> Anyway, if I don't stall out or hit any big roadblocks, I'll try to
> make something available later this weekend.

That's great!  I look forward to seeing it.  Let us know if you run
into any trouble.  I'll be checking mail over the weekend.

And welcome!

> One question I had was what type of document(s) to generate?
> 
> - book
> - chapter
> - article
> 
> It would be nice if all 3 could be generated based on a parameter
> given to the writer, but given my lack of experience w/DocBook I
> don't know if this is feasible.

You could add command-line options to choose the top-level element of
the DocBook output.  Articles and chapters contain sections, and books
contain chapters.

But I wouldn't worry about it for now.  Choose one (article seems
best); we can add bells & whistles later.

-- 
David Goodger  <goodger@users.sourceforge.net>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/