                            README for DANG_c.pl
                            ====================
Introduction

This is version 0.4 of DANG_c.pl. This is a program to automatically generate
a guide to DOSEMU for new hackers. It relies on special markers in the code
and the cooperation of the coders.

Changes

o   DANG_BEGIN_FUNCTION / DANG_END_FUNCTION
    This has been modified to assume that functions do not have parameters.
    It now has more flexibility. Please see the description later.
o   Command Line Flags and Parameters
    "-c <fname>" specifies a configuration file. The format of this file
        hasn't changed - just the way of specifying it.
    "fname1 fname2 ..." specifies a list of files to check. No 'sgml' file
        is generated, but error messages are.
o   DANG_FIXTHIS (in particular)
    Sometimes these had comment 'bits' left on them. These have been cleared.

Markers

The following markers are used:

o   DANG_BEGIN_MODULE / DANG_END_MODULE
    This will bracket a description of the file (normally at the start).

o   DANG_BEGIN_FUNCTION / DANG_END_FUNCTION
    This brackets a description of functions (good this, isn't it!) Not every 
    function needs to be described in this way - just the major ones.
    The Format is :
        DANG_BEGIN_FUNCTION <function_name ... until end of line>

        [text ...]

        [arguments:
        [arguments list ...]]

        [description:
        [text ...]]

        DANG_END_FUNCTION

    You may have as many "description:" and "arguments:" markers as you like,
    although it is recommended that you only use one of each. They are optional,
    as is the initial text. Both "arguments:" and "description:" markers are
    case _insensitive_.
    The difference is that arguments are bulletted. The suggested form for
    arguments is :
        argc - number of arguments
        argv - array of arguments

DANG_BEGIN_REMARK / DANG_END_REMARK
    This brackets descriptions of obscure items, like data structures
    and architecture.
    NB: These will be placed out of context in the document, and should be
        worded suitably.

DANG_FIXTHIS
    This is a one line item, indicating a an area requiring a fix, or
    redesign.
    NB: These will be placed out of context in the document, and should be
        worded suitably. ie _NOT_ "not implemented", but "gibber() is not 
        implemented"

DANG_BEGIN_NEWIDEA / DANG_END_NEWIDEA
    New Ideas Start Here! As Ideas are proposed, that get added with 
    their description, so that future generations can laugh at or
    code the ideas ..... These bracket the idea description.
    NB: These will be placed out of context in the document, and should be
        worded suitably.

DANG_BEGIN_CHANGELOG / DANG_END_CHANGELOG
    Changelogs - very useful for bug fixing, and avvailable for use
    with DPR (or that's the theory)


Alistair MacDonald
<alistair@slitesys.demon.co.uk>
