path: root/macros/inrstex/inrsdoc/thp2.tex

%-*-tex-*-
\ifundefined{writestatus} \input status \relax \fi %
\chcode{preface}
%\inputtocfiles = {\checklistopen{toc}\inputwithcheck{masth.toc}}
%\catcode`\@=11 \s@ubdocumentfalse \catcode`\@=12 
\tenpoint
\romanpagenumber = 1
\openlistfile{toc}
\opencitationtagfile
\beginprelude
\preludehead{Preface} \specialpagestyle
This volume is a reference manual for \intex\ and \TeX82. It should not be considered a
substitute for the \texbook. Indeed, when there is a conflict between the two
it should be assumed that the \texbook\ is correct. This author expresses an
immense debt of gratitude to 
Donald Knuth, the Grand \TeX Wizard, originator of \TeX, and the
author of the \texbook[\cite{[Knut84]}]. Indeed many of the macros that have been used for
this book have been borrowed from those used for the production of the
\texbook. 

Any deficiencies in the aesthetics of the layout of this book lie with the
author and not the \TeX\ that was used to produce it. \TeX\ is an exceedingly
powerful system. Full exploitation of its capabilities will probably be
limited to a few persons. However, it is possible, and will indeed happen,
that there will be a number of systems based on \TeX\ that will be simple to
use and aesthetically pleasing \dots\ at least in your local environment. 
\intex\ is one of these. 

This book is organized so that the information may be accessed in two ways.
The main objective is to introduce the names and syntax of commands used
in \TeX. \TeX\ is an {\it extensible language}. By this it is meant that it is
possible, and indeed quite easy, to add commands of your own to the set
supplied. The \texbook[\cite{[Knut84]}] discusses in 
detail those that are primitives in the
language and those that have been added in the basic package known as
\plain. There are about 300 primitive and 600 more in \plain. This book
introduces enhancements under the name of \intex. These constitute a document
preparation package that make both an author's and secretary's life
considerably easier. Several hundred more commands are added in \intex.


However, these large numbers should not be considered too frightening. A very
large number of the commands are for special symbols. In fact for most users,
the most useful commands are the ones added
to make the production of documents reasonably simple and automatic. However,
{\it automatic} has its limitations. On the one hand there is the very real
difference between people on what constitutes a beautiful layout, and on the
other there is the problem of describing linguistically an algorithm or
recipe for that individual beauty. 

In fact beauty is usually compromised by expediency. The additional commands
described for the various styles, books, reports, and letters attempt to
balance the two. As much as possible is done automatically. There will be
compromises that are not always appropriate. However, there is always a way,
usually simple, to specifically modify a single item. Actions of this sort
are only taken as a last resort. The problem is that subsequent changes in
other parts may make the specific local change all wrong. It is probably a
truism that there is never  a {\bf final} version of a document. 


\begingroup
\cquote{The best time for planning a book is while you are doing the
dishes.}{Agatha Christie}

\cquote{No man but a blockhead ever wrote except for 
money.}{Boswell's ``Life~of~Johnson (1709-1784)'' [April~5,~1776]}




\ejectpage
\endgroup
%\tracingall
\begingroup
\def\ftn{}%footnote problem
\def\cr{ }%\cr print problem
\let\twelvett=\tentt % ugh!
\preludehead{Table of Contents} \specialpagestyle
\inputtocfiles = { \inputwithcheck{masth.toc} }
\maketoclist
\endgroup
\ejectpage
\ifodd\pageno \vglue 0ptplus1fill
              \pslide \intex// \centergraph{\refoffset h:.75 v:.75 
                                  \btg \inrslogo h:0 v:0 sc:2 
                                     \etg}// \fi
\endprelude
\chcode{Intro}
\pagenumber=0

\def\cqu{\let\folio=\relax 
\cquote{Beauty in things exists in the mind which contemplates them.}{Essays
on Tragedy, David~Hume (1711-1776)}
}



\chapterhead{Intro}{\tex\cr and\cr \intex}

\tex\ is a typesetting 
system\footnote{\dagger}{In fact \tex\ is a very versatile system providing
a powerful language facility that can be used to create author aids
for the production of documents. \intex\ is an example of an integrated
version of such aids.}
developed by Prof. Donald Knuth of Stanford
University for the production of beautiful books. The intent was to
automatically duplicate the format of the second edition of a
text whose first edition was typeset, for the most part, manually. It has
grown, and is becoming the basis of some very powerful document production
systems.

\tex\ is many things. It is first and foremost a language in which to tell a
computer how to {\bf beautifully} typeset text --- all sorts of text. It allows for the use of
symbols such as $\star$, that are not found on your normal typewriter to be
produced by typing |\star| using letters that usually are. It goes beyond the
simple single character and makes it possible to display a mathematics
equation such as 
$$
\sum_{n=1}^k n^2 = {n(n+1)\over 2}
$$
in the middle of the page by just typing
\begintt
$$
\sum_{n=1}^k n^2 = {n(n+1)\over 2}
$$
\endtt
It produces better looking words by moving the ``a'' closer to the ``T'' in
such words as ``Tag'' to compensate for the visual effect of the overhang of
the top of the ``T''. It produces better looking paragraphs by absorbing the
whole paragraph before attempting to break lines. This means that decisions
near the top will not lead to disasters later on. It produces better looking
pages by considering what is on the following page before attempting to break
the present one. This prevents such visual disruptions as those 
caused by single line paragraphs at the top or bottom of pages. 

\tex\ is rapidly becoming the basis of document preparation systems,
including \intex\  described in this book.
Documents are made up of parts that are not usually
thought of in terms of how they look. Parts such as sections, paragraphs,
lists, footnotes, chapters, introductions or prefaces. \tex\ has very
powerful facilities for creating systems for dealing with these parts and
making decisions on how they should be displayed. These facilities really
make up a language whose {\it primitive} parts are used to make more powerful
parts. 

\shead{TeXlevels}{The \tex\ language --- primitive, plain, and extended}

As with most systems, the
more complex parts are built from more primitive parts. {\it Primitives} in
\tex\ supply the fundamental facilities for both typesetting and language
extension. The first set of extensions are those in the {\it plain} package
supplied with a {\it raw} \tex\ system. The definitive description of 
the \tex\ {\it primitives}, and the associated extension {\it plain}, is in
the \texbook\ of Donald Knuth. The \texbook\ shows how to use these commands
and explores some of the implications. 

The \texbook\ is aimed at all users of
\tex\ --- the system builder and the end user. This book is aimed primarily
at the end user and more especially the user of \intex. 
It briefly discusses the basic text and page building
philosophy on which \tex\ is based. 
It gathers together most, but not all of the commands in the
\texbook\ and displays their required syntax, and gives some uses. It does
not explore them too deeply. Further examples will be found in the 
{\bf \tex\ Example Book} that will be published as soon as it is compiled.

In addition it describes \intex, a document preparation system that has been built on
top of {\it plain}. At present, this includes styles for papers, reports, and
books. In addition it aids in the preparation of documents by automatically
generating, tables of contents, simple indexes, and numbering such
as chapters, sections, equations, tables. Finally it allows for symbolic
referencing of any of these parts. 

\shead{editors}{\tex\ editors}
Any text editor can be used to create a \tex\ document. Only those characters
normally found on a keyboard are used and there are facilities in \tex\ to
allow for those special keyboards and screen systems that can display
different characters. For instance it might be that a French keyboard has the
letter \'e on it and the screen can display it in that form. This can be
encoded as single key and translated by \tex. Less capable keyboards would
actually type a |\'e| to obtain the \'e.  

Another feature that makes life easier for producing a document on a text
editor is the ability to match a left |{| with a right |}|.
\tex\ uses these extensively to {\it group} things together and sometimes can
get upset in quite mysterious ways when they do not. 
It is also quite useful to be able to edit several parts of the
document at the same time. Newer editors allow this.

A \tex\ editor does not really exist \dots\ for a number of reasons. 
A major objective of such an editor  would be 
as a means of catching (\tex) errors on
input and to facilitate modifications of the file for better layout. An
editor of that sort must know an awful lot, not only about \tex, but also
your extended version. Another objective would be to allow coordinated views
of the input file and the \tex printed output,
so that the effect of both major and
minor changes would be evident. This is conceivable, but still for the
future. 

It is possible to argue that an editor that ``showed you what you get'' is
ideal for a document preparation and typesetting system. The difficulty with
this argument is that there is no language that adequately encompasses the
graphics on the screen with the place of, say a summation sign, $\sum$ in a
mathematical equation. In some cases the semantics of the resulting document
is varied by a change in the display format and in other cases it is not. 
In some cases different semantic objects, such as an {\it IF} in a computer
program and the {\it if } in a sentence are distinguished by font style, and
sometimes not. At the document level, it is the semantics of the entity that
is important. It may or may not show up in a format change.

\shead{gentyp}{Generic Typesetting}
The opposite extreme to the ``see what you get'' school is the giving of
semantic tags to each entity in the document and deciding later how they will
be displayed. This means that it is possible to change your mind about the
way a, say {\it keyword}, will be displayed and change it consistently
throughout the document. This approach appears to be possible in a
constrained environment and has been successfully applied by
DIGITAL[\cite{[Digi83]}] to the production of their manuals for the VAX11/780.
\tex\ can be the basis of such a system too.

\shead{intexintro}{\intex}
\intex\ is 
a system to aid in the preparation of documents in several languages using
ordinary fonts. The system, excluding its graphics component, is usable
with any \TeX\ system but is most useful, when using ordinary {\tt cm}
fonts with an ML\TeX\ system. The graphics component will work with any
reasonable PostScript printer and driver. The version at INRS/BNR uses a
modified version of Nelson~Beebe's DVIALW on the VAX/VMS and the IBM~PC and
uses Tom~Rokiki's DVIPS on the UNIX workstations. 
The two languages actually used are French and English. The
pieces, all relatively independent, are as follows:
\beginlist
\li $\bullet$ the \intex\ macro package kernel. This includes all the
facilities needed for 
\beginsublist
\tightenlist 
\li $\circ$ section and chapter heads,
\li $\circ$ lists,
\li $\circ$ {\bf easy} tables,
\li $\circ$ {\it floating} figure and table insertions, 
\li $\circ$ footnotes,
\li $\circ$ automatic generation of table of contents, list of figures, and
list of tables, 
\li $\circ$ automatic numbering of equations, section heads, etc.,
\li $\circ$ symbolic referencing of equations, sections, etc.,
\li $\circ$ optional margin notes to aid in keeping track of symbolic
references, 
\li $\circ$ automatic generation of citation lists (IEEE style only)
\li $\circ$ a {\it subdocument} feature for building large documents in
pieces.
\endsublist
\li $\bullet$ additional packages for special forms. The modular form of the
kernel allows for modifications of what is inside and out. At the present
these include 
\beginsublist
\li $\circ$ a verbatim style using {\tt typewriter} fonts for such things as
program listings,
\li $\circ$ a several document styles including a |<<PAPER STYLE>>|, 
|<<BOOK STYLE>>|, |<<REPORT STYLE>>|. Some of these are rather specialized.
\li $\circ$ \TeX graph, a graphics system for drawing figures and inserting
external figures. This uses the graphics primitives of  a PostScript
printer. It is {\it inside} rather than outside the \TeX\ system.
\li $\circ$ memo macros {\bf including} graphics for letterhead, 
\li $\circ$ slide making {\bf including} graphics for letterhead, 
\endsublist
\li $\bullet$ templates for various styles. This makes their use as easy as
filling in blanks. 
\li $\bullet$ {\bf MLTeX} is an {\bf extension} to \TeX\ 3.+ that
allows hyphenation of words with explicitly accented letters 
words while using ordinary {\tt cm} fonts.
\li $\bullet$ {\bf DVIALW}, a PostScript driver, written by Nelson~Beebe 
has been modified by INRS to allow inline PostScript for \TeX Graph.
There is also a version of \TeX Graph that will work with 
Tom~Rokiki's {\bf DVIPS}. 
\endlist
\noindent
\intex\ may be viewed from several perspectives. 
\beginlist
\li $\bullet$ At the user level, it is a
set of procedures that augment the {\it plain} macros supplied with \TeX.
These aid the author in building  a document by making shuffling of such
things as sections, equations, figures, and tables sufficiently painless that
they will be done. It helps the secretary/typist by making it easier to
respond to changes. To work most effectively, the author, at the
{\it pencil} input level, should be aware of the power of the system. 
\li $\bullet$ At the document formatting level, parameters and features are
available to modify various spacings, headers, footers, etc. 
\li $\bullet$ At the document design level, the various internal formatting
forms are available, {\bf independently} of the housekeeping functions for the
automatic generation of section, equation, and figure numbers, or such things
as the table of contents. 
\endlist

\shead{language}{English and French --- Together}
\intex\   supports  both English and French document preparation,
and is easily extendable to other languages . It does this through
the generation of messages and various forms from within the \intex\ kernel
and through the \mtex\ extension that allows for language dependent hyphenation
of words with and without accents. An example of a kernel form variation is the
change from ``Chapter'' to ``Chapitre'' when a |\chapterhead| is called in
French rather than in English. |\englishversion| calls the English forms and
|\versionfrancaise| the French forms. 


\shead{scope}{Scope of Book}
This book will introduce the first version of the document preparation
system, to be called \intex, that is used at INRS/BNR. 
It will describe virtually all of the symbols and
commands that have been introduced in the \texbook\ with the exception of
those used for symbol definitions and output routines. All of the accessible
and changeable parameters will be listed and grouped according to function.

Most chapters will begin with a list of commands that will be discussed in that
chapter. Some discussion of where and how these will be used and what will be
accomplished using them follows. Then there will be a list of the individual
commands with their normal usage syntax. An index of these commands will be
found at the end of the book.

\ejectpage
\chcode{descom}
\def\cqu{\cquote{We ought to give the whole of our attention to
the most insignificant and most easily mastered facts, and remain a long time
in contemplation of them until we are accustomed to behold the truth clearly
and distinctly}{Rules for the Direction of the Mind, Rule IX, 
Ren\'e~Descartes (1596-1650)}}

\chapterhead{descom}{\tex\ COMMANDS:\cr DESCRIPTION\cr FORM}
In this book commands, command parameters, and characters that you might be
expected to type in at a terminal are shown in {\tt typewriter} font. Thus a
file that would typeset the  23$^{rd}$ psalm below
\medskip
\beginnarrowtext 1in
\eightpoint
\obeylines
The Lord is my shepherd, I shall not want;
He maketh me to lie down in green pastures,
He leadth me beside the still waters;
He restoreth my soul.
\endnarrowtext
\noindent
is given  by 
\begintt
\beginnarrowtext 1in
\eightpoint
\obeylines
The Lord is my shepherd, I shall not want;
He maketh me to lie down in green pastures,
He leadth me beside the still waters;
He restoreth my soul.
\endnarrowtext
\bye
\endtt

The actual commands and their meaning will be described in later chapters. 
However, it should be possible to guess what they do from their common sense
meaning (noting, of course that a |\| starts a command). 
When a listing is shown in this manner, it is assumed that each line
is terminated by a |<return>|. The |<return>|, abbreviated by |<cr>| will
only be explicitly shown when there might be some confusion.

\shead{telltex}{Commands TO \tex\ and \intex }
A command is the way to tell \tex\ to do something. \tex\ responds to both
{\it verbose}, single character commands, and {\it one} implicit command.
Verbose commands always start with an {\it escape character} which for most \tex\
systems, and in this book, is the backslash |\|. The command name is
a string of {\it letters} and the end of the command is shown by a
non-letter, usually a blank, although a number such as 1, or a special
character such as |{| or |,| will do.

A typical 
verbose command
might be the |\beginnarrowtext| used above. It takes a parameter which is a
{\it dimension} and is delimited by a final space. The form of the command
description would be |\beginnarrowtext <indent dimen>|\]. 
{\bf Note that the brackets |<| and |>| should not be typed.}
If a parameter or entity in the command is optional it is enclosed in
square brackets |[...]|.
For example, the  $=$ 
when setting the {\it outer page size} as in
|\houterpagesize [=] <page size dimen>| is optional. Readability suggests
that they should be included.
{\it Verbose} commands ignore spaces between the command and the following
text. 

Single character commands are not preceded by a |\|, obviously, and exist
primarily to improve readability and ease of typing. An example is |^| for
superscripting or |~| to {\it tie} two words together. The major difference
between these and the verbose commands is that spaces or blanks after them
are {\bf not} ignored. 

Finally, \tex\ has one implicit command, namely a blank line, which signifies
the end of a paragraph and hence is equivalent to |\par|. Several blank lines
are equivalent to only one. In addition, a line that has only a \tex\
comment, for example
\begintt
%This line is a TeX comment because it starts with a %
\endtt
is a blank line. |\par| and blank lines are {\bf not} allowed in |\halign| or in
display mathematics mode. 

\shead{comdesc}{\tex\ Command Description}
The general form used to describe \tex\ commands is 
\begintt
\<command> <parameters>
\endtt
If blank space is shown in the description, that space is optional and there
can 
be several of them. In fact the command can be split at that point and placed
on the next line with no ensuing problems. On the other hand a \] implies that
the blank space {\bf must} be there. 

Finally the commands are shown preceded by one of $\bullet$, $\diamond$, or
$\star$, and are {\it primitive}, {\it plain}, or \intex\  respectively.

\ejectpage
\done