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.)
Some initial comments:
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:
There should only be one maintainer on a line. There can be no other lines of description before DANG_END_MODULE.
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'.
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 ...
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.
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.
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.
* No Example *
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.
Next Previous Contents
|The DOSEMU team|