17. Documenting DOSEmu

This is all about the new style DOSEmu documentation. When I was discussing this with Hans he was concerned (as I am) about the fact that we are all programmers - and generally programmers are poor at documentation. Of course, I'd love you all to prove me (us ?) wrong!

However, every programmer can handle the few basic linuxdoc-sgml commands that are need to make some really good documents! Much of linuxdoc-sgml is like HTML, which is hardly surprising as they are both SGMLs. The source to this document may make useful reading (This is the file './src/doc/README/doc')

17.1 Sections

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

<sect>

A top level section. This is indexed.

<sect1>

A 1st level section. This is indexed.

<sect2>

A 2nd level section. This is not indexed.

<sect3>

A 3rd level section. This is not indexed.

<sect4>

A 4th level section. This is not indexed.

• You cannot skip section levels on the way down (ie you must go <sect>,<sect1>,<sect2> and not <sect>,<sect2>). On the way back it doesn't matter!
• Any text on the same line as the tag will be used to identify the section
• You must have a <p> before you start the section text

17.2 Emphasising text

I think there are lots of ways of doing this, but I've only been using 2:

<em>...</em>

Emphasises text like this.

<bf>...</bf>

Emboldens text like this.

There is a useful shorthand here. These (and many other tags) can be written either as:

• <em>...</em>
• <em/.../

This second form can be very useful.

17.3 Lists

Here we have 3 useful types:

itemize

A standard bulletted list

enum

A numbered list

descrip

A description list (like this)

For the ``itemize'' and ``enum'' lists the items are marked with <item>. eg:

<itemize>
<item> item 1
<item> item 2
</itemize>

For the ``descrip'' lists the items are marked with either <tag>...</tag> or it's short form (<tag/.../). eg:

<descrip>
<tag>item 1</tag> is here
<tag/item 2/ is here!
</descrip>

17.4 Quoting stuff

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

This is ./src/doc/README/doc

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

<tscreen><verb>
<descrip>
,,,
</descrip>
</verb></tscreen>

Note that the order of closing the tags is the reverse of opening! You also still need to ``quote'' any < or > characters although most other characters should be OK.

17.5 Special Characters

Obviously some characters are going to need to be quoted. In general these are the same ones as HTML (eg < is written as <) There are 2 additional exceptions (which had me in trouble until I realised) which are [ and ]. These must be written as [ and ].

17.6 Cross-References & URLs

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

Cross-References

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

The label is <label id="...">

The reference is <ref id="..." name="...">. The id should refer to a lable somewhere else in the document (not necessarily the same file as the REAMDE's consist of multiple files) The content of name will be used as the link text.

URLs

This looks slightly horrible, but is very flexible. It looks quite similar to the reference above. It is <htmlurl url="..." name="...">. The url will be active only for HTML. The text in name will be used at all times. This means that it is possible to make things like email addresses look good! eg:

<htmlurl url="mailto:someone@no.where.com" name="&lt;someone@no.where.com&gt;">

17.7 Gotchas

• You must do the sect*'s in sequence on the way up
• You must have a <p> after each sect*
• You must close your lists
• You must reverse the order of the tags when closing tscreen/verb structures
• You must replace <, >, [ and ]