%-*-tex-*- \ifundefined{writestatus} \input status \relax \fi % \chcode{defs} \def\cqu{\cquote{If names are not correct, language will not be in accordance with the truth of things.}{Confucius}} \chapterhead{defs}{SIMPLE\cr DEFINITIONS\cr or MACROS} \tex\ makes it easy to invent definitions to make your typing job easier. This chapter describes the simplest form of definitions. More complex definitions and some of the subtleties are found in the \texbook. This chapter also introduces the idea that definitions can be modified by such primitive commands as |\outer|, |\long|, and |\global|. Simple definitions consist of those that have zero or more arguments and that do not use advanced commands such as |\futurelet|, |\aftergroup|, |\edef|, |\catcode|, |\bgroup|, |\egroup|, |\afterassignment|. These commands and their use may be found in the \texbook\ and the definition package that actually is used to develop {\it plain} or \intex. If you wish to write complex definitions, please see the warning at the end of this chapter. \shead{defcomlist}{Command List} \beginthreecolumn \pri|\def| \pla|\gdef| \pri|\global| \pri|\let| \pri|\long| \pri|\outer| \endthreecolumn \shead{defcomforms}{Command Forms} \beginblockmode \pri\@|\def\ {}| \nbr This is the basic command for creating new definitions or, as they are sometimes called, {\it macros}. The || is the name given to the definition and {\bf must} consist of letters, upper or lower case only. The || is the form for which \tex\ is looking after it sees the |\| in the text. Parameters in the || are indicated by |#| where || is from 1 to 9, in {\bf order}. \tex\ then puts the parameter values that it found into the || and then puts that text in the place of |\| and all of the parameters that it has eaten while filling in the ||. Some examples follow: \dssshead{Simple Replacements --- No Parameters} These are the simplest form of definitions. In this case there are no parameters and the || directly replaces the |\|\]\dots\]. The \]\dots\] is there to emphasize that all the blanks after the |\| are eaten by \tex. Suppose that the sequence $\alpha\beta\gamma$ kept occurring in the text. Then |\abg\|\] defined by |\def\abg{$\alpha\beta\gamma$}| \def\abg{$\alpha\beta\gamma$} will produce \abg\ in its place. In this example the || is |$\alpha\beta\gamma$|. A second example is the problem of putting {\it italic correction\/} in the text, keeping the italic inside the group defined by the |{...}|. The || then should be |{\it italic correction\/}| including the braces. Thus the correct definition, if |\itc| is to be the ||, is |\def\itc{{\it italic correction\/}}|. \dssshead{Simple Replacements --- Simple Parameter List} These definitions have the || of |#1|, |#1#2|, \dots, |#1#2...#9|. An example is |\def\up#1{$^{#1}$}|. When |\up| is used, the next {\it token}, either a character, command, or entire group inside a |{...}| is absorbed as |#1| and put into the position of |#1| in the replacement text. Thus |\up{**}| becomes |$^{**}$| which is then put in the text in place of the entire |\up{**}|. Note that |**| and not |{**}| is the parameter for |\up|. The |{...}| were used to delimit |**| so that \tex\ knew that both of them together should be |#1|. ``Thus|\up{**}|'' gives ``Thus\up{**}''. Note that a definition made inside a group only lasts as long as the group lasts. At that point the definition becomes what it was previous to the group. \mbr \pla\@|\gdef\ {}| \nbr This is identical to |\global\def| and can be used in exactly the same way as |\def|. The major difference is that a |\| defined with a |\gdef| does {\bf not} disappear at the end of the group in which it is defined. \mbr \pri\@|\global| \nbr The command |\global| will cause either the definition, assignment, or definition equivalence (|\let|) to be global, {\it ie} not disappear at the end of the group. This should be used with care and sparingly. \mbr \pri\@|\let\ [=] \| This command makes the command |\| be equivalent to, both in || and ||, as |\| at the time that the |\let| is called. This command is very useful for such things as |\let\sheadfont = \twelvess|. It should be used with care or a circle of definitions may be produced. \mbr \pri\@|\long| \nbr A |\def| may be preceded by a |\long| to give a |\long\def|. When this is done the parameters |#1| \dots\ may contain either |\par| or, equivalently, blank lines. Without the |\long|, a |\par| in a |#1| will cause an error. This is a safety feature to allow \tex\ to isolate errors before the origin is completely lost. |\long| should be used with extreme care. \mbr \pri\@|\outer| \nbr A |\def| may be preceded by |\outer| to give an |\outer\def|. A definition so preceded may {\it not} be used in any other definition. Again this is a safety feature to catch errors before it is too late. For example, all of the section head definitions in \intex, |\shead| and its relatives, are declared |\outer|. It is possible to have a |\outer\long\global\def|. \endblockmode \shead{defwarning}{WARNING --- Clever Definitions} It is possible tell \tex\ very complex things. The danger and difficulty for debugging increases dramatically as you start to exercise fine control over how \tex\ processes the text. The simplest extension to the forms above is to use the fact that the || can include tokens other than |#|. This additional freedom allows for the input of parameters without requiring that they be placed in |{...}|. The second level of extension is to use the various |\if... \else ... \fi| forms to control the actual text that will be placed in the text and even the placing of definitions inside definitions. The next level of complexity arises when the macro builder attempts to control when \tex\ expands the various definitions and macros that make up the || and the ||. For instance, this must be done when writing out both the page number and the section number while accumulating information for making a table of contents. This requires extreme care. The final level of complexity occurs when the macro writer attempts to control how, and when \tex\ tokenizes its input. Doing this correctly requires exquisite care. For instance, conditionally modifying the catcodes of input on the fly will prevent that input from being passed as a parameter to a macro. \tex\ tokenizes once and forever. Although making a character active for an entire document is relatively simple, flipping it back and forth is error prone. \ejectpage \done