%-*-tex-*- \ifundefined{writestatus} \input status \relax \fi % \marginnotestrue \chcode{start} \def\cqu{} \draftversion \chapterhead{start}{STARTING\cr STOPPING\cr and FINISHING} This chapter discusses the commands that are required to actually process a \tex\ or \intex\ document, and to answer the ``|?|'' when \tex\ runs into an error. Section~{\ref{printing}} gives the most important options available in \tex print, the program that actually prints the \intex\ file. Since the initial production of a document is almost always in the ``draft'' mode, the \intex\ default is |\draftversion|. This mode includes the ``{\eightrm Draft Version :} {\eightit Date}'' at the bottom of the page and margin notes that include {\it tags} and their values. This version of the book was a produced with |\draftversion| but with |\marginnotesfalse| for all but this chapter and the one on auto numbering and tagging (\ref{auto}). The really {\bf final} version of this book will probably be produced with |\finalversion|. Section~\ref{finalversion} discusses the changes to make when processing the ``final'' version of a document. \intex, especially in conjunction with Multilingual \mtex, supports both English and French \dots\ in the same document on a paragraph by paragraph basis. English, both for \intex\ messages and hyphenation is the default and is called by |\englishversion|. |\versionfrancaise| invokes French messages, hyphenation, and spacing. To change only the hyphenation and spacing, |\ehyph| is used for English and |\fhyph| is used for French. \shead{startcom}{Command List} The commands in this list are organized in three sections, Creation, Termination and Language, \tex print, and ``?'' answer and interrupt. The Language commands include those related to choosing the particular language (French or English) and efficient commands for just changing spacing and hyphenation rules and not the messages. \comhead{Creation, Termination and Language Commands} \begintwocolumn \pla|\bye| \ext|\done| \ext|\draftversion| \ext|\ehyph| \pri|\end| \ext|\englishversion| \ext|\fhyph| \ext|\finalversion| \pri|\hyphenation| \ext|\language| \ext|\marginnotestrue| \ext|\marginnotesfalse| \ext|\versionfrancaise| \endtwocolumn \shead{Doc}{Document Creation} To create a document, you first need something to write. Enter the text into a file on whatever system you are using. In this book it is assumed that the system you are using is a VAX11/780 running the VMS operating system with the appropriate file names or system conventions. There are basically three steps to producing a document. The first is to enter the information, with all of the appropriate \tex\ conventions into a file. The second is for \tex\ to process it, and the third is for \tex print, \tex's printing system to print it out. Any output device that supports typesetting can be used if it has been properly configured for \tex. This could be a dot matrix printer (heaven forbid), a phototypesetter such as the Alphatype, or PostScript laser printer. \shead{docprep}{Preparing the File} All that is required to prepare the file is to create the file using your favourite editor. You might try the example given in Chapter \ref{descom}. A file of \tex\ commands is normally given the name |.tex| and it can be referred to by only || with \tex\ automatically extending it. To tell \intex\ that the your file has is completed, the command |\done| should be the last command in the file. \tex\ will ignore everything after a |\done|. |\done| not only terminates the file, it also {\it fills} the last page so that the spacing is correct. The primitive command for \tex\ to terminate processing is |\end|. This is {\bf not} recommended while using \intex\ because the last page is not reasonably processed and it will terminate processing while inside a subdocument, something not ordinarily desired (see Chapter~\ref{subdoc} for discussion on the details of subdocuments). {\it Plain} \tex\ supplies the command |\bye| which has an |\end| imbedded in it and also cleans up the last page. |\done| is similar but has a few additional features including a compatibility with the |\subdocumentmacros| commands. |\done| is recommended for use in \intex. \shead{subfile}{\tex ing a File} After the file has been completed, you leave the editor and return to the operating system where you will be greeted by the prompt of a \$\ sign. For example if the 23$^{rd}$ psalm file is called |psalm23.tex| then \begintt $inrstex psalm23 \endtt This will submit the job. If you forget to put in your file name, \tex\ will return with its interactive prompt, the |*|, and ask you for a file name. At this point you will see the following on your screen. \begingroup \eightpoint \begintt This is MLTeX, Version 3.1+ (psalm23.tex [1] ) Output written on psalm23.dvi (1 page, 540 bytes). \endtt \endgroup Do not be deceived. \intex\ was indeed loaded \dots\ the evidence will be in the |psalm23.lis| file. The directories containing the files are completely given, and will be yours instead of that shown. The |psalm23.log| shows that \intex\ was indeed preloaded. This file contains \begingroup\eightpoint \begintt This is MLTeX, Version 3.1+ (format=inrs3_mlb 91.8.22) 2 SEP 1991 02:59 **&/usr/users/u1/mike/inrstex/inrs3_mlb psalm23 (psalm23.tex [1] ) Output written on psalm23.dvi (1 page, 540 bytes). \endtt \endgroup The version numbers, for both \tex\ and \intex\ will vary with time and installation. If you are not using ML\TeX\ the two ``version'' lines will be more like \begingroup\eightpoint \begintt This is TeX, Version 3.14 or This is TeX, Version 3.14 (format=inrs3_mlb 91.8.22) 2 SEP 1991 02:59 \endtt \endgroup for the terminal and list file respectively. The default form of the interaction of \tex\ with you is to stop on an error. At an error, the display will halt and \tex\ gives you a ``~{\tt ?}~'' as a prompt. At this point if you reply with an |x| or an |e|, the job will terminate cleanly and you can print what you have to that point. An |s| will cause \tex\ to continue, but not to pause for further errors; a || will continue to the next error; an |r| is like |s| but will not stop even if it cannot find a file; a |q| is a nonstop mode that also suppresses all output to your terminal. Sometimes \tex\ seems to be in deep trouble and cannot extricate itself. At this point |^C| or | C| will send \tex\ a message that it should stop. It will after the end of its present command, and return to you the ``~{\tt ?}~''. At that point an |x| will terminate the job, {\bf and} give you output that you can print. If all else fails, a |^Y| will terminate the job, uncleanly, and there will be no help to fix it. Sometimes \tex\ stops with an |*|. When this happens \tex\ is looking for a command. Usually an |\end| or |\done| will satisfy it and terminate cleanly. Finally, \tex\ sometimes has trouble reading a file and asks for another name. The only way out of this, cleanly, is to give it a file name. You should have an empty or |null.tex| in your directory for such eventualities. This will allow \tex\ to continue whereupon a |^C| will interrupt. \shead{additionalfiles}{Additional Files} Whenever \tex\ processes a job (your file), it creates an internal name that is referred to in a \tex\ file as \@|\jobname|. This is the same as the file name submitted to \tex\ or \intex\ {\bf without} the |.tex| extension. Both \tex\ and \intex\ use this |\jobname| to create other files with different extensions. All \tex\ and \intex\ jobs create create a second file called |\jobname.lis|. In this file is a complete listing of the messages and prompts sent to your terminal along with information about problems that may have existed. It is useful for correcting errors. If there is any output that can be printed, this is placed in a file with the name |\jobname.dvi|. This is the file used by \tex print. In addition to these two files, \intex\ creates and uses files for special purposes such as building table of contents, lists of figures, or citation lists. These are only produced when some automatic feature of \intex\ is active. The complete list of these files is \bshortcomlist |\jobname.ctg|&created by the first |\cite| command used to accumulate the citation tags for a list of citations or references.\cr |\jobname.cfm|&{\bf NOT} created by \intex\ but by the user. This file holds the citation forms to be used when actually printing the citation in the list of citations. \cr |\jobname.dvi|&created by \tex\ for any (partly) successful \tex\ or \intex\ job. This is used by \tex print.\cr |\jobname.fig|&created with a |\openlistfile{fig}| and used to accumulate the figure list.\cr |\jobname.lis|&created by \tex\ for all jobs. This contains the terminal messages and errors along with more detail on overfull boxes.\cr |\jobname.tag|&created by |\autonumberingon| and used to accumulate the tags and other special information necessary for symbolic references to sections, equations, etc in the text.\cr |\jobname.tbl|&created with a |\openlistfile{tbl}| and used to accumulate the table list.\cr |\jobname.toc|&created with a |\openlistfile{toc}| and used to accumulate the table of contents.\cr \eshortcomlist \shead{printing}{\tex print --- Printing your Document} After \tex\ has successfully produced your |.dvi| file it is submitted for printing, using the same example, by \begintt $dvialw psalm23 -b \endtt \intex\ makes the same irrational assumptions of drivers as other macro packages such as {\tt plain}, namely that the initial position on the page is at (1in, 1in). However these assumptions are not hard wired. \intex\ has two commands |\hprintoffset| and |\vprintoffset| which are given default values of 1in respectively. These may be changed at will. \beginblockmode \ext\@|\hprintoffset = | \nbr This offsets, horizontally, \intex's natural margins, which would be flush with the top of the page by {\tt }. The default is |\hprintoffset = 1in| \mbr\ext\@|\vprintoffset = | \nbr This offsets, vertically, \intex's natural margins, which would be flush with the top of the page by {\tt }. The default is |\vprintoffset = 1in| \endblockmode The {\tt -b} option prints the pages {\tt backwards}, really normal, order from the lowest number to the highest. A simple batch file can hide this messiness\footnote{\dagger}{For the INRS/BNR VAX } use {\tt HELP DVIALW to find a list of all the command line options.}. The most important command line option that you can use gives the ability to print only a few pages of the file. {\tt DVIALW} reports output pages as $[p\{l\}]$ where $p$ is the {\it physical} page number and $l$ is the {\it logical} page number. The first example will print from {\it physical} page 6 to the end of the document. The second example from page 6 to page 12, and the third example from page 6 to page 12 in steps of 2, {\it ie} pages 6, 8, 10, and 12. \beginttverbatim $dvialw psalm23 -b -o6 $dvialw psalm23 -b -o6:12 $dvialw psalm23 -b -o6:12:2 \endttverbatim \shead{finalversion}{The ``Final'' Version} \intex\ has number of features that are quite useful while putting together a document but which appear in the ``draft'' version but not in the ``final'' version. The default for \intex\ is |\draftversion|. This puts all the tags in the margin and puts ``Draft Version: {\it date}''\footnote{\dagger}{version pr\'eliminaire: {\it date} en fran\c cais} at the bottom of the page. To create the final version the command |\finalversion| should be put at the very beginning of your document. \shead{stcomforms}{Command Forms} \nosheadbreak \dssshead{Creation and Termination Commands} \beginblockmode \pla\@|\bye| \nbr Cleanly terminates a file. Actual meaning is ``|\par \vfill \supereject \end|''. However, it will also {\bf terminate} \tex\ processing if found in a {\it subdocument.} See Chapter~\ref{subdoc} for details. \mbr \ext\@|\done| \nbr This is the only way to terminate a document or subdocument in \intex\ without creating problems. Does everything |\bye| does along with checking whether certain groups are properly ended. \mbr \ext\@|\draftversion| \nbr This is the \intex\ default form. It prints margin notes when tags and autonumbering are used and puts a draft version note in the bottom margin. It is turned off using |\finalversion|. \mbr \pri\@|\end| \nbr Terminates a \tex\ job, even if it is in a subdocument. See Chapter~\ref{subdoc}. \mbr \ext\@|\englishversion \ehyph| \nbr This is the default for \intex. All the messages are in English, along with the various headings such as Chapter, and Appendix. Hyphenation is done by English rules, as is sentence and word spacing. \@|\ehyph| just invokes English hyphenation rules and does not affect messages. The other version that exists is |\versionfrancaise| \mbr \ext\@|\finalversion| \nbr This removes the marginal notes and the ``Draft Version'' note in the bottom margin. It should be used for the ``final'' copy. \mbr \ext\@|\hyphenation{}| \nbr This command is used to correct hyphenation of a specific word when \tex\ does it incorrectly. It is generally needed only for English. Without \mtex, the word is entered into the hyphenation exception table. With \mtex, it is entered into the hyphenation table corresponding to the language that is active at the time the command is executed. For example, if English (|\language=0|) is active, then |\hyphenation{man-u-script}| will enter the word ``manuscript'' into the hyphenation exception table with possible hyphens at those places where there is a ``~-~''. \mbr \ext\@|\language [=] | \nbr Normally this command will not need to be used. \intex\ has |\language=0| for English and |\language=1| for French. Additional languages may be added. If \intex\ is used in conjunction \mtex, then |\language| is an integer parameter; otherwise, it is a |\count|. For details on \mtex, see ``A Multilingual \mtex''. \mbr \ext|\marginnotestrue \marginnotesfalse| \nbr If \@|\marginnotestrue|, then the margin notes will be produced. They will not be produced when \@|\marginnotesfalse|. These can be used to override the defaults in |\draftversion| and |\finalversion|. \mbr \ext\@|\versionfrancaise \fhyph| \nbr This will produce French titles, messages, and spacing. When used with Multi-lingual \mtex, it also produces French hyphenation. \@|\fhyph| just invokes French hyphenation rules and does not affect messages. It should be placed at the beginning of the file. \endblockmode \dssshead{\tex print Commands} These commands are dependent upon the actual print driver that is being used. For DVIALW the following command line switches are used: \beginblockmode \@|DVIALW Command line options| \nbr \endblockmode \bl \li -b : Print the file in normal order. The default is to print the file beginning with the last page. \li -c\# : Select the number of copies to print ... each page is printed \# times. eg -c42 will print 42 copies of each page. \li -h : Select landscape printing. \li -i : Select Legal printing. \li -o : Select output page range ... all numbers are the "physical" page numbers, not the logical pages. DVIALW reports page output in the format of [p{l}] where where p is the "physical' page number and l is the "logical' page number. -o\# specifies start page -o\#:\# specifies start page and end page -o\#:\#:\# specifies start page, end page and step \li -r : Select manual feed. The laserwriter will wait for the insertion of manual pages. \li -x\#{\tt <}dim{\tt >} : Set left margin. -x0in sets the left margin to 0in. \li -y\#{\tt <}dim{\tt >} : Set top margin. -y0in sets the top margin to 0in. \el \ejectpage \marginnotesfalse \done