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')
There are 5 section levels you can use. They are all automatically numbered. Your choices are:
A top level section. This is indexed.
A 1st level section. This is indexed.
A 2nd level section. This is not indexed.
A 3rd level section. This is not indexed.
A 4th level section. This is not indexed.
I think there are lots of ways of doing this, but I've only been using 2:
Emphasises text like this.
Emboldens text like this.
There is a useful shorthand here. These (and many other tags) can be written either as:
This second form can be very useful.
Here we have 3 useful types:
A standard bulletted list
A numbered list
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>
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.
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
]
.
One of the extra feature that this lets us do is include URLs and 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.
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="<someone@no.where.com>">
Which will appear as
<someone@no.where.com>