re: Yellow pages

[Robert Kessler <kessler%utah-orion@utah-cs>]

 > What information do we want to include with each program?  My initial
 > list is as follows:
 > 
 > A copyright notice or statement that the code is in the public domain.
I agree that a copyright notice along with the appropriate release.
 > Author's name.
And address.
 > Current maintainer, with mail and net address.
 > Description of the program (optional if there is a document).
I would still require a brief description.  
 > Notes on any non-portable aspects of the code.
 > Known bugs and ideas for future extension.
 > Log of significant changes from one release to another.
 > Random comments.
 > 
 > Anything else?  Should this be in the same file as the code (in a big
 > initial comment), or a separate-but-related file?  Should we try to come
It should be in the same file.  Its hard enough tracking down code
across multiple files, without the necessity of looking for the
documentation in some other place.
 > up with some syntax for making the fields easily identifiable by
 > machine, or is human-readability sufficient?
I would make a standard form of comments where there is a keyword before
each piece of information.  Then a fairly simple program can have
access.  We use a scheme devised at HP which creates a header like the
following, along with a revision list:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% File:         MINI-SUPPORT.SL
% Description:  A Small Meta System (Support routines for mini.min/mini.sl)
% Author:       Robert Kessler, Utah PASS Project
% Created:      01-Jan-79
% Modified:     9-Mar-84 15:05:06  (Robert Kessler)
% Mode:         Lisp
% Status:       Experimental (Do Not Distribute)
%
% (c) Copyright 1979, University of Utah, all rights reserved.
>>>> Put in some kind of release statement
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Revisions:
%
% 9-Mar-84 15:03:40  (Robert Kessler)
%  Added fluid definition of !*writingfaslfile, and modified
%   rule-define, so it does a boundp check before accessing the value of
%   the variable.  For strange reasons, this a call to an undefined
%   function if the compiler wasn't loaded.
% 27-Feb-84 11:58:47 (Robert Kessler)
%  Added Legal-single-char to check to see if a keyword is an
%   alphanumeric character.  We do not want to make an alphanumeric
%   character a keyword.  This would make words with that letter in it
%   invalid.  Therefore, if the grammar definer makes something a
%   keyword (like 't), it must be separated by other delimiters.
% ...
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
The NMODE text editor automatically updates the last modified line any
time you write the file out.

Bob.