mirror of https://github.com/tLDP/LDP
229 lines
7.4 KiB
Plaintext
229 lines
7.4 KiB
Plaintext
=head1 NAME
|
|
|
|
B<wt2db> - converts WikiText documents into DocBook XML/SGML.
|
|
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
B<wt2db> [I<OPTION>] [I<FILE>]
|
|
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
B<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.
|
|
|
|
|
|
=head1 OPTIONS
|
|
|
|
B<-s>, B<--sgml> add SGML DOCTYPE and article tags.
|
|
|
|
B<-x>, B<--xml> add XML DOCTYPE and article tags.
|
|
|
|
B<-f>, B<--faq> make the article a FAQ.
|
|
|
|
B<-e>, B<--encoding> specify the document encoding.
|
|
|
|
B<-n>, B<--nonet> do not access the network.
|
|
|
|
B<-o>, B<--output-to> I<filename> write to the specified file.
|
|
|
|
B<-V>, B<--verbose> show diagnostic output.
|
|
|
|
B<-v>, B<--version> show program version.
|
|
|
|
B<-h>, B<--help> show a usage message.
|
|
|
|
|
|
=head1 HISTORY
|
|
|
|
B<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.
|
|
|
|
|
|
=head1 NOTES
|
|
|
|
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.
|
|
B<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 B<wt2db> and converted into
|
|
DocBook.
|
|
Or, a complete and valid DocBook document can be processed,
|
|
and will pass through the B<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.
|
|
|
|
|
|
=head1 WIKITEXT
|
|
|
|
These are the tags which are supported in this release of
|
|
B<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. B<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.
|
|
|
|
|
|
=head1 RESTRICTIONS
|
|
|
|
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.
|
|
|
|
|
|
=head1 BUGS
|
|
|
|
Bugs are tracked along with Lampadas bugs in the Gnome Bugzilla
|
|
repository.
|
|
If you report a bug in B<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
|
|
|
|
|
|
=head1 SEE ALSO
|
|
|
|
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/.
|
|
|
|
=head1 AUTHOR
|
|
|
|
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.
|
|
|
|
=cut
|
|
|