Description of the a2m XSL Transform

Note: The moin markup for this page was generated automatically from the xml file by the tools described below. The original xml is in the Docteam's Subversion repository. However, feel free to make any changes and additions and suggestions to the moin on this page.

Introduction

This article describes the DocBook Article markup to Moin markup (a2m) experimental toolset that has been constructed for automatic generation of moin wiki pages. The a2m toolset is an xml-based valid subset of DocBook. It consists of a Document Type Definition (DTD), an Extensible Stylesheet Language for Transformations (XSLT) template, and a makefile. The makefile is not essential to the use of the toolset. However, it does simplify the process of transforming an a2m document into a wiki moin document. The makefile should probably be replaced by a shell script at some point.

The a2m toolset will probably only be useful for documents that are more or less static, or at least change infrequently, and for one reason or another are kept under revision control in the Subversion repository. It will be most useful for policy documents such as style guides and documentation handbooks, as well as short howto documents and the like. It would be inappropriate for the Ubuntu User Guide and other large, book-length documents. It would also be useful for quickly transferring content from several wiki sources into larger DocBook publications.

The a2m subset is valid DocBook article markup. This is important because it means that a valid a2m document can be processed by existing DocBook tools into html, pdf, and other formats.

Note: Keep in mind that a2m is only a tiny subset of the full DocBook set of elements. This is necessary for two reasons: 1) to keep the tool as simple as possible, and 2) to make automated round-tripping possible (a2m->moin->a2m).

Purpose of the a2m Toolset

The intent of the toolset is to provide a minimal and simplified valid subset of the DocBook xml standard markup which can be used to automatically generate moin markup for use on the Ubuntu wiki. Eventually, a2m may become part of a larger toolset for round-tripping documents from DocBook to Moin and back to DocBook.

Caution: The a2m is experimental only. It may not work. It may work but end up not being used by anyone. Files that are processed without problem today may not process at all tomorrow.

Where to Get the a2m Toolset

The toolset is currently in the Docteam's Subversion repository in the teamstuff folder. See DocteamStepByStepRepository. Alternatively, the DTD and XSLT template used to create this page is copied below, in the appendix. However, they are there for demonstration purposes and are likely to be out of date.

A Minimal a2m Document

Here is a minimal valid a2m document:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" 
        "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" []>
<article>
<title>A minimal valid a2m document</title>
<sect1>
  <title>This is a heading 2</title>
  <para>This is a paragraph</para>
</sect1>
</article>

Note that the document is declared with the DocBook DTD. This is to ensure that any a2m document is also valid DocBook. The document can be validated against the a2m DTD by passing the location of the DTD to an xslt validator such as xmllint.

Here is the moin markup generated using the above DocBook article:

## Generator: a2m.xslt Version 0.1.0 
= A minimal valid a2m document =
== This is a heading 2 ==
This is a paragraph

Supported DocBook Article Elements

Block Level Elements

Block level elements are elements which typically start on new lines with space before and space after. Headings and paragraphs are block level elements.

• sect1, sect2, sect3, sect4
• title, para
• caution, important, note, tip, warning
• table, informaltable
• programlisting, literallayout
• itemizedlist, orderedlist, listitem

Inline Elements

Inline elements typically get converted to bold, italic, or a combination of the two. In valid a2m, inline elements are always within <para></para> tags.

• application
• command
• menuchoice (guimenu, guisubmenu, guimenuitem)
• subscript, superscript
• citetitle
• emphasis (defaults to italic), emphasis role="bold"
• filename

Needed DocBook Article Elements

Here is a list of elements that are not yet implemented. These elements are needed to complete the a2m toolset.

• articleinfo, authorgroup, legalnotice
• mediaobject, inlinemediaobject (imageobject, imagedata)
• qandaset
• screen
• ulink

Quick Guide to a2m Markup

Here is a quick guide to using the a2m tools. A more detailed and useful howto can be created if the a2m idea catches on.

Sections and Titles

There are 5 levels supported in a2m. The top level is of course the article element. The 4 sub levels are: sect1, sect2, sect3, and sect4. Each level has one title element. It is the title element that gets rendered as moin headings. Title elements are mandatory. To demonstrate, here is a repeat of a minimal a2m document:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" 
        "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" []>
<article>
<title>A minimal valid a2m document</title>
<sect1>
  <title>This is a heading 2</title>
  <para>This is a paragraph</para>
</sect1>
</article>

In a2m, article titles are given moin Heading 1, sect1 titles are given Heading 2, sect2 titles are given Heading 3, and so on.

Lists

Ordered and itemized lists have almost identical markup. The only difference is the opening tags: <orderedlist> and <itemizedlist>. Here is a sample of an ordered list:

<orderedlist>
  <listitem>
    <para>list item 1</para>
    <orderedlist>
      <listitem>
        <para>sub item 1</para>
      </listitem>
      <listitem>
        <para>sub item 2</para>
      </listitem>
  </orderedlist>
  </listitem>
  <listitem>
    <para>list item 2</para>
  </listitem>
  <listitem>
    <para>list item 3</para>
  </listitem>
</orderedlist>

This is what the above list looks like when rendered in moin on this wiki:

1. list item 1
   1. sub item 1
   2. sub item 2
2. list item 2
3. list item 3

Note: Currently, a2m only supports lists up to two levels deep.

Menu Selections

Menu selections are rendered as inline elements. Here is how to do a menu selection:

<para>To start the Ubuntu Update Manager, choose
  <menuchoice>
    <guimenu>System</guimenu>
    <guisubmenu>Administration</guisubmenu>
    <guimenuitem>Ubuntu Update Manager</guimenuitem>
  </menuchoice>
</para>

Here is how the above markup looks in this wiki:

To start the Ubuntu Update Manager, choose System->Administration->Ubuntu Update Manager

Admonitions

Admonitions are block elements. The admonitions supported in a2m are: caution, important, note, tip, and warning. The only child element available for admonitions is the para element. Here is a sample of a note:

<note>
  <para>The only child element for the note admonition is the para element. Of
  course, you can also use the usual inline markup such as
  <emphasis>emphasis</emphasis> and <filename>filename</filename>.</para>
</note>

Here is what the above note admonition looks like when rendered in this wiki:

Note: The only child element for the note admonition is the para element. Of course, you can also use the usual inline markup such as emphasis and filename.

Tables and InformalTables

Rudimentary support for <table> and <informaltable> is provided. Here is a sample:

<table>
  <title>Title of the Table</title>
  <tgroup cols="3">
  <thead>
    <row>
      <entry>head 1</entry>
      <entry>head 2</entry>
      <entry>head 3</entry>
    </row>
  </thead>
  <tbody>
    <row>
      <entry>col 1</entry>
      <entry>col 2</entry>
      <entry>column 3</entry>
    </row>
  </tbody>
</tgroup>
</table>

Here is how the above markup renders:

Quick Guide to the a2m Toolset

The initial toolset consists of the a2m DTD (a2m.dtd), the XSLT template (a2m.xslt), and a Makefile (makefile).

Note: There is also the file udp-pdf.xsl, which is a customization layer for creating PDFs of DocBook documents.

Here is the makefile:

INFILE = a2m-desc.xml
OUTFILE = a2m-desc
STYLESHEET = a2m.xslt
#STYLESHEET_HTML = /usr/share/xml/docbook/stylesheet/ldp/html/tldp-one-page.xsl
STYLESHEET_HTML = /usr/share/xml/docbook/stylesheet/nwalsh/html/docbook.xsl
PDFSTYLE = udp-pdf.xsl
DTD1 = a2m.dtd
DTD2 = /usr/share/xml/docbook/schema/dtd/4.3/docbookx.dtd

validate:
  xmllint --dtdvalid $(DTD1) --noout --xinclude --noent --postvalid $(INFILE)
  xmllint --dtdvalid $(DTD2) --noout --xinclude --noent --postvalid $(INFILE)

moin: validate
  xsltproc -o $(OUTFILE).txt $(STYLESHEET) $(INFILE)
# java org.apache.xalan.xslt.Process -IN $(INFILE) -XSL $(STYLESHEET) -OUT $(OUTFILE).txt

html: validate
  xsltproc -o $(OUTFILE).html $(STYLESHEET_HTML) $(INFILE)

pdf: validate
  xsltproc -o $(OUTFILE).fo $(PDFSTYLE) $(INFILE)
  fop.sh -fo $(OUTFILE).fo -pdf $(OUTFILE).pdf
  rm $(OUTFILE).fo

To use the makefile, change the INFILE and OUTFILE to your own document's name, and then type make moin at the command line. Similarly, you can create HTML and PDF documents by typing make html and make pdf respectively.

If you only want to validate your a2m xml file, then you only need to type make at the command line.

Naturally, you have to make sure all the appropriate files are in the current working directory when you use the make command.

Note: The makefile should probably be replaced by a shell script at some point.

Open Issues

The biggest impediment is the loss of information when transforming a2m to Moin: a couple of a2m elements get transformed into fixed width font. When it comes to converting that fixed width font from Moin back to a2m, it is impossible to know which one of the original a2m elements to transform the fixed width text into. For example, both filename and command elements get converted to fixed width font during the a2m->moin transform. While transforming the moin back to a2m, the script (or however it gets done) has no easy way of knowing whether the fixed width font it has just encountered should be transformed to a filename or a command element.

An a2m file does not open in Yelp. Yelp complains that section '(null)' is missing.

The Future

Who knows? This is just an experiment to see whether or not round-tripping is possible. The a2m tools only provide one aspect of that trip, namely the a2m->wiki transform. The wiki->a2m will be more challenging, but not impossible, provided that a2m is limited in its support of DocBook elements.

CategoryDocteam