how to document yellow page entries, belated discussion by REM

[Robert Elton Maas <REM@IMSSS.SU.EDU>]

> Date: Thu, 24 Jan 1985  21:18 EST
> From: "Scott E. Fahlman" <Fahlman@CMU-CS-C.ARPA>
> 
> ;;; Program name: Gritch Generator
> ;;; Keywords: foo, bar, grumble, bletch
> ;;; Author: James Madison
> ;;; Description: This is an example of a long field that goes onto more
> ;;;  than one line.  The subsequent lines have this extra bit of
> ;;;  indentation after the triple-semicolon stuff.

One disadvantage of this format, as any ;-style comments, is that when
you copy a file using the LISP reader, such as to prettyprint or to
translate to another dialect, or to convert into or out of RLISP form,
or to expand some private macros, etc., all those comments are
stripped off during READing and thus will be missing from the output
version of the program.  Do you know of a LISP pseudo-reader that
somehow internalizes sections of a file like READ does except that
;-style comments are retained, somehow attached to the normal
s-expressions, so that when the file is PRINTed or PRETTYPRINTed etc.
back out using a correspondingly-modified version of the appropriate
output function the ;-style comments are put back in?

If not, I would say that *any* use of ;-style comments in an otherwise
READable&PRINTable LISP-source file is bad programming style since it
limits the kinds of processing that can effectively be done on the file.

(CC to COMMON-LISP general forum to spark debate on this controversial issue.)