.c	Friday  June 10,1983  19:03  NM+7H.23M.59S.  -*- Bolio -*-

.chapter "The NIL Pretty-Printer"

The lan{nil} pretty-printer is constructed in three layers.  The
core of it is the lan{write} module.  The lan{write} module
provides the code which produces all formatting decisions.  It is not
itself specific to lan{lisp} code, but rather defines mechanisms for
outputting text or tokens once "parsed" into logical constructs.  The
issues involved in this, pretty-printing in general, and the
lan{write} module, are topics of a paper in preparation by
Hawkinson.

The middle layer of the pretty-printer is provided by the lan{ppdef}
and lan{ppdesc} modules (which comprise the
3pretty-print-definition* system as defined with lan{lsb}).
This layer provides formatting capability for lan{lisp} objects,
while at the same time not forcing the interpretation of those objects
as lan{lisp} code (programs).

The final layer is that which is used by the actual lan{lisp} code
pretty-printer (the 3pretty-prin1* function).  This module,
lan{ppcode} (the 3pretty-print* system defined with lan{lsb})
2does* cause the interpretation of lan{lisp} objects as code,
and provides some default formats and simple parameterizations in
order that the actual formats used may be customized somewhat.

The primary purpose of this document is to provide lan{nil} users
with the information necessary to both add and customize
pretty-printing formats of new and existing lan{lisp} functions and
forms, and also to add pretty-printing capabilities to user-defined
objects or structures (as might be defined with 3defstruct* or
3defflavor*).  The best way to approach this is to go over the
following chapter on lan{write}, which describes the basic
formatting constructs and how they are used, then go to
(summary-section-page) (perhaps skimming the intermediate chapters),
which which describes the typical usage and gives some examples;  the
remaining sections will be needed as a reference source then.

