The DANG compiler is a perl script which produces a linuxdoc-sgml document
from special comments embedded in the DOSEmu source code. This document is
intended to give an overview of the DOSEmu code for the benefit of hackers.

THE FOLLOWING MAY NOT SOUND VERY NICE, BUT IS INTENDED TO KEEP DANG AS IT
WAS DESIGNED TO BE - A GUIDE FOR NOVICES.

DANG is not intended to be a vehicle for copyrights, gratuitous plugs, or
anything similar. It is intended to guide hackers through the maze of DOSEmu
source code. The comments should be short and informative. I will mercilessly
hack out comments which do not conform to this. If this damages anything, or
annoys anyone, so be it.

I spent hours correcting the DOSEmu 0.63.1 source code because some
developers didn't follow the rules. They are very simple, and I'll remind you
of the below. (I am here to co-ordinate this, not do the work. The comments
are the responsibility of all of us.)

All the text is passed through a text formatting system. This means
that text may not be formatted how you want it to be. If you insist on
having something formatted in a particular way, then it probably
shouldn't be in DANG. Try a README instead. Embedding sgml tags in
the comment will probably not work.

Copyrights and long detailed discussions should not be in DANG. If
there is a good reason for including a copyright notice, then it should
be included ONCE, prefereably in the group summary file (see
'./src/doc/DANG/DANG_CONFIG' for the locations)

If I say something must be done in a particular way, then it
MUST. There is no point in doing it differently because the script
will not work correctly (and changing the script won't help anyone
else.) In most cases the reason for a particular style is to help users
who are actually reading the SOURCE file.

These should enclose a piece of summary text at the start of a file. It should
explain the purpose of the file. Anything on the same line as DANG_BEGIN_MODULE
is ignored. A future version may use the rest of this line to provide a
user selected name for the module. There may be any number of lines of text.
To include information on the maintainer(s) of a module, put 'maintainer:' on
a blank line. The following lines should contain the maintainers details in
form:

name ..... <user@address>

There should only be one maintainer on a line. There can be no other lines
of description before DANG_END_MODULE.

Example:

DANG_BEGIN_FUNCTION / DANG_END_FUNCTION

This is used to describe functions. Ideally this should only be complicated
or important functions as this avoids cluttering DANG with lots of
descriptions for trivial functions. Any text on the same line as
'DANG_BEGIN_FUNCTION' is taken as the name of the function.

There are two optional sub-markers: 'description:' & 'arguments:' These can
be included at any point, and the default marker is a description. The
difference is that arguments are converted into a bulleted list. For this
reason, there should be only one argument (& it's description) per line.
I suggest that arguments should be in the form 'name - description of name'.

Example:

DANG_BEGIN_REMARK / DANG_END_REMARK

This is used to provide in-context comments within the code. They can be used
to describe some particularly interesting or complex code. It should be
borne in mind that this will be out of context in DANG, and that DANG is
intended for Novice DOSEmu hackers too ...

Example:

DANG_BEGIN_NEWIDEA / DANG_END_NEWIDEA

This is used to make a note of a new idea which we would like to have
implemented, or an alternative way of coding something. This can be used
as a scratch pad until the idea is in a state where someone can actually
begin coding.

Example:

DANG_FIXTHIS

This is for single line comments on an area which needs fixing. This should
say where the fix is required. This may become a multi-line comment in the
future.

Example:

DANG_BEGIN_CHANGELOG / DANG_END_CHANGELOG

This is not currently used. It should be placed around the CHANGES section in
the code. It was intended to be used along with the DPR.

The current version of the configuration file resides in './src/doc/DANG'. The program
needs to be told where to find this using '-c <file>'. On my system I run it
in the './src/doc/DANG' directory using './DANG_c.pl -c DANG_CONFIG', but
its really up to you.

The other options are '-v' for verbose mode and '-i'.
-v isn't really useful, but it does tell you what it is doing at all times.
-i is 'irritating mode' and makes comments in the DANG file about missing
items, such as no MODULE information, no FUNCTION information, etc.

If the program is executed with a list of files as parameters then the files
will be processed, but no sgml output produced. This can be used for basic
debugging, as it warns you when there are missing BEGIN/END markers, etc.

I have vaguelly started writing the successor of this program. This will be a
more general program with a more flexible configuration system. Don't hold
your breath for an imminent release though. The new version will make it
easier to change the markers & document structure, as well as providing
feedback on errors.