Creating Doocbook Documents from the Moin wiki

This page notes some experiences trying to create a formal document using the Moin wiki Docbook export capability.

Contents:

Contents

Docbook export from Moin
About Docbook
Using the Moin wiki docbook output
Sample template for document with Table of Contents
References

1. Docbook export from Moin

This bit is easy. Onder "More actions:" select "Render as Docbook". This is provided with Moin version 1.5.3.

The XML exported is pretty straightforward, but does not contain any DTD of namespace declarations thatb allow the XML output to be definitively identified as Docbook format.

The output does not seem to include a table of contents for the exported page, even when the actual wiki page has such a table. The output is preented as a single <section>, without further wrapping.

2. About Docbook

Docbook is an OASIS-specified XML language for describing formal documents, books, articles, etc. A kind of nroff or LATeX for the XML world. See:

There's a useful page about Docbook authoring tools here:

http://wiki.docbook.org/topic/DocBookAuthoringTools

and other Docbook tools:

http://wiki.docbook.org/topic/DocBookTools

3. Using the Moin wiki docbook output

I tried a couple of utilities downloaded from the Web:

Oxygen http://www.oxygenxml.com/ - appears to be a very competent but non-WYSIWYG editor for arbitrary XML, but does have Docbook conversion support built-in. It objected to the docbook output generated by Moin, claiming that <listitem> elements contained spurious text. It does have a few Docbook examples as part of the installation package.
It appears the problem is that Moin generates <listitem> tags without contained <para> elements tags.. When this was fixed up, and a few other changes made, I was able to generate PDF directly from Oxygen (using CTRL-SHIFT-C and selecting the Docbook-to-PDF scenario).
XXE standard edition http://www.xmlmind.com/xmleditor - seems to handle the wiki output nicely, but is not immediately obvious how to manipulate the document structure. I couldn't quickly figure how to insert a table of contents at the top of the document. The PDF output in the free XXE stamndard edition does not work, I think because of the restrictions on formatting objects (FOP?).
Lyx http://www.lyx.org/ - has been reported to me as an effective tool (apparently edits LATeX and Docbook, among others). This does not work out of the box. I've installed LyX under Windows, and it seems to be running fine with !MikTeX, ImageMagick and a collection of other tools it decided to install. But it still doesn't recognize Docbook files. Apparently, there is a further collection of tools that need to be installed for all this to work: http://bgu.chez-alice.fr/doc/db4lyx/; I'm out of time to pursue this now.

4. Sample template for document with Table of Contents

This is just a starting point - not complete or optimal, but it does seem to be a valid Docbook structure.

<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
<book>
  <article>
    <title>A title</title>
    <subtitle>A subtitle</subtitle>
    <articleinfo>
      <title>Article info</title>
    </articleinfo>
    <para>
      <emphasis>Introductory material</emphasis>
    </para>

    <section>
      <title>Section title</title>
      <para>Body content</para>
    </section>

    <Section>
      :
    </Section>

    <toc/>
  </article>
</book>

5. References

-- GrahamKlyne 2006-10-25 12:41:51