Crashcourse Tutorial on how to use XML/DocBook for LinuxTag Papers
==================================================================

Papers for the LinuxTag Conferences should be submitted in a subset of
XML/DocBook. The structure of this format is described in this text.
This document is part of the LinuxTag Paper Development Kit (ltpdk).
Please make sure that you have read the README before you dive into this
text.

There is also an "example" directory, which contains some documents
explaining the use of XML/DocBook.


Basics of XML
-------------

XML works quite similar to HTML but is a little more strict in terms of
syntax. All markup is written in tags just like in HTML. For example,
<section> is an opening tag for the container "section". An opening tag
can be accompained by attributes as in <ulink url="http://www.linux.org/">.

The most important rules are:

  - All tags have to be closed, there are no exceptions like in HTML.

  - To abbreviate opening and closing a tag, you can add a trailing
    slash at the opening tag: "<title></title>" is equivalent to "<title/>".

  - All tag names and all attribute names have to use lowercase
    charcters and are case sensitive, unlike HTML. Values for attributes
    have to be quoted: <ulink url="mailto:a@b.de">.


Structure of an XML document
----------------------------

There is a framework and a header for each XML document. For LinuxTag
papers these headers look the same for all papers and should be used
directly from the template. Just correct your name, the title of the
paper and your paper id according to the README in the ltpdk. After this
header the body of the <article> container follows.
 

List of valid DocBook elements
------------------------------

We recommend only a subset of the full DocBook standard, so please use 
only the following elements for the body of your paper:

<section>           Creates new sections and subsections. 

<title>             Should be used as first container in every <section>
                    and can be also used inside tables and figures. 

<para>              For normal text. Note that this container is
                    necessary, you can't type directly into a <section>
                    container.  

<itemizedlist>      For ordered and unordered itemized lists. Every
<orderedlist>       single item needs a <listitem> container, which has
<listitem>          to be closed! Usually you place a <para> inside your
                    <listitem>. 

<programlisting>    Everything inside will be quoted verbatim. See
                    example document for important hints. 

<table>             To create tables quite similar to HTML. See example
<tgroup>            document.
<tbody>
<thead>
<tfoot>
<row>
<entry>

<emphasis>          The only text markup we support to emphasis a text
                    (may later be displayed bold or in italics in print)

<ulink>             To link to external URIs. Since your papers should
                    be more or less self-contained, don't make too much
                    use of this tag. The tag can be placed in any <para>.  

<mediaobject>       To include a figure, like a diagramm or a picture.
                    See the example document for details. 



Structure of the body
---------------------

Start with a <section>, followed by a <title>.

Now follows an arbitrary number of either simple paragraphs, lists,
tables, verbatim text or a sub level of a section.

Inside these there's just text, emphasized text, figures or links.

That's about all ;)


Further information
-------------------

If you are really interested in XML/DocBook, have a look at

    http://www.docbook.org/

But beware: This is mainly a highly technical reference guide. A good
starting point in this somewhat confusing website is

    http://www.docbook.org/tdg/en/html/ref-elements.html

A much more comprehensive introduction is

    http://xml.web.cern.ch/XML/goossens/dbatcern/

especially the chapters 3 - 7 describe the above in more detail.

Finally there are links to some other tutorials, the last two in german:

    http://opensource.bureau-cornavin.com/crash-course/
    http://rzserv2.fhnon.de/~lg002556/docbuch/
    http://trieloff.net/doctutorial/