diff options
Diffstat (limited to 'obsolete/macros/inrstex/inrsdoc/thp2.tex')
-rw-r--r-- | obsolete/macros/inrstex/inrsdoc/thp2.tex | 420 |
1 files changed, 420 insertions, 0 deletions
diff --git a/obsolete/macros/inrstex/inrsdoc/thp2.tex b/obsolete/macros/inrstex/inrsdoc/thp2.tex new file mode 100644 index 0000000000..850fd38aae --- /dev/null +++ b/obsolete/macros/inrstex/inrsdoc/thp2.tex @@ -0,0 +1,420 @@ + + +%-*-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 + |