.c	Sunday  Dec 11,1983  18:33  NM+7D.3H.28M.51S.  -*- Bolio -*-

.section "Format"
.setq format-chapter chapter-number
.setq format-section-page section-page
.setq format-page page

This section is a quick reworking of the chapter on 3format* which
appeared in ref{Maclisp-Extensions}.  It omits topics specific to
implementations of 3format* other than lan{nil}'s, and includes
references to differences between what lan{nil} currently provides,
and the definition of 3format* provided by lan{common lisp}.  It
is not known at this time how the lan{common lisp} definition of
3format* will affect the lan{maclisp} implementation, which
utilizes the same source code as the lan{nil} implementation right
now.  The lan{nil} version of 3format* will of course be made to
conform to the lan{common lisp} definition.

.defun format destination control-string &rest args
3format* is used to produce formatted output.  3format*
outputs the characters of 2control-string*, except that tilde
("3~*") introduces a directive.  The character after the tilde,
possibly preceded by arguments and modifiers, specifies what kind of
formatting is desired.  Some directives use an element of 2args*
to create their output.
.end_defun

The output is sent to 2destination*.  If 2destination* is
3nil*, a string is created which contains the output.  If
2destination* is 3t*, the output is sent to the "default
output destination", the value of 3standard-output*
((standard-output-var)).  Otherwise, 2destination* should be an
output stream.

.defun ?format destination control-string &rest args
This is equivalent to 3format* except that 2destination* is
interpreted just like the stream argument to 3print*--3nil*
means "the default" (the value of 3standard-output*), and 3t*
means "the terminal" (the value of 3terminal-io*).  This only
exists in lan{maclisp} and lan{nil}.
.end_defun

A directive consists of a tilde, optional decimal numeric parameters
separated by commas, optional colon ("3:*") and atsign ("3@*")
modifiers, and a single character indicating what kind of directive
this is.  The alphabetic case of the character is ignored.
Examples of control strings:
.lisp
"~S"        ; 1This is an S directive with no parameters.*
"~3,4:@s"   ; 1This is an S directive with two parameters, 3 and 4,*
            ; 1   and both the colon and atsign flags.*
.end_lisp

3format* includes some extremely complicated and specialized
features.  It is not necessary to understand all or even most of its
features to use 3format* efficiently.  The beginner should
skip over anything in the following documentation that is not
immediately useful or clear.  The more sophisticated features are
there for the convenience of programs with complicated formatting
requirements.

Sometimes a numeric parameter is used to specify a character,
for instance the padding character in a right- or left-justifying
operation.  In this case a single quote (3'*) followed by the
desired character may be used as a numeric argument.  For example,
you can use
.lisp
"~5,'0d"
.end_lisp
to print a decimal number in five columns with leading zeros (the
first two parameters to 3~D* are the number of columns and the
padding character).

In place of a numeric parameter to a directive, you can put
the letter 3v*, which takes an argument from 2args* as a
parameter to the directive.  Normally this should be a number but it
doesn't really have to be.  This feature allows variable column-widths
and the like.  Also, you can use the character 3#* in place of a
parameter; it represents the number of arguments remaining to be
processed.

It is possible to have a directive name of more than one
'setq multi-character-operator-page page
character.  The name need simply be enclosed in backslashes
("3\*");  for example,
.lisp
(format t "~\\now\\" (status daytime))
.end_lisp
The backslashes above are doubled, because backslash is the
quoting character in lan{common lisp}.  Because of this, the
forward-slash character (3/*) will probably be made synonymous
with backslash, but as of yet it has not been.
As always, case is ignored here.  There is no way to quote a backslash
in such a construct.  No multi-character operators come with
3format*.

Once upon a time, various strange and wonderful interpretations were
made on 2control-string* when it was neither a string nor a
symbol.  Some of these are still supported for compatibility with
existing code (if any) which uses them;  new code, however, should
only use a string or symbol for 2control-string*.

.subsection "The Operators"
	Here are the operators.
.table 3 250 500
.item ~A
2arg*, any lan{lisp} object, is printed without slashification (like
3princ*).  3~2n*A* inserts spaces on the right, if
necessary, to make the column width at least 2n*.
3~2mincol,colinc,minpad,padchar*A* is the full form of
3~A*, which allows aleborate control of the padding.  The string
is padded on the right with at least 2minpad* copies of
2padchar*;  padding characters are then inserted 2colinc*
characters at a time until the total width is at least 2mincol*.
The defaults are 30* for 2mincol* and 2minpad*, 31*
for 2colinc*, and 2space* for 2padchar*.  The atsign
modifier causes the output to be right-justified in the field instead
of left-justified.  (The same algorithm for calculating how many pad
characters to output is used.)  The colon modifier causes an 2arg*
of 3nil* to be output as 3()*.

.item ~S
This is identical to 3~A* except that it uses 3prin1* instead
of 3princ*.
.item ~D
Decimal output.  2arg* is printed as a decimal integer.
3~2n*,2m*,2o*D* uses a column width of
2n*, padding on the left with pad-character 2m* (default of
space), using the character 2o* (default comma) to separate
groups of three digits.  These commas are only inserted if the
3:* modifier is present.  Additionally, if the 3@* modifier
is present, then the sign character will be output unconditionally;
normally it is only output if the integer is negative.  If 2arg*
is not an integer, then it is output (using 3princ*)
right-justified in a field 2n* wide, using a pad-character of
2m*, with decimal output radix and trailing decimal point
suppression.

If 2arg* is not an integer, then it is output in the specified
field (as by 3~A*), in decimal.

.item ~O
Octal output.  Just like 3~D*;  if 2arg* is not an integer, it
is output (as by 3~A*), in octal.

.item ~B
Similar, but binary (base 2).

.item ~P
If 2arg* is not the integer 31*, a lower-case "s" is printed.
("P" is for "plural".)  3~:P* does the same thing, after backing
up an argument (like "3~:**", below);  it prints a lower-case
3s* if the 2last* argument was not 1.  3~@P* prints "y" if
the argument is 1, or "ies" if it is not.  3~:@P* does the same
thing, but backs up first.
.break
Example:
.lisp
(format nil "~D Kitt~:@P" 3)  =>  "3 Kitties"
.end_lisp
.item ~*
3~** ignores one 2arg*. 3~2n*** ignores the next 2n*
arguments.  2n* may be negative.  3~:** backs up one arg;
3~2n*:** backs up 2n* args.

3~2n*@** is an "absolute goto"; it "goes to" the 2n*th
argument.

This directive only affects the "local" args, if control is within
something like 3~{*.
'c matching }.

.item ~%
Outputs a newline.  3~2n*%* outputs 2n* newlines.  No
argument is used.
.item ~&
Performs a 3fresh-line* on the output stream ((fresh-line-fun)).
3~2n*&* outputs 32n*-1* newlines after the fresh-line.
.item ~X
Outputs a space.  3~2n*X* outputs 2n* spaces.  No
argument is used.  This directive is changing in lan{common lisp} to
mean "hexidecimal output" (done like 3~D*);  to get the effect of
the old 3~X*, one can use 3~T*, or some construct utilizing
3~<* or 3~{*.
'c matching }.

.item ~~
Outputs a tilde.  3~2n*~* outputs 2n* tildes.  No argument
is used.

.item ~2newline*
Tilde immediately followed by a newline ignores the newline
and any whitespace at the beginning of the next line.  With a
3:*, the whitespace is left in place.  With an 3@*, the
newline is left in place.  This directive is typically used
when a format control string is too long to fit nicely into one line
of the program:
.lisp
(format the-output-stream "~&This is a reasonably ~
			   long string~%")
.end_lisp
which is equivalent to 3format*ing the string
.lisp
"~&This is a reasonably long string~%"
.end_lisp
.item ~|
Outputs a formfeed.  3~2n*|* outputs 2n* formfeeds.  No
argument is used.

In the current implementation, 3~|* will do something like try
to clear the screen on a terminal.  However, this will be changed:
the intent of 3~|* is to output the page separator character,
which might be inconvenient to type in or have sitting in the middle
of a format string in ones source file.  To get the old behavior, use
3~:|*--eventually 3~|* will be changed.
.item ~T
Spaces over to a given column.  The full form is
3~2destination*,2increment*T*, which will output
sufficient spaces to move the cursor to column 2destination*.  If
the cursor is already past column 2destination*, it will output
spaces to move it to column 2destination3+*increment7**k*,
for the smallest integer value 2k* possible.  2increment*
defaults to 31*.  This is implemented by the 3format-tab-to*
function, (format-tab-to-fun).  On certain streams, this may not
actually output spaces, but may use cursor positioning;  thus, one
should not depend on ~T "erasing" text by the typing of spaces.

This will be changed slightly to eliminate a common and unsightly
fencepost.  Currently 3~T* will do nothing if the "cursor" is
exactly at column 2destination*;  however, it will be changed so
that spacing will be done then too.

In the future, 3~@T* will do 2relative* positioning.

.item ~Q
3~Q* uses one argument, and applies it as a function to
2params*.  It could thus be used to, for example, get a specific
printing function interfaced to 3format* without defining a
specific operator for that operation, as in
.lisp
(format t "~&;  The frob ~vQ is not known.~%"
	frob 'frob-printer)
.end_lisp
The printing function should obey the conventions described in
(define-your-own-section-page).  Note that the function to 3~Q*
follows the arguments it will get, because they are passed in as
3format* parameters which get collected before the operator's
argument.  Not in lan{common lisp}.
.item ~[
3~[2str0*~;2str1*~;2...*~;2strn*~]* is a set of
alternative control strings.  The alternatives (called 2clauses*)
are separated by 3~;* and the construct is terminated by 3~]*.
For example, "3~[Siamese ~;Manx ~;Persian ~;Tortoise-Shell ~;Tiger
~;Yu-Hsiang ~]kitty*".  The 2arg*th
alternative is selected; 30* selects the first.
If a numeric parameter is given (i.e. 3~2n*[*),
then the parameter is used instead of an argument
(this is useful only if the parameter is "3#*").
If 2arg* is out of range no alternative is selected.
After the selected alternative has been processed, the control string
continues after the 3~]*.

~[2str0*~;2str1*~;2...*~;2strn*~:;2default*~] has a default case.
If the 2last* 3~;* used to separate clauses
is instead 3~:;*, then the last clause is an "else" clause,
which is performed if no other clause is selected.
For example, "3~[Siamese ~;Manx ~;Persian ~;Tortoise-Shell ~;Tiger
~;Yu-Hsiang ~:;Unknown ~] kitty*".

~[~2tag00*,2tag01*,2...*;2str0*~2tag10*,2...*;2str1...*~]
allows the clauses to have explicit tags.  The parameters to each 3~;*
are numeric tags for the clause which follows it.  That clause is processed
which has a tag matching the argument.  If 3~:2a1*,2a2*,2b1*,2b2*,2...*;*
is used, then the following clause is tagged not by single values but
by ranges of values 2a1* through 2a2* (inclusive), 2b1* through 2b2*, etc.
3~:;* with no parameters may be used at the end to denote a default clause.
For example, "3~[~'+,'-,'*,'//;operator ~'A,'Z,'a,'z;letter ~'0,'9;digit ~:;other ~]*".

3~:[2false*~;2true*~]* selects the 2false* control string
if 2arg* is 3nil*, and selects the 2true* control string otherwise.

3~@[2true*~]* tests the argument.  If it is not 3nil*,
then the argument is not used up, but is the next one to be processed,
and the one clause is processed.
If it is 3nil*, then the argument is used up, and the clause is not processed.
.lisp
(setq prinlevel nil prinlength 5)
(format nil "~@[ PRINLEVEL=~D~]~@[ PRINLENGTH=~D]"
	prinlevel prinlength)
   =>  " PRINLENGTH=5"
.end_lisp
.item ~R
'c I quote, once more:
If there is no parameter, then 2arg* is printed as a cardinal English number, e.g. four.
With the colon modifier, 2arg* is printed as an ordinal number, e.g. fourth.
With the atsign modifier, 2arg* is printed as a Roman numeral, e.g. IV.
With both atsign and colon, 2arg* is printed as an old Roman numeral, e.g. IIII.

If there is a parameter, then it is the radix in which to print the number.
The flags and any remaining parameters are used as for the 3~D* directive.
Indeed, 3~D* is the same as 3~10R*.  The full form here is therefore
3~2radix*,2mincol*,2padchar*,2commachar*R*.

.item ~C
2arg* is coerced to a character code.  With no modifiers, 3~C*
simply outputs this character.  3~@C* outputs the character so it
can be read in again using the 3#* reader macro:  if there is a
named character for it, that will be used, for example
"3#\Return*";  if not, it will be output like "3#/A*".
3~:C* outputs the character in human-readable form, as in
"Return", "Meta-A".  3~:@C* is like 3~:C*, and additionally
might (if warranted and if it is known how) parenthetically state how
the character may be typed on the user's keyboard.

To find the name of a character, 3~C* looks in two places.  The
first is the value of the symbol which is the value of
3format:*/#-var*,
'vindex format:*/#-var
which is initialized to be the variable which the 3#* reader macro
uses.  It is not necessary for the value of 3format:*/#-var* to be
bound.  The second place is 3*format-chnames*;  this is used
primarily to handle non-printing characters, in case the 3#*
reader macro is not loaded.  Both of these are a-lists, of the form
3((2name* . 2code*) (2name* . 2code*) ...)*.

The Maclisp/NIL 3format* has no mechanism for telling how a
particular character needs to be typed on a keyboard, but it does
provide a hook for one.  If the value of 3format:*top-char-printer*
'vindex format:*top-char-printer
is not 3nil*, then it will be called as a function on two arguments:  the character code, and the character name.  If there were bucky-bits present, then they will have been stripped off unless there was a defined name for the character with the bits present.  The function should do nothing in normal
cases, but if it does it should output two spaces, and then the
how-to-type-it-in description in parentheses.  See
(define-your-own-section-page) for information on how to do output
within 3format*.
.item ~<
3~2mincol*,2colinc*,2minpad*,2padchar*<2text*~>*
justifies 2text* within a field 2mincol* wide.  2text* may
be divided up into segments with 3~;*--the spacing is evenly
divided between the text segments.  With no modifiers, the leftmost
text segment is left justified in the field, and the rightmost text
segment right justified;  if there is only one, as a special case, it
is right justified.  The colon modifier causes spacing to be
introduced before the first text segment;  the atsign modifier causes
spacing to be added after the last.  2minpad*, default 30*, is
the minimum number of 2padchar* (default space) padding characters
to be output between each segment.  If the total width needed to
satisfy these constraints is greater than 2mincol*, then
2mincol* is adjusted upwards in 2colinc* increments.
2colinc* defaults to 31*.  For example,
.lisp
(format nil "~10<foo~;bar~>")    =>  "foo    bar"
(format nil "~10:<foo~;bar~>")   =>  "  foo  bar"
(format nil "~10:@<foo~;bar~>")  =>  "  foo bar "
(format nil "~10<foobar~>")      =>  "    foobar"
(format nil "~10:@<foobar~>")    =>  "  foobar  "
(format nil "$~10,,,'*<~3f~>" 2.59023)
				 =>  "$******2.59"
.end_lisp

If 3~^* is used within a 3~<* construct, then only the clauses
which were completely processed are used.  For example,
.lisp
(format nil "~15<~S~;~^~S~;~^~S~>" 'foo)
	=>  "            FOO"
(format nil "~15<~S~;~^~S~;~^~S~>" 'foo 'bar)
	=>  "FOO         BAR"
(format nil "~15<~S~;~^~S~;~^~S~>" 'foo 'bar 'baz)
	=>  "FOO   BAR   BAZ"
.end_lisp

If the first clause of a 3~<* is terminated with 3~:;* instead of
3~;*, then it is used in a special way.  All of the clauses are
processed (subject to 3~^*, of course), but the first one is omitted
in performing the spacing and padding.  When the padded result has
been determined, then if it will fit on the current line of output, it
is output, and the text for the first clause is discarded.  If,
however, the padded text will not fit on the current line, then the
text for the first clause is output before the padded text.  The first
clause ought to contain a carriage return.  The first clause is always
processed, and so any arguments it refers to will be used; the
decision is whether to use the resulting piece of text, not whether to
process the first clause.  If the 3~:;* has a numeric parameter
2n*, then the padded text must fit on the current line with 2n*
character positions to spare to avoid outputting the first clause's
text.  For example, the control string
.lisp
"~%;; ~{~<~%;; ~1:; ~S~>~^,~}.~%"
.end_lisp
can be used to print a list of items separated by commas, without
breaking items over line boundaries, and beginning each line with
"3;; *".  The argument 1 in 3~1:;* accounts for the width of the
comma which will follow the justified item if it is not the last
element in the list, or the period if it is.  If 3~:;* has a second
numeric parameter, then it is used as the width of the line,
thus overriding the natural line width of the output stream.  To make
the preceding example use a line width of 50, one would write
.lisp
"~%;; ~{~<~%;; ~1,50:; ~S~>~^,~}.~%"
.end_lisp

Note that the segments 3~<* breaks the output up into are computed
"out of context" (that is, they are first recursively 3format*ted
into strings).  Thus, it is not a good idea for any of the segments to
contain relative-positioning commands (such as 3~T* and 3~&*),
or any line breaks.  If 3~:;* is used to produce a prefix string,
it also should not use relative-positioning commands.
.item ~{2str*~}
.c The merging of the italic "r" and bold "~" loses on XGP, so a ^T is used.
This is an iteration construct.  The argument should be a list,
which is used as a set of arguments as if for a recursive call to
3format*.  The string 2str* is used repeatedly as the control
string.  Each iteration can absorb as many elements of the list as it
likes.  If before any iteration step the list is empty, then the
iteration is terminated.  Also, if a numeric parameter 2n* is
given, then there will be at most 2n* repetitions of processing of
2str*.

3~:{2str*~}* is similar, but the argument should be a list
of sublists.  At each repetition step one sublist is used as the set
of arguments for processing 2str*; on the next repetition a new
sublist is used, whether or not all of the last sublist had been
processed.

3~@{2str*~}* is similar to 3~{2str*~}*, but
instead of using one argument which is a list, all the remaining
arguments are used as the list of arguments for the iteration.

3~:@{2str*~}* combines the features of
3~:{2str*~}* and 3~@{2str*~}*.  All the
remaining arguments are used, and each one must be a list.  On each
iteration one argument is used as a list of arguments.

Terminating the repetition construct with
'c Matching {
3~:}*
instead of
'c Matching {
3~}*
forces 2str* to be processed at least once even if the initial
list of arguments is null (however, it will not override an explicit
numeric parameter of zero).

If 2str* is null, then an argument is used as 2str*.  It must be
a string, and precedes any arguments processed by the iteration.  As
an example, the following are equivalent:
.lisp
(apply (function format) (list* stream string args))
(format stream "~1{~:}" string args)
.end_lisp
This will use 3string* as a formatting string.  The 3~1{* says
it will be processed at most once, and the 3~:}* says it will be
processed at least once.  Therefore it is processed exactly once,
using 3args* as the arguments.
.c Matching {
.item ~}
Terminates a 3~{*.  It is undefined elsewhere.
.c Matching }
.item ~^
'c     I quote, from the Lispm manual:
This is an escape construct.  If there are no more arguments remaining
to be processed, then the immediately enclosing 3~{*
'c matching "}"
or 3~<* construct is terminated.  (In the latter case, the 3~<*
formatting 2is* performed, but no more clauses are processed before
doing the justification.  The 3~^* should appear only at the
2beginning* of a 3~<* clause, because it aborts the entire
clause.  It may appear anywhere in a 3~{*
'c Matching "}"
construct.)  If there is no such enclosing construct, then the entire
formatting operation is terminated.

If a numeric parameter is given, then termination occurs if the parameter
is zero.  (Hence 3~^* is the same as 3~#^*.)  If two parameters are
given, termination occurs if they are equal.  If three are given, termination
occurs if the second is between the other two in ascending order.

If 3~^* is used within a 3~:{*
'c Matching "}"
construct, then it merely terminates
the current iteration step (because in the standard case it tests for
remaining arguments of the current step only); the next iteration step
commences immediately.  To terminate the entire iteration process,
use 3~:^*.

.item ~2n*G
This is the old form of 3~2n*@**, above.  In lan{common
lisp}, 3~G* is a floating-point format directive derived from
lan{fortran} 7G* format.  New code should use 3~@**.

.item ~F
Reserved for fixed-field floating-point format.
.item ~E
Reserved for exponential floating-point format.
.item ~$
2This is not yet defined in NIL.*

3~2rdig*,2ldig*,2field*,2padchar*$* prints
2arg*, a flonum, with exactly 2rdig* digits after the decimal
point.  The default for 2rdig* is 2, which is convenient for
printing amounts of money.  At least 2ldig* digits will be printed
preceding the decimal point; leading zeros will be printed if there would
be fewer than 2ldig*.  The default for 2ldig* is 1.  The number is
right justified in a field 2field*
columns long, padded out with 2padchar*.  The colon modifier means
that the sign character is to be at the beginning of the field, before
the padding, rather than just to the left of the number.  The atsign modifier
says that the sign character should always be output.

In some implementations, if 2arg* is unreasonably large, it will
be printed in 3~2field*,,,2padchar*@A* format; i.e. it
will be 3princ*'ed right-justified in the specified field width.
This will not happen in the Maclisp implementation, because the range
provided by flonums is not extremely large.
.c Throw this in here for good measure

.item ~\
This is not really an operator.  If one desires to use a
multi-character 3format* operator, it may be placed within
backslashes, as in 3~\now\* for the 3now* operator.  See
(multi-character-operator-page).
.end_table

.subsection "Defining your own"
.setq define-your-own-section-page section-page

Everything in this section is defined in the lan{maclisp} and
lan{nil} implementations of 3format* only.

.defmac define-format-op
This may be used in two formats:
.lisp
(define-format-op 2operator* 2varlist* 2body-forms...*)
.end_lisp
and
.lisp
(define-format-op 2operator* 2character*)
.end_lisp
The 2operator* may be a character, string, symbol, or fixnum code
for a character (in lan{nil}, it is coerced using the 3string*
function, (string-fun)).  Whichever, it is
canonicalized (into upper case) and will be interned into the same
package which 3format* resides in.
For example, the 3format* operator for 2tilde* could be
defined as
.lisp
(define-format-op \~ #\~)
.end_lisp
For the first format, the type of operator is determined by decoding
2varlist*, which may have one of the following formats:
.table 3 250 500
.item (2params-var*)
An operator of exactly zero arguments;  2params-var* will get
bound to the parameters list.
.item (2params-var*2arg-var*)
An operator of exactly one argument;  2params-var* will get bound
to the parameters list, and 2arg-var* to the argument.
.item (2params-var*.2args-var*)
An operator of a variable number of args;  2params-var* will get
bound to the parameters list, and 2args-var* to the remaining
arguments to 3format* (or to the recursive 3~{*
'c matching "}"
arguments).  The operator should return as its value some sublist of
2args-var*, so that 3format* knows how many were used.
.end_table

A definition for the appropriate function is produced with a bvl
derived from the variables in 2varlist* and a body of
2body-forms*.  (The argument ordering in the function produced is
compatible with that on the Lisp Machine, which is 2arg-var*
(if any) first, and then 2params-var*.)
.end_defmac
.defvar standard-output
Output from 3format* operators should be sent to the stream which
is the value of 3standard-output*.
.end_defvar

.defvar format:colon-flag
.defvar1 format:atsign-flag
These tell whether or not we have seen a colon or atsign respectively
while parsing the parameters to a 3format* operator.  They are
only bound in the toplevel call to 3format*, so are only really
valid when the 3format* operator is first called;  if the operator
does more parameter parsing (like 3~[* does) their values should be
saved if they will be needed.
.end_defvar

The 2params* are passed in as a list.  This list, however,
may be temporary storage only;  one should not allow it to be "passed
back" from the call to the format operator without being copied first.
Also, it is recommended that format 2params* be referenced with
3elt*, and their length obtained with 3length*, in order that
they may be reimplemented as some sort of sequence in the future
(which will probably be a stack-allocated vector for lan{nil}).

Conceptually, 3format* operates by performing output to
some stream.  In practice, this is what occurs in most
implementations;  in Maclisp, there are a few special SFAs used by
3format*.  This may not be possible in all implementations,
however.  To get around this, 3format* has a mechanism for
allowing the output to go to a pseudo-stream, and supplies a set of
functions which will interact with these when they are used.

.defun format-tyo character
3tyo*s 2character* to the 3format* output destination.
2character* may be either an object of type 3character*, or
the fixnum code for a character.
.end_defun

.defun format-princ object
3princ*s 2object* to the 3format* output destination.
.end_defun

.defun format-prin1 object
3prin1*s 2frob* to the 3format* output destination.
.end_defun

.defun format-lcprinc string capitalize?
This outputs 2string*, which must be a string or symbol, to the
3format* output destination in lower-case.  If 2capitalize?*
is not 3nil*, then the first character is converted to upper case
rather than lower.
.end_defun

.defun format-terpri
Does a 3terpri* to the 3format* output destination.
.end_defun

.defun format-charpos
.defun1 format-linel
Return the 3charpos* and 3linel* of the 3format*
output destination.  Since in the lan{maclisp} implementation multiple
output destinations may be implicitly in use (via 3outfiles*, for
instance), this attempts to choose a representative one.  The terminal
is preferred if it is involved.
.end_defun

.defun format-fresh-line
This performs the 3fresh-line* operation to the default
3format* destination.  The hair involved in this is mostly
subsumed by the 3fresh-line* function in lan{nil}.
.end_defun
.defun format-tab-to destination &optional increment
This implements 3~T* to the current 3format* destination (q.v.).
In lan{nil}, it will utilize the 3:tab-to* message if that is
supported.  Otherwise, if it can determine the "current position" of
the format destination, it will output the proper number of spaces;
all else failing, two spaces will be output.
.end_defun

.defun format-formfeed
Performs a 3formfeed* on the 3format* output destination.  In
lan{nil}, this will send the 3:formfeed* message to the stream
if that is supported, the 3:clear-screen* message if that is
supported, otherwise just output the page separator character.  The
3:formfeed* message is supported by a number of lan{nil}
streams, and is designed for just this use.
.end_defun

.defmac format-flatc
.lisp
(format-flatc 2form1* 2form2* ... 2formn*)
.end_lisp
The 2form*s are evaluated in an environment similar to that used
inside of 3format*:  the various 3format* output-performing
routines such as 3format-tyo* and 3format-princ* may be used
to "perform output".  In all but the lan{multics maclisp} implementation,
3standard-output* will be a stream which simply counts the
characters output--it will only support the 3:write-char* operation.
.end_defmac

