summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/midnight/styledef.doc
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2006-01-09 00:56:57 +0000
committerKarl Berry <karl@freefriends.org>2006-01-09 00:56:57 +0000
commitf07bb53970ee2ecc53f81a206a3d3a67ef665e4a (patch)
tree6f57a1d62971db79e5ff023bdfd83b22cb971dc9 /Master/texmf-dist/doc/generic/midnight/styledef.doc
parent007f67a693e4d031fd3d792df8e4d5f43e2cb2e7 (diff)
doc 6
git-svn-id: svn://tug.org/texlive/trunk@85 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/generic/midnight/styledef.doc')
-rw-r--r--Master/texmf-dist/doc/generic/midnight/styledef.doc309
1 files changed, 309 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/midnight/styledef.doc b/Master/texmf-dist/doc/generic/midnight/styledef.doc
new file mode 100644
index 00000000000..c2991cbc598
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/midnight/styledef.doc
@@ -0,0 +1,309 @@
+% 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