<sect>The DANG system
<p>

<sect1>Description
<p>
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.


<sect1>Changes from last compiler release
<p>

<itemize>
<item>	Recognizes 'maintainer:' information.
<item>	'-i' (irritating) flag.
<item>	Corrections to sgml special character protection.
</itemize>

<sect1>Using DANG in your code
<p>
<BF>THE FOLLOWING MAY NOT SOUND VERY NICE, BUT IS INTENDED TO KEEP DANG AS IT
WAS DESIGNED TO BE - A <em/GUIDE/ FOR <em/NOVICES/.</BF>
<p>
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.
<p>
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.)


<sect1>DANG Markers
<p>
Some initial comments:
<itemize>
<item>	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.
<item>	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 <em/ONCE/, prefereably in the group summary file (see 
	'./src/doc/DANG/DANG_CONFIG' for the locations)
<item>	If I say something <em/must/ be done in a particular way, then it 
	<em/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.
</itemize>

<sect1> DANG_BEGIN_MODULE / DANG_END_MODULE
<p>
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:

<tscreen><verb>
name ..... <user@address>
</verb></tscreen>

There should only be one maintainer on a line. There can be no other lines
of description before DANG_END_MODULE. 
<p>
Example:
<tscreen><verb>
/*
 * DANG_BEGIN_MODULE
 * 
 * This is the goobledygook module. It provides BAR services. Currently there
 * are no facilities for mixing a 'FOO' cocktail. The stubs are in 'mix_foo()'.
 *
 * Maintainer:
 * 	Alistair MacDonald	<alistair@slitesys.demon.co.uk>
 *	Foo Bar			<foobar@inter.net.junk>
 *
 * DANG_END_MODULE
 */
</verb></tscreen>

<sect2> DANG_BEGIN_FUNCTION / DANG_END_FUNCTION
<p>
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.
<p>
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'.
<p>
Example:
<tscreen><verb>
/*
 * DANG_BEGIN_FUNCTION mix_foo
 *
 * This function provides the foo mixing for the module. The 'foo' cocktail
 * is used to wet the throat of busy hackers.
 *
 * arguments:
 *  soft_drink - the type of soft drink to use.
 *  ice_cream - the flavour of ice-cream required
 *
 * description:
 * A number of hackers would prefer something a little stronger.
 *
 * DANG_END_FUNCTION
 */
</verb></tscreen>

<sect2> DANG_BEGIN_REMARK / DANG_END_REMARK
<p>
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 ...
<p>
Example:
<tscreen><verb>
/*
 * DANG_BEGIN_REMARK
 *
 * We select the method of preparation of the cocktail, according to the type
 * of cocktail being prepared. To do this we divide the cocktails up into :
 * VERY_ALCHOHOLIC, MILDLY_ALCHOHOLIC & ALCOHOL_FREE
 *
 * DANG_END_REMARK
 */
</verb></tscreen>

<sect2> DANG_BEGIN_NEWIDEA / DANG_END_NEWIDEA
<p>
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.
<p>
Example:
<tscreen><verb>
/*
 * DANG_BEGIN_NEWIDEA
 *
 * Rather than hard coding the names of the mixer functions we could try
 * using an array constructed at compile time - Alistair
 *
 * How to we get the list of functions ? - Foo
 *
 * DANG_END_NEWIDEA
 */
</verb></tscreen>

<sect2> DANG_FIXTHIS
<p>
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.
<p>
Example:
<tscreen><verb>
/* DANG_FIXTHIS The mix_foo() function should be written to replace the stub */
</verb></tscreen>

<sect2> DANG_BEGIN_CHANGELOG / DANG_END_CHANGELOG
<p>
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.
<p>
* No Example *

<sect1> Usage
<p>
The current version of the configuration file resides in './src/doc/DANG'. The program
needs to be told where to find this using '-c &lt;file&gt;'. 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.
<p>
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.
<p>
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.

<sect1> Future
<p>
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.
