Header Comment Form for Dialog Source Files
                             29th August 1985

                            Bertrand Ibrahim
                             Alastair Milne


   In order to assure that enough information is kept with a module's source
   files to enable it to be compiled and run reliably from those files, the
   following forms should be placed at the head of every source file, from
   which the utility FUDGE can assemble them into a listing for the module.  

   The form outlines are available on DIS.SYS: and the TOOLS: subvolumes 
   to be copied into source files that don't yet have them.  

   There are four of these forms, one each for program main files, unit main 
   files, include files for either programs or units, and keyed file sources.  
   Here is an explanation of each form, describing the components, 
   and indicating where components are either necessary or optional.

   The four forms all begin with these three items:

	 File Name :
       Description : (include, main, keyed, data) used by...

	 Creation
	    Date :
	   Coder :

	 Update
	    Date :
	   Coder :

   The "file name" field gives the name of this file, with any explanations of
   the name that might be required (especially if the name is an abbreviation,
   or follows an overall naming scheme).  Be sure to keep this field up to
   date if the file's name changes.

   The "description" field should give a general description of the file,
   including its category and its purpose.  Take as many lines (within reason)
   as needed for this: too much information is usually preferable to too
   little.

   The coder who originally creates the file should fill in the "creation"
   field.  All subsequent coders handling this file should add their own
   "update" fields.  In both cases, the date given should be that on which the
   new stable, running version was created and, presumably, placed on the
   maintenance disc.



A.  For the Dialog's Main File (the one given to the compiler):


      Compilation context
		    Units used : (specify version)
	List of included files :

   This pair specifies what is required simply to compile the program: all the
   units it uses (and the library files, if not *SYSTEM.LIBRARY, in
   which this file looks for them), and all its include files.  The units
   should be listed in the same order in which they are listed in the USES
   statement, and their version numbers should be given, if they have any.


      Execution context
	  List of Data files :
	 List of Keyed files :
	  List of Foto files :
	  List of Units used :

   The "Execution Context" entry should list all files which must be on line
   when the program is executed.  If an entry does not apply (if, for instance, 
   the only data files used are foto files), it need not be included.  
   - For units outside *SYSTEM.LIBRARY, list also the file(s) in which the 
     system should look for them when executing the program.  
   - If the program requires special characters, ETC.CHARSET should be listed 
     under "data files".  
   - For any foto files listed, give the machine for which each file is
     intended, and the dimensions in pixels of its graphics screen.


	 Special requirements
		 Memory size :
		  Disk space :
	     Temporary files :
		      Prefix :
	    p-System version :

   If the program has any special requirements for execution, they should be
   listed here.
   - If a certain minimum amount of memory or free disc space is known to be 
     needed, it should be given.
   - Any temporary files not otherwise specified should be listed.
   - If the prefixed volume is not the root volume, list what it should be.
   - Give the version of the p-System for which the program is intended.
     At this writing, the version should be IV.2.1 3R4.



B.  For Main Files of Units:


      Compilation context
		    Units used : (specify file in which expected, and version)
	List of included files :

   This pair specifies what is required simply to compile the unit: all the
   units it itself uses (and the library files, if not *SYSTEM.LIBRARY, in
   which the file looks for them), and all its include files.  The units
   should be listed in the same order in which they are listed in the USES
   statement, with either their version numbers, if they have them, or their
   dates.


	 Compilation order
	   Before :
	    After :

   In the "before" entry, list all units (if any) that must be compiled before
   this unit can be compiled.  It isn't necessary to list recursively: if unit
   "X" is required, units that "X" uses needn't be listed.  
   In the "after" entry, list all units and programs (if any) which cannot 
   be compiled until this one has been.


      Run-Time requirements :

   List here anything (memory space, disc space, special files, etc.) that the
   unit will need for its routines to be used.



C.  For Include Files (of Programs and Units): 


      Included by :

   This complements the list of include files given in the program's or
   unit's main file.  It is particularly useful where the name of the include 
   file does not clearly indicate the module to which it belongs.

   It is possible, though not recommended, for one include file to be included
   by more than one main file.  The entry "included by:" should list ALL
   main files requiring this include file.



D. For Keyed File Sources:

   For keyed file sources, the "description" field should list at least:
   - the name(s) of the program(s) that use it;
   - its purpose;
   - whether it contains color scheme definitions;
   - whether it contains patterns for matching student entries.


       Translated versions: 

   This field should list all languages to which this keyed file has been 
   translated (the language in which this version of the file is written need
   not be included).