\input nice
\article
\marklevel=2 \contentslevel=2
\font\verbatimfont=cmtt10 \vbaselineskip=\baselineskip

\font\commandfont=cmtt10 scaled \magstephalf
\def\command#1#2{\noindent\line{\commandfont \\#1 \subsubsectiontitlefont --
        #2\hfil}}
\def\iline#1{\parwithoutskip\hbox{\hskip20pt #1}\parwithoutskip}

\titlepage
\title {NICE -- an useful enhancement for plain\TeX}
\author {* by CR *}
\bigskip
\release{Description of Version 1.4}
\bigskip
\release {26/07/89 \rm (last change)}
\vfil
\abstract \baselineskip=15pt
NICE is a macro packet which provides useful commands in addition to
plain\TeX's facilities. The structure of plain\TeX\ is preserved, so the
user doesn't have to deal with a new command language. This article
is a short description of the new commands introduced by NICE.

\baselineskip=12pt
\bf NOTE: Since the documentation for the new NICE version~1.5 is not yet
available, this documentation for the older version~1.4 is included.
You can use all features of version~1.4 in version~1.5 unless for
exceptions stated explicitly in the text.

\endtitlepage

\plainsection {Contents}
\bigskip
{\baselineskip=18pt \makecontents}
\newpage

\section {Changes to plain\TeX's behaviour}

When using NICE, the behaviour of plain\TeX\ is changed in two ways: The
setting of some parameters is different, and a few commands have slightly
changed their effects.

\subsection {Parameters}

{\noindent \parskip=0pt
{\tt \\voffset} and {\tt \\hoffset}: The setting of these parameters is
system dependent.

{\tt
\\vsize=9.2 true in \\hsize=6.5 true in

\\smallskipamount=6pt plus 1pt minus 1pt

\\medskipamount=12pt plus 2pt minus 2pt

\\bigskipamount=18pt plus 3pt minus 3pt

\\parskip=6pt plus 1pt minus 1pt

\\parindent=0pt

\\tolerance=10000

\\hbadness=5000
}
}

\subsection {Commands}

The {\tt \\footnote}-macro of plain\TeX\ is now available as {\tt
\\plainfootnote}. Now {\tt \\footnote} does an automatic numbering of
footnotes.

Since {\tt \\parindent} is set to 0pt, {\tt \\narrower} would produce
no effect. So {\tt \\narrower} was changed to increase {\tt \\leftskip}
and {\tt \\rightskip} by the value of the new parameter {\tt \\narrowskip}.

The {\tt \\vfootnote}-macro of plain\TeX\ uses {\tt \\parindent} for
the hanging indentation of footnotes. This has been changed:
Now all footnotes are displayed
with a hanging indentation of 20pt.

\section {New NICE commands}

\subsection {Fonts}

There are four fonts defined for use in titels and headings:

The {\tt \\documenttitlefont} is cmr10 at \\magstep4 and is only used
to design the title page of a document. {\tt \\sectiontitlefont},
{\tt \\subsectiontitlefont} and {\tt \\subsubsectiontitlefont} (each
cmbx10 at \magstep2, \magstep1, \magstephalf, resp.) are used for the
headings of sections, subsections and sub-subsections.

\subsection {General utilities}

\command{newpage}{immediate page break}
After this command, the old page is finished, and the following text
starts at the next page.

\command{raggedcenter}{center text}
The following text is no longer displayed justified, but centered instead.
This command should only be issued inside a group, otherwise the centering
would last to the end of the document.

\command{parwithoutskip}{new paragraph without parskip}
Has the same effect as {\tt \\par}, but does not append the {\tt \\parskip}
glue. This only works if the new paragraph is started immediately after
this command.

\command{narrower}{narrower setting of lines both left and right}
Advances {\tt \\leftskip} and {\tt \\rightskip} by the current value
of {\tt \\narrowskip}, which is set to 20pt by default. If you do not want
to continue the narrower setting throughout the rest of the document, you
should issue this command inside a group. If you use this command inside
a paragraph, the whole paragraph will be typed narrower, so a new paragraph
should be started before a {\tt \\narrower} to prevent unwanted effects.

\command{lnarrower}{narrower setting of lines, left only}
Like {\tt \\narrower}, execpt that the value of {\tt \\rightskip} does not
change.

\command{\\}{backslash}
Produces a ``\\'' by a temporary shift to math mode.


\subsection {Section layout}

NICE provides commands to split a document into sections, subsections and
subsubsections (referred to as ``items'' for the rest of this subsection).
The headings of these items are automatically numbered and can be placed
as headlines on the top of every page. There is another feature which
adds item headings to a table of contents.

Section numbering normally starts with ``1'' and continues until an
appendix is introduced with the {\tt \\appendix}-command. From this point,
sections are numbered with capital letters, beginning with ``A''.

It is guaranteed that a page break never occurs after an item heading.

\command{section \#1}{generate numbered section heading}
Generates a section heading in the form
\iline {$<$sectionnumber$>$. \#1}
typeset with the {\tt \\sectiontitlefont}.
if {\tt \\contentslevel} $>$ 0, this heading is included in the table of
contents. if {\tt \\marklevel} $>$ 0 and the heading
is the first heading
on this page, it is also displayed as headline of the current page.
The count for subsections is reinitialized, so numbering of subsections starts
with ``1'' again.

\command{subsection \#1}{generate numbered subsection heading}
Generates a subsection heading
\iline {$<$sectionnumber$>$. $<$subsectionnumber$>$. \#1}
typeset with the {\tt \\subsectiontitlefont}.
if {\tt \\contentslevel} $>$ 1, this heading is included in the table of
contents. if {\tt \\marklevel} $>$ 1 and the heading is the first heading
on this page, it is also displayed as headline of the current page.
The count for subsubsections is reinitialized,
so numbering of subsubsections starts
with ``1'' again.

\command{subsubsection \#1}{generate numbered subsubsection heading}
Generates a subsubsection heading
\iline {$<$sectionnumber$>$. $<$subsectionnumber$>$.
$<$subsubsectionnumber$>$. \#1}
typeset with the {\tt \\subsubsectiontitlefont}.
if {\tt \\contentslevel} $>$ 2, this heading is included in the table of
contents. if {\tt \\marklevel} $>$ 2 and the heading is the first heading
on this page, it is also displayed as headline of the current page.

\command{plainsection \#1}{generate section header without numbering}
The parameter is printed as section heading (with {\tt \\sectiontitlefont})
without affecting the section
numbering.
if {\tt \\contentslevel} $>$ 0, the heading is included in the table of
contents. if {\tt \\marklevel} $>$ 0 and the heading
is the first section heading
on this page, it is also displayed as headline of the current page.

\command{appendix}{start appendix}
Set up the section numbering for appendices so that the following sections
are numbered with capital letters.


\subsection {Page layout}

The following commands set up the page head- and footlines
for articles and books properly. One of the following commands must be
used if displaying a section heading is desired to appear as page headline.

\command{book}{set up head- and footline for book printing}
Set up the headline on every page in the following way:
On the first page, the headline is always empty. On the following pages,
the headline contains a section heading (or subsection or subsubsection
heading, according to the value of {\tt \\marklevel}) and the page number.
For odd pagenumbers, the section heading is left justified and the page
number is right justified. On pages with even number, alignment of
section heading and page number goes just the other way round, so when using
the document as a book, the page numbers are always situated near the edges
of the book.
The headline is separated by a {\tt \\hrule} from the page contents.
The fine positioning of this rule can be controlled by the dimension
parameter {\tt \\hdrulepos}.
After using this command, the footline is empty.

\command{article}{set up head- and footline for article style}
This command is similar to {\tt \\book}, unless alignment of section
headings and page numbers does not change throughout the whole document:
The section headings are always placed left and the page numbers are
always on the right of the headline.

\subsection {Titlepage layout}

With the following set of commands, the first page of a document can be
turned into a title page, only containing the title of the document,
name of the author, some related details and an abstract.

\command{titlepage}{enter titlepage mode}
After issuing this command, a set of special commands for designing
the title page is made available. These commands are described below.
Note: This command introduces a new level of grouping, so changes to
parameters remain in effect only until {\tt \\endtitlepage}.

\command{title \#1}{typeset title of document \rm (available only in
titlepage mode)}
The title of the document is printed in centered mode with the
{\tt \\documenttitlefont}.

\command{author \#1}{typeset author of document \rm (available only in
titlepage mode)}
The name of the author is printed in centered mode with the normal {\tt \\rm}
font. Since this command is defined {\tt \\long}, you can include additional
information (like address or name of the institute) on separate lines.

\command{release \#1}{typeset other information \rm (available only in
titlepage mode)}
This command can be used to typeset some other information to appear
on a single line at the titlepage (e.~g.\ the version of a document).
The text is centered with the normal {\tt \\bf} font.

\command{abstract}{begin typesetting of abstract\rm (available only in
titlepage mode)}
After issuing this command, a short summary (the ``abstract'') of the
documents contents should be given. This abstract is typed in
{\tt \\narrower} mode with a {\tt \\narrowskip} of 3~true~cm and is
preceded by a heading named ``Abstract'' in boldface letters.
The {\tt \\abstract}-command is finished when the titlepage ends, so it
must be the last command in titlepage mode.

\command{endtitlepage}{end titlepage mode, eject titlepage \rm (available only
in titlepage mode)}
This command is used to end the typesetting of the titlepage. After using
this command, following text starts on a new page.

The whole stuff on a titlepage not only becomes centered horizontally,
but also vertically. It is recommended to
separate the items on the titlepage occasionally by {\tt \\vfil}-commands
to obtain a balanced layout. Here's one suggest for designing a titlepage:
\beginverbatim
   \titlepage
   \title {...}
   \release {...}
   \bigskip
   \author {...}
   \vfil
   \abstract
      ...
   \endtitlepage
\endverbatim

\subsection {Table of contents}

\command{makecontents}{build table of contents}
This command has two effects:
\itemlist {- }
\next It reads a table of contents generated by a previous run of \TeX.
\next It sets things up so that the following section headings etc.\ will
go to a special contents (toc) file (which is read by the next run of \TeX).
Section headings are indented by the value of {\tt \\scindent}, subsection
headings by the value of {\tt \\sscindent} and subsubsection headings by
the value of {\tt \\ssscindent}. For every heading, the page number on which
the heading appears is included at the right.
\enditemlist
Due to this way of maintaining the table of contents,
it must appear in the text
before any items that shall go to the table of contents are encountered
(so it is usually the best to include it immediately
after the titlepage). Since the toc file read in reflects the situation of the
previous run of \TeX, it is necessary to run \TeX\ twice to obtain a DVI
output with the correct table of contents.
Note: {\tt \\makecontents} only inserts the table of contents at the current
text position, so you have to supply commands for proper appearance
of the table.


\subsection {Footnotes}

\command{footnote \#1}{generate numbered footnote}
This command works like in plain\TeX, except the the footnote marker is an
automatically supplied number. Footnote numbering starts at ``1''.


\subsection {Staggered layout}

There is a number of macros for typesetting various itemized lists.
The {\tt \\staggered}-command is designed for general lists with any key value,
the others are for some special cases. All commands which switch to list
mode set {\tt \\parskip} to 0pt~plus~0.5pt and then perform a {\tt \\par}.

\command{staggered \#1}{typeset staggered list with arbitrary key values}
A staggered list is a number of keys together with a describing text
for every key. The key is set left justified, the describing text is set
right to the key with an offset of the longest key from the left margin.
The parameter of this command represents the longest key with additional
spacing to put after this key.

\command{key \#1}{typeset key of staggered list \rm (only valid when
typesetting a staggered list)}
Add the key with the value of the first parameter to the current staggered
list. The describing text must follow this command.

\command{endstaggered}{end staggered list}
The current staggered list is finished.

\command{itemlist \#1}{typeset staggered list with all key values equal}
This command is designed for typesetting a staggered list in which all
keys have the same value. This value (together with spacing to put after
the key) is represented by the parameter to this command.
Items are added with the {\tt \\next}-command.

\command{enditemlist}{end itemlist}
The current itemlist ist finished.

\command{numbered \#1}{typeset numerical numbered list}
Use this command to generate a numerically numbered item list.
The parameter value is the number of decimal digits of the number of
entries (e.~g.\ 2 if there are more than 9, but less than 100 entries).
The list numbering starts with the value ``1''. New items are added
with the {\tt \\next}-command.

\command{endnumbered}{end numerical numbered list}
The current numerical numbered list is finished.

\command{alphanumbered}{typeset alphanumerical numbered list}
The keys of the items are of the form ``a)'', ``b)'', ... New items
are added with the {\tt \\next}-command.

\command{endalphanumbered}{end alphanumerical numbered list}
The current alphanumberical numbered list is finished.

\command{next}{add next item to list \rm (only valid within a list)}
The text that follows this command is added as new item to the current
list. The key value depends on the type of the list (item, numerical,
alphanumerical).


\subsection {Verbatim mode}

The verbatim mode is used to display text exactly as typed.

\command{beginverbatim}{switch to verbatim mode}
The verbatim mode is enabled until the {\tt \\endverbatim}-command is
encountered. The font used within verbatim mode ist controlled by
the {\tt \\verbatimfont} font parameter, which is set to cmtt10 by
default. You should only use fonts from the cmtt and cmtex series,
otherwise the special symbols will show up as other characters.
You can change the verbatim mode baselineskip by altering the
{\tt \\vbaselineskip} parameter, which is set to the initial
{\tt \\baselineskip}-value by default.

\command{endverbatim}{leave verbatim mode}
The verbatim mode (which must have been enabled by a previous
{\tt \\beginverbatim}-command) is disabled.

Use these two commands to enable verbatim mode for whole lines of text.
If you want to enable temporary verbatim mode in the middle of a line, and only
for a few characters or words, you can use the vertical bar ``$|$'' to
toggle verbatim mode. This only works when not in math mode. In math
mode, the vertical bar preserves its old effect from plain\TeX. The
{\tt \\verbatimfont} does also apply to temporary verbatim mode, but
{\bf not} the {\tt \\vbaselineskip} setting.


\subsection {Miscellaneous macros}

\command{include \#1}{insert contents of file}
Has the same effect as {\tt \\input} if the file exists. If the file
does not exist, a message announcing this fact is written to the terminal,
and typesetting continues.

\command{0 ... \\6}{generate german umlaut characters}
These seven commands generate ``\ss'', ``\"a'', ``\"o'', ``\"u'', ``\"A'',
``\"O'', ``\"U'', resp. {\bf NOTE: These commands are obsolete and going
to disappear in version~1.5.}


\section {NICE parameters}

This section gives an overview of the additional nice parameters with
their default values.

\noindent
\halign{\tt #\hfil\quad & #\hfil\quad & #\hfil\cr
\rm Parameter & Default & Meaning\cr
\\narrowskip & 20pt & indentation value for {\tt \\narrow} and
{\tt \\lnarrow}\cr
\\contentslevel & 1 & amount of information that goes to the table of contents
(see below)\cr
\\scindent & 0pt & indentation for section headings in the table of contents\cr
\\sscindent & 12pt & indentation for subsection headings in the table of
contents\cr
\\ssscindent & 32pt & indentation for subsubsection headings in the table
of contents\cr
\\marklevel & 1 & the level of section headings that are displayed in the
headline (see below)\cr
\\hdrulepos & -2pt & the vertical offset of the underlining rule for
the headline\cr
\\verbatimfont & cmtt10 & the font used within verbatim mode\cr
\\vbaselineskip & 12pt & the baselineskip within verbatim mode\cr
}

The parameters {\tt \\contentslevel} and {\tt \\marklevel} can take the
following values:
{\vskip0pt \lnarrower \staggered {0: }
\key{0:} no information included
\key{1:} section headings only
\key{2:} section and subsection headings
\key{3:} section, subsection and subsubsection headings
\endstaggered}


\bye