DOSEMU Technical Guide
Prev		Next

14. Documenting DOSEMU

Effective from dosemu-1.0.1 the documentation format for DOSEMU is DocBook. Currently this is DocBook 3.0, but formatted in lower case for XML compatibility. This will probably be migrated to DocBook 4, but the changes are unlikely to affect most authors.

Every programmer can handle the few basic DocBook commands that are need to make some really good documents! There are many similarities with HTML, which is hardly surprising as they are both SGML narkup languages. The source to this document may make useful reading (This is the file ./src/doc/README/doc)

14.1. Sections

There are 5 section levels you can use. They are all automatically numbered. Your choices are:

<sect1>: A top level section. This is indexed.
<sect2>: A 2nd level section. This is indexed.
<sect3>: A 3rd level section. This is indexed.
<sect4>: A 4th level section. This is not indexed.
<sect5>: A 5th level section. This is not indexed.

You cannot skip section levels on the way up or down (ie you must go <sect>,<sect1>,<sect2> and not <sect>,<sect2>). You must also close each section when you finish it. This includes the enclosing sections.
The title of the section must be enclosed within <title>...</title> tags.
Each paragraph of text must be enclosed within <para>...</para>.

14.2. Emphasising text

There is only one way to do this.

<em>...</em>: Emphasises text like this.

14.3. Lists

Here we have 3 useful types:

itemizedList: A standard bulletted list
orderedList: A "numbered" list
variableList: A description list (like this)

For ``itemizedList'' and ``orderedList'' the items are marked with <listitem>. eg:

    <itemizedList>
    <listitem><para> item 1 </para></listitem>
    <listitem><para> item 2 </para></listitem>
    </itemize>

For the ``variableList'' the items have two additional markers. Each entry in the list is enclosed in <varlistentry>...</varlistentry>. Each ``term'' is marked using <term>...</term> and then the content is marked with listitem, as above. eg:

    <variableList>
    <varlistentry><term>item 1</term><listitem><para> is here</para></listitem></varlistentry>
    <varlistentry><term>item 2</term><listitem><para> is here!</para></listitem></varlistentry>
    </variableList>

14.4. Quoting stuff

If you want to quote a small amount use <literal>...</literal>. eg:

    This is <literal>./src/doc/README/doc</literal>

To quote a large section, such as part of a file or an example use <screen>. eg:

    <screen>
    ...
    </screen>

You still need to ``quote'' any <, > or & characters although most other characters should be OK.

14.5. Special Characters

Obviously some characters are going to need to be quoted. In general these are the same ones as HTML. The most common ones are:

<: <
>: >
&: &

14.6. Cross-References & URLs

One of the extra feature that this lets us do is include URLs and cross-references.

14.6.1. Cross-References

These have 2 parts: a label, and a reference.

The label is <... id="...">. ie an id on the element you want to refer to.

The reference is <xref linkend="..." >. The linkend should refer to an id somewhere else in the same document (not necessarily the same file as the README's consist of multiple files). The section naem will be inserted automatically at site of the <xref>.

14.6.2. URLs

This is <ulink url="...">...</ulink>. The url will be active only for HTML. The text will be used at all times. eg:

    See the <ulink url="http://www.dosemu.org/">DOSEMU website</ulink>.

Which will appear as See the DOSEMU website.

14.6.3. Email addresses

Whilst it is possible to do insert email addresses as URLs there is a better way. Simply enclose the address in <email>...</email>. eg:

    <email>alistair@slitesys.demon.co.uk</email>

14.7. References

Here are a few other places to find information about writing using DocBook.

http://www.docbook.org/tdg/: ``DocBook: The Definitive Guide'' is a complete reference to DocBook. It is an O'Reilly book, which is also readable online.
http://metalab.unc.edu/godoy/using-docbook/using-docbook.html: This is a basic guide to DocBook.
http://www.linuxdoc.org/HOWTO/HOWTO-HOWTO/index.html: Part of the Linux Documentation Project (LDP) this is a guide to writing HOWTO's specifically, but covers DocBook in general as this is now the preferred MarkUp for the LDP.

Prev	Home	Next
mkfatimage16 -- Make a large FAT hdimage pre-loaded with files		Sound Code