GENERAL
        How to read the docs

UPDATE
        Mateese, 15-Oct-93, 14:45 MET

DESCRIPTION
        Nighfall uses a loosely standardized format for the written
        docs.
        The documentation is thematically separated into several
        chapters:
          'general'   (what it says)
          'concepts'  about the design concepts,
          'std'       about the standard objects in /std/*,
          'obj'       about the general objects in /obj/*,
          'lfun'      about the existing local functions in objects,
          'efun'      about external functions, supplied by the
                      gamedriver and the simul_efun.c,
          'help'      about the player commands
          'w'         about the wizard commands
          'papers'    misc. papers and abstracts
	  'prop'      about the existing properties in objects.

        The chapters are organized as own subdirectories in /doc (with
        'general' being /doc itself).

        To reference a specific docfile, the 'name(X)' convention is
        used: e.g. 'light(C)' means the doc about light in 'concepts'
        and thus is to be read as '/doc/concepts/light'.

        The text within each docfile is separated into several
        sections (this text is part of the section DESCRIPTION, above
        you see the sections 'UPDATE' and the title) and nicely
        indented within the sections.

        Special is the first section, since it titles the document.
        Therefore it has no fixed tagname like UPDATE, but instead the
        name of the chapter the text is located in (see the top of
        this file for an example).

        Often used sections are:

          UPDATE
            This shows author-name and time of the last modification.

          SYNOPSIS
            Short hint how to use/activate the thing described.
	    This may also a list of several equivalent forms of usage.

            E.g. the text
              #include <foo.h>
              inherit "std/foo";
            means that to use the features of the object 'foo' you
            have to inherit it into your object. The file 'foo.h' must
            be included to get the symbolic constants used with the
            functions of 'foo'.

            For commands, their usage and options form the synopsis.

          DESCRIPTION
            What you currently read (and hopefully remember).

          BUGS
            A description of known but unfixed bugs.

          SEE ALSO
            References to other docs.


       When describing functions, a notation similar to LPC is used:

         int function1 ( void )
         int function2 ( string arg )

       denotes two functions returning a result of type integer; the
       first taking no argument, the second taking an argument named 'arg'
       of type string.

       If a function allows several types for an argument, the | notation
       is used:

         void function3 ( int|string data )

       Here the argument <data> (note the <> for the formal parameter) may
       be of type integer or of type string. If one of the possible types
       is 'void', the argument may be omitted at all, and the function will
       instead use the value 0 (if not commented otherwise).

       A special case is the 'varargs' notation:

         string function ( void|int arg1, void|int arg2, void|string arg3 )

       Any of the three parameters may be omitted, BUT ONLY if all following
       parameters are omitted as well!


       Properties are normally described using their symbolic name. Thus

         string P_SHORT  "Short"

       specifies the property P_SHORT of being of value string and having
       the name "Short".


SEE ALSO
        rtfm(C), everything in /doc
