% styledef.doc --- version 1.0 (16 April 1991) % This is the documentation for styledef.tex. % To read this file, process it with (plain) TeX: tex styledef.doc % (To do that, you need manmac.tex, which has % the macros for typesetting the TeXbook, as explained in appendix E. % It comes free with the standard distribution of TeX.) % % NOTE: Processing this file with TeX will create empty files % index.tex and answers.tex in your directory. And if you % have a file pages.tex in your directory, TeX will probably % get very confused. % The manmac format will try to load a font called cmman; if % TeX complains that it cannot find that font you can savely % ignore that, since the font is not actually used. % % This file: copyright (c) 1991 Marcel van der Goot. % You may redistribute this file and printed versions of it. % % original: csvax.cs.caltech.edu [131.215.131.131] in pub/tex % (use anonymous ftp). Also in various archives. % % Marcel van der Goot % marcel@cs.caltech.edu % Caltech 256--80 % Pasadena, CA 91125 % (818) 356--4603 % ------ definitions for manual pages: % The documentation is typeset using Knuth's ``manmac'' macros, with a % few additional things defined here. You are free to use or adapt these % extra definitions. \input manmac % the macros used for typesetting The TeXbook (appendix E) \catcode`^=7 % manmac makes ^ active for creating an index % we don't make an index, and we need ^ to be non-active {\catcode`\^^M=12 \endlinechar=-1 % 12 = other \long\gdef\manpagehead#1^^M#2^^M#3^^M^^M% tex-file, description, version {\egroup % matches \bgroup in \manpage \par\vfill\eject \edef\rhead{\manualname: #1\unskip}% \setbox1=\hbox{\titlefont #1\quad}% \setbox3=\vtop{\advance\hsize by-\wd1 \parindent=0pt \raggedright #2\par #3\par \cnotice }% \line{\box1\box3}% \bigskip\bigskip\bigskip\noindent }% } % restore \catcode`\^^M \outer\def\manpage {\bgroup\catcode`\^^M=12 \manpagehead } \hsize=6.5in\vsize=8.9in % default plain TeX values \pagewidth=\hsize \pageheight=\vsize \def\cnotice{Copyright \copyright\ 1991 Marcel R. van der Goot} \def\manualname{Midnight Macros} % LaTeX logo, from latex.tex (except for the capital `A': manmac % doesn't have a real smallcaps font) \def\LaTeX{{\rm L\kern-.36em\raise.3ex\hbox{\sc A}\kern-.15em T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}} \tenpoint % (end of extra definitions) % -------------------- styledef.doc: \pageno=14 % follows labels.doc \manpage styledef.tex styledef.tex: Macros to selectively input parts of a file. Version: 1.0 (16 April 1991) (doc: 19 Sep 1991) Consider the following situation: You write a set of \TeX\ macros to typeset letters. These macros must set fonts, margins, offsets, etc. However, you want to use different styles for different types of letters. For instance, a short letter may need extra white space at the top to get a full page, whereas this is not needed for a letter several pages long. And a business letter has a standard header, with subject and references, whereas a small note to a friend only has a date. Probably the macros for the different styles have a lot in common, a reason to put them all in one file. But the different styles may have some conflicting definitions, of which you only want to include one. Styledef.tex\footnote*{You also need Midnight/dolines.tex and Midnight/loop.tex, which will be |\input| automatically.} provides some macros to |\input| from a file only parts belonging to a particular ``style.'' (Partial inclusion can also be useful for other things than styles; see the end of this manual section for an example.) Before we explain the macros from styledef.tex, let us look at two other solutions. First, say the only difference between styles ``wide'' and ``narrow'' is the width of the text. Then we can write macros |\widestyle| and |\narrowstyle| that set the appropriate width. As long as the differences between styles are small and easily parametrized, this method works fine. If there are many differences, however, the macros for setting the style soon get very large. Furthermore, it is hard too share parts of styles. A second method is the one used by \LaTeX. One makes one file ``letter.sty'' with all the common definitions for letters; an additional file is made for each style. \LaTeX's |\documentstyle| macro is then used to include the proper files. E.g., one could write \begintt \documentstyle[business,narrow]{letter} \endtt to write a letter with the ``business'' and ``narrow'' style options. This method allows sharing of common definitions, and also allows the combination of different style options. The disadvantage is that it soon leads to a very large number of files, many of them with only a few definitions. With the macros in styledef.tex, you would use only one or two files. Typical would be to have one file, ``letter.tex,'' with all the common definitions for letters, and one file, ``letter.style,'' with all the different styles. Only some parts of the latter file are included, through the macros below. Alternatively, everything can be put in a single file. (Using two files has the advantage that ``letter.tex'' can be shared by several users, who each have there own personalized ``letter.style.'') Styledef.tex is of course especially useful with plain \TeX, since that does not have an equivalent mechanism. However, the macros can also be used with \LaTeX; later on we describe how to make the |\documentstyle| command interact with the styledef macros. First we describe how to |\input| only parts of a file. In order to use any of these macros, you first have to |\input styledef|. Then you have to allocate one or more ``style registers'': a style register called ``|\myst|'' is allocated with the command \begintt \newstyle\myst \endtt You can give a new value to a style register through the |\setstyle| command. It takes a style register and a list of styles as arguments. E.g., \begintt \setstyle\myst{business, narrow} \endtt For this command, as for all others, a style list is a list of style names separated by spaces and/or commas; the whole list must be enclosed in braces. The style names themselves can be any names that are meaningful to the macro package you are using. The |\addstyle| command is used in the same way as |\setstyle|, but it adds one or more styles to the style register without removing the old contents. You can use |\the\myst| to get the contents of the style register, and style registers can be assigned to each other using `|=|'. The last operation involving style registers is |\readstyle|. It takes a style register and a file name: The command \begintt \readstyle\myst{letter.style} \endtt will |\input| file letter.style, but includes only those parts of it that belong to one of the styles in register |\myst|. That is all that is needed to selectively |\input| a file. The other macros from styledef.tex and the remainder of this manual section describe how to indicate in a file like letter.style which parts belong to which styles. If you don't intend to create such files yourself, there is no need to read on. There are only three commands that govern which parts of a file belong to a particular style: |\styledef|, |\negstyledef|, and |\endstyle|. The first two are followed by a brace-enclosed list of styles (but not by a style register). When a file is read with |\readstyle|, the file is just |\input| by \TeX. However, when in that file a command \begintt \styledef{business, long} \endtt is encountered, \TeX\ checks whether the style register that is used with |\readstyle| contains style ``business'' or style ``long.'' If at least one of them is contained in the register, \TeX\ continues to input the file. But if none of the styles match, \TeX\ skips lines of the file until an |\endstyle| command is encountered. |\negstyledef| has exactly the opposite effect: if any style matches, the file is skipped till the next |\endstyle| command; only if no style matches is this part of the file included. The |\endstyle| command must occur on a line by itself, with nothing, not even a comment, following it. The |\endstyle| command stops \TeX\ from skipping text; if it is encountered when \TeX\ is not skipping text, it is equivalent to |\relax|. Text that is not enclosed by a |\styledef| \dots |\endstyle| (or |\negstyledef| equivalent) is always included. |\styledef| commands can be used within each other's range, but they do not actually nest: when part of the text is skipped, skipping always stops at the first |\endstyle|; any intervening |\styledef| commands are also skipped. E.g., \begintt \styledef{business} \negstyledef{narrow} ... \endstyle \endtt The text corresponding to `|...|' (which does not include any |\endstyle|) is only included if the style register contains style ``business'' and does not contain ``narrow.'' If style ``business'' is not contained in the register, the |\negstyledef| command as well as the `|...|' are skipped. As a catch-all you may want to put an |\endstyle| at the end of the included file: if you missed an |\endstyle| somewhere, this catch-all will at least restrict the effects to this file. \danger The |\readstyle| command uses an internal style register to store which styles must be included. Therefore, if a file which is being read with |\readstyle|, uses |\readstyle| to read yet another file, the original list of styles will be lost. Although this situation seldomly occurs, there is a command |\savereadstyle| which takes a style register as argument and saves the internal style list in this register. Of course, if the second file should be read with exactly the same style list, you should just use |\input| instead of |\readstyle|. To restore the original style list, you use |\setreadstyle|, which also takes a style register as argument. |\setreadstyle| can also be used instead of |\readstyle|, if you want to select certain parts of the current file rather than |\input| a different file. \danger Style names can be built from any characters, except for spaces, commas, dots, and some characters with a special meaning to \TeX\ (e.g., braces, hash signs (|#|), and percentage signs). Also, characters in a style name must have the same catcode in the |\styledef| command as in the |\setstyle| command. When a |\styledef| or |\negstyledef| command is encountered, the following conditions must hold: The only escape character (catcode 0) is `|\|'; the only grouping characters (catcodes 1 and 2) are `|{|' and `|}|'; the only parameter character (catcode 6) is `|#|'; and the only comment character (catcode 14) is `|%|'. After the |\styledef| command these catcodes may be changed, as long as the conditions hold again when the next |\styledef| is encountered. These particular catcode assignments are so standard that this rule is unlikely to ever cause problems. Suppose you have written a file letter.tex, which is to be used by several people. You also have a file letter.style with some standard styles; people can copy and change this file to suit their own needs. To make life easier for those who only want to use your standard styles, you may not want to force them to learn about styledef.tex. Instead, you can define a macro |\style| which always reads a file with name letter.style. Its usage would be: \begintt \input letter \style business, long, narrow. ... \endtt so that users need not be concerned about style registers etc. Here is part of an appropriate letter.tex: \beginlines |\input styledef| \nobreak |\newstyle\letterstyle| \medskip |\def\style#1.% terminate the argument with a dot| \nobreak | {\setstyle\letterstyle{#1}| | \readstyle\letterstyle{letter.style}| \nobreak | }| \endlines \ddanger Something similar can be done with \LaTeX's |\documentstyle|, provided you know which styles can appear in letter.style. This is done as follows: first, rename letter.tex to letter.sty, so that \LaTeX\ can read it. Then add the following to the end of that file: \begintt \newstyle\lst \def\ds@business{\addstyle\lst{business}} \def\ds@narrow{\addstyle\lst{narrow}} ... % same for every style \@options \readstyle\lst{letter.style} \endtt You can then write |\documentstyle[narrow]{letter}|. \LaTeX\ takes this as a command to read letter.sty. The |\@options| command causes \LaTeX\ to execute, for every option `xyz,' the command |\ds@xyz|, if it exists. All options for which this command does not exist lead to the input of a file xyz.sty, so that standard \LaTeX\ options can still be used. Note that letter.sty is here the main style file (only there can |\@options| be used); be warned that it is not easy to write a main style file that satisfies all of \LaTeX's assumptions. Although we have suggested that these macros are suitable to handle different ``styles,'' selective inclusion can also be useful in contexts unrelated to styles. For instance, you may write a paper which has some details and speculations which are not relevant for every reader. You can write the paper like this: \beginlines | ... % relevant thoughts| \goodbreak |\styledef{details}| | ... % messy details| |\endstyle| \goodbreak |\negstyledef{details}| |Details are left as an exercise for the reader.| |\endstyle| \goodbreak | ... % important stuff| |\styledef{speculations}| | ... % wild fantasies| |\endstyle| \endlines If you want to print a version with speculations but without details, you can start the file with \begintt \newstyle\print \setstyle\print{speculations} \setreadstyle\print ... \endtt \bye