wt2db - converts WikiText documents into DocBook XML/SGML.
wt2db [OPTION] [FILE]
wt2db converts a text file in a special format similar to that used in WikiWikiWebs into DocBook XML/SGML. The DocBook it writes out by default is only a fragment, but it will write a complete document upon request.
By default it reads from STDIN and writes to STDOUT. However, if given a filename, it will read that file, and an output filename can also be specified as a command-line option.
-s, --sgml add SGML DOCTYPE and article tags.
-x, --xml add XML DOCTYPE and article tags.
-f, --faq make the article a FAQ.
-e, --encoding specify the document encoding.
-n, --nonet do not access the network.
-o, --output-to filename write to the specified file.
-V, --verbose show diagnostic output.
-v, --version show program version.
-h, --help show a usage message.
wt2db was originally developed to convert articles from the Wikipedia into DocBook for republishing at the LDP. As development proceeded, I realized that it could be used to provide an easier way to write DocBook documentation.
WikiText is based on the form of text that is used in a WikiWikiWeb. It provides very simple and easy to remember tags so you can write a Wiki article without learning HTML. wt2db was originally written to convert Wikipedia articles into DocBook.
The Wiki format has been enhanced in several ways to make it more powerful for authors. Support has been added for Wiki tags that don't exist in any real Wiki, by giving common DocBook elements their own Wiki tags. Support has also been added for including DocBook elements right in the source file.
This means WikiText is a merging of DocBook into a plain text file. In in its simplest form, it is plain text. A plain text document can be processed by wt2db and converted into DocBook. Or, a complete and valid DocBook document can be processed, and will pass through the w2db filters and come out unchanged. Virtually any combination of DocBook with plain text will work, with the additional Wiki style tags to make things even easier for authors. It put all of the semantic of DocBook at your disposal, while being as easy to write as a Wiki page.
These are the tags which are supported in this release of wt2db. All DocBook tags are also supported. If you encounter any valid DocBook that is not handled correctly, please file a bug report.
Foo <para>Foo</para>
=Title= <sect1>
<title>Title</title>
</sect1>
=Title|id= <sect1 id='id'>
<title>Title</title>
</sect1>
The id attribute, delimited with a pipe character, works for other sect levels as well, and many other tags. In some cases it is not an id value, but the title, depending on the semantics of the particular tag. Usage should be obvious in context.
==Title== <sect2>
<title>Title</title>
</sect2>
===Title=== <sect3>
<title>Title</title>
</sect3>
#Foo <orderedlist>
#Bar <listitem>
#Baz <para>Foo</para>
/# </listitem>
<listitem>
<para>Bar</para>
</listitem>
<listitem>
<para>Baz</para>
</listitem>
</orderedlist>
*Foo <simplelist>
*Bar <listitem>
*Baz <para>Foo</para>
/* </listitem>
<listitem>
<para>Bar</para>
</listitem>
<listitem>
<para>Baz</para>
</listitem>
</simplelist>
Both ordered and unordered lists can be nested by increasing the number of ``#'' or ``*'' indicators, and ordered and unordered lists can also be nested inside each other. wt2db supports a depth of up to four itemized and/or four ordered lists. When nesting an itemized list inside another itemized list, or an ordered list inside an ordered list, repeat the ``#'' or ``*'' character to indicate the desired nesting level. When nesting an itemized list inside an ordered list or vice versa, it is not necessary to specify the depth, but it is recommended for clarity.
*Foo Nests one itemized list inside another. **Bar **Baz *Quux
*Foo Nests an ordered list inside an itemized list. #Bar #Baz *Quux
[[foo]] <xref linkend='foo' linkterm='foo'/> [[link:Foo]]
[[file:/etc/foo]] <filename>/etc/foo</filename>
[[dir:/etc]] <filename class="directory">/etc</filename>
[[dev:/dev/ttyS0]] <filename class="devicefile">/dev/ttyS0</filename>
[[http://foo.org]] <ulink url='http://foo.org'>
<citetitle>http://foo.org</citetitle>;
</ulink>
[[http://foo.org Foo]] <ulink url='http://foo.org'>
[[http://foo.org|Foo]] <citetitle>Foo</citetitle>
</ulink>
[[ftp://foo.org]] <ulink url='ftp://foo.org'>
<citetitle>ftp://foo.org</citetitle>;
</ulink>
[[news://alt.foo.bar]] <ulink url='news://alt.foo.bar'>
<citetitle>alt.foo.bar</citetitle>
</ulink>
'''Foo''' <emphasis>Foo</emphasis>
A few DocBook structures will not have <para> tags wrapped around them. They are <para> itself, <sect?> and <programlisting>. If you insert anything using these tags, no <para> tags will be wrapped around it or inserted into it. So if you want fine control over your <para> tags, insert them yourself.
The <screen> element will be wrapped with <para> tags, but no internal paragraph breaks will be generated.
Currently only a single form of WikiText is supported, which is very similar to that used by the Wikipedia. See http://www.wikipedia.com for more information on the Wikipedia.
A future release will be configurable to support additional styles of WikiText.
Bugs are tracked along with Lampadas bugs in the Gnome Bugzilla repository. If you report a bug in wt2db, specify lampadas as the product and wt2db as the component, so it will be routed the appropriate person. You can do this quickly by visiting the following URL:
http://bugzilla.gnome.org/enter_bug.cgi?product=lampadas&component=wt2db
See the home page of the Linux Documentation Project, http://www.tldp.org for updates and more information. Also see the WikiText Editing HOWTO published by the LDP at http://www.tldp.org/HOWTO/WikiText-HOWTO/.
This man page was written by David C. Merrill, david -AT- lupercalia.net.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts.