The file example.zip holds several files. We will try to
    present what the documentation tools are. In this text, the
    word documentation refers to whatever tools help programmers
    understand and use software libraries. We are not talking
    about user documentation.

    Providing a reliable documentation on a software system
    is not easy. Most methodologies based on system too far
    away from the source code won't work.

    Reliable documentation on a system helps code reusability.
    Here is, we believe, the most important things to do for code
    reuse to happen.

    A)  Software component must be easy to locate. Programmers
        need index, summary, reference guides ... If a component
        exists but is not easy to locate, it will be duplicated.

    B)  Software component must be easy to understand.

        Each function of a system must be documented, simply and
        that documentation must be near the code itself.

    C)  The code must work well !

    The Solucorp Programmer's Toolkit start from a simple principle.
    Reliable documentation for a software component (function) is
    in the source code, immediatly near the declaration part of the
    component. If this documentation is not reliable, then nothing
    will ever be.

    The guidelines are simple. The first line of comments before a
    function declaration is a short description of the function
    action. All following comments before the declaration should
    tell explicitly what the function does, when a programmer must
    use it, what would make this function better, what values are
    returned, and so on.

    The source files (source*.c) provided show a sample system with
    very short documentation. In the provided makefile, a target
    "doc" at the end, shows which commands are used to update the
    documentation kit.

    From the source file, proto (the prototype extractor) gets
    the prototypes and surrounding comments. The file xsys.nap
    is produced.

    Naperm format three files from xsys.nap.

    xsys.nas : All functions are presented with the short documentation.
    xsys.nai : This is a permutted index of the file xsys.nas.
    xsys.nah : This is a log of all revisions made to project xsys.
               It shows when functions has been added, modified or
               deleted from system xsys.

    Those three files are good to spot a function when you have
    at least a small experience with system xsys. If you are
    new to xsys, and the system has over a hundred functions, you
    need something else. You need a general document that introduces
    xsys and present function is an organised way. This kind of
    document is difficult to produce. It is generally huge. It
    is often inacurate. For all this, it is also never read.

    There is a way out. If you have acurate documentation in
    the source files for each function, then there is a way
    to create this document without too much pain. The file
    xsys.doc is the layout of the reference manual of system
    xsys. It contains simple introduction, a general outline of
    the system, and simple classification of the function of the
    system.

    From xsys.doc and xsys.nap, the file xsys.ref is produced.
    This file is the reference manual. It is always up to date.
    Nadoc is the utility that produced that. It will spot all
    functions not classified in xsys.doc. It will also
    tell about functions that do not exist anymore.