diff options
Diffstat (limited to 'Master/texmf-dist/doc/texsis/base/TXSenvmt.doc')
-rw-r--r-- | Master/texmf-dist/doc/texsis/base/TXSenvmt.doc | 610 |
1 files changed, 610 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/texsis/base/TXSenvmt.doc b/Master/texmf-dist/doc/texsis/base/TXSenvmt.doc new file mode 100644 index 00000000000..34de0ac5927 --- /dev/null +++ b/Master/texmf-dist/doc/texsis/base/TXSenvmt.doc @@ -0,0 +1,610 @@ +%% file: TXSenvmt.doc - Environments - TeXsis version 2.18 +%% @(#) $Id: TXSenvmt.doc,v 18.2 2000/05/17 00:19:46 myers Exp $ +%======================================================================* +% (C) copyright 1988, 1991, 1994 by Eric Myers and Frank E. Paige. +% This file is a part of TeXsis. Distribution and/or modifications +% are allowed under the terms of the LaTeX Project Public License (LPPL). +% See the file COPYING or ftp://ftp.texsis.org/texsis/LPPL +%======================================================================* +\ifx\undefined\bs \texsis\input TXSdocM.doc\draft\input Manual.aux\fi + + +\section{Environments \label{sect.envmt}} + + \TeX\ ordinarily provides a layout appropriate for straight text +and equations. The \TeXsis\ macros described below create environments +which bypass the normal layout to format text in special ways, to create +different types of lists, to display theorems and proofs, to display +computer code, and even to print \TeX\ examples. With the exception of +some of the specialized \TeX\ example macros, the syntax for all of +these is generally of the form ``|\thing|...'' to begin the environment +and ``|\endthing|'' to end it. + +%==================================================* +\subsection{Flush or Centered Text} + + There are three environments in \TeXsis\ which center lines, set +them flush left, or set them flush right, respectively: +\description{~endflushright~\qquad}\clump + +\itm{\CS{center}} +Centers all lines which follow, up to |\endcenter|. + +\itm{\CS{flushleft}} +The lines which follow, up to |\endflushleft|, +are made to line up flush to the left margin. + +\itm{\CS{flushright}} +The lines which follow, up to |\endflushright|, +are made to line up flush to the right margin. +\enddescription +In all of these environments line endings +in the input file {\sl are} obeyed, as with \cs{obeylines}. +\index{lines!centering}\index{lines!flush left}\index{lines!flush right}% +For example, +\TeXexample +\center +A Centered Line +and Another +\endcenter +|endTeXexample +produces + +\center\singlespaced\parskip=0pt +A Centered Line +and Another +\endcenter +\noindent +There is also a \CS{raggedcenter} environment which does not respect line +breaks but instead produces centered lines each of which is made as long +as possible: +\description{~raggedcenter~\qquad}\clump +\itm{\CS{raggedcenter}} +Center lines without respecting line endings. +Terminate with |\endraggedcenter|. +\enddescription +\goodbreak\noindent +For example +\def\|{\ifmmode\Vert\else \char`\|\fi} +\TeXexample +\raggedcenter +In the ragged centering environment each line +is made as long as possible, and +the successive lines are centered. +\endraggedcenter +|endTeXexample +produces +\raggedcenter\baselineskip=\normalbaselineskip +In the ragged centering environment each line +is made as long as possible, and +the successive lines are centered. +\endraggedcenter +\noindent +Note that \cs{raggedcenter} does not hyphenate words. + + +%==================================================* +\subsection{Simple Examples and Quoted Text} + + The \CS{example} environment can be used to display an example of +something in a way that sets it off from the main text. The indentation +of an example is the same as in the list environments (see +\Sect{env-indent}). The text in an example will be single +spaced, even if the rest of the document is double spaced. End this +environment with \cs{endexample}. An example of the use of \CS{example} +is +\TeXexample +|tentt\example +Physics is not a finished logical system. Rather, at any +moment it spans a great confusion of ideas, some that +survive like folk epics from the heroic periods of the past, +and other that arise like utopian novels from our dim +premonitions of a future grand synthesis. +\endexample +|endTeXexample +which produces\reference{Weinberg, 1972} +S.~Weinberg, +\booktitle{Gravitation and Cosmology: Principles and Applications of the +General Theory of Relativity} +(Wiley, New York, 1972) pg.~3 +\endreference\relax\index{Weinberg, Steven} +\begingroup\tenpoint +\EnvRightskip=\parindent % need this to show off defaults! +\blockquote +Physics is not a finished logical system. Rather, at any +moment it spans a great confusion of ideas, some that +survive like folk epics from the heroic periods of the past, +and other that arise like utopian novels from our dim +premonitions of a future grand synthesis. +\endexample +\endgroup +Another example of \CS{example} is given in the next subsection as an +example of the |\theorem| environment. + +Since one of the uses of \CS{example} is to display block quotes, as +we've just done above, a synonym for \CS{example} is \CS{blockquote}, +which should be ended with \CS{endblockquote}. + + +%==================================================* +\subsection{Theorems and Proofs} + + Theorems,\index{theorems} \idx{lemmas}, and \idx{corollaries} are +typeset in a quasi-SIAM format, with the number in boldface and the text +in slanted type. +They are automatically numbered, including the chapter and +section numbers if \cs{showchaptIDtrue} and \cs{showsectIDtrue} are +being used. The syntax for a theorem is +\example +\CS{theorem}\arg{label} \n +\meta{text} \n +\cs{endtheorem} \n +\CS{proof} \n +\meta{text} \n +\cs{endproof} +\endexample +\noindent +and similarly for \CS{lemma}, \CS{corollary} and \CS{definition}. +Definitions are printed in Roman type, not slanted. The +\cs{endproof} macro inserts a black box to mark the end of the +proof. Subsequent references to theorems, lemmas, corollaries +and definitions can be made in the text automatically using +\CS{Theorem}\arg{label}, \CS{Lemma}\arg{label}, +\CS{Corollary}\arg{label}, and \CS{Definition}\arg{label}, +which give the appropriate name and number. An example of a +Theorem is: +\TeXexample +|tentt\example +\theorem{Cauchy} +If $f(z)$ is a function of $z$ which is analytic on and inside of +a contour $C$, then +$$ +\int_C f(z)\,dz = 0 +$$ +\endtheorem +\proof +Left as an exercise to the reader. +\endproof +\endexample +|endTeXexample +which produces +\begingroup +\EnvRightskip=\parindent % need this to show off defaults! +\tenpoint +\example +\theorem{Cauchy} +If $f(z)$ is a function of $z$ which is analytic on and inside of +a contour $C$, then +$$ +\int_C f(z)\,dz = 0 +$$ +\endtheorem +\proof +Left as an exercise to the reader. +\endproof +\endexample +\endgroup +\noindent +Note the use of \cs{example} to indent the theorem and proof and print +them single spaced. Had the \cs{example} been omitted the theorem and +proof would have had the same margins and spacing as the rest of the text. +This theorem would be referred to in the text with |\Theorem{Cauchy}|, +which gives ``\Theorem{Cauchy}.'' This should be sufficient in most +cases, but if necessary one can refer to theorem or lemma numbers with +the primitive \cs{use}|{|\meta{type}.\meta{label}|}|, where \meta{type} is +either |Thm|, |Lem|, respectively. See Section~\use{sect.labels} for +more on the use of \cs{use}. + + +%==================================================* +\subsection{Listing Computer Code} + + The \CS{Listing} environment can be used to display computer code +or fragments of computer code. \index{listing computer code}% +The text is printed in |\tt| type with line endings respected and every +space counted. You can still use \TeX\ control sequences in this +environment, but many of the special characters like |%|, |&|, and |#| +are simply printable characters, since they are used in languages like +C. (|$|, |_| and |^| also lose any special meaning in this +environment.) Since the curly brackets used by \TeX\ are also used in C +(and other languages) they are also simply characters in the |\Listing| +environment. To perform grouping you should use \cs{bgroup} and +\cs{egroup}. The backslash is also used in C as an escape character, so +there has to be some way to print it --- you simply use |\\|; thus \cs{n} +should be typed as |\\n|. You end the listing environment with +\cs{endListing}. As an example here is a very famous little +program,\reference{K&R} +Brian W.~Kernighan and Dennis M.~Ritchie, +\booktitle{The C Programming Language}, +(Prentice Hall, Englewood Clifs, NJ, 1978) +\endreference +\index{hello@``hello, world''}% +% +\Listing +#include <stdio.h> +main() +{ + printf("hello, world\\n"); +} +\endListing +\noindent +which was created by simply typing, +\TeXexample +|tentt\Listing +#include <stdio.h> +main() +{ + printf("hello, world\\n"); +} +\endListing +|endTeXexample + + +The indentation and spacing of the of the \CS{Listing} environment are +controlled by the same parameters that control the indentation of the +list environments, as described in Sect.~\use{sect.env-indent}. In +addition, at the begining of the \CS{Listing} environment the macro +\CS{everyListing} is executed, if it exists. You can define +\CS{everyListing} to change the typestyle, type size, or spacing in the +\CS{Listing} environment. + +An alternative way to list computer code is +\CS{ListCodeFile}\arg{filename}, which will list the contents of a +source code file exactly as it appears in the file (with no need to make +|\n| into |\\n| and such). The call to this macro should {\sl not\/} be +enclosed in a |\Listing| environment. If the example program above were +contained in the source file |hello.c| it could be listed simply by +typing +\TeXexample +\ListCodeFile{hello.c} +|endTeXexample +\noindent +Long lines can bump up against the right margin. +Some extra glue has been added to help allow for this, but another way +to make such lines fit is to make the type size smaller before you +invoke +\CS{ListCodeFile} (you can do this using \CS{everyListing}). +% MAYBE THE FOLLOWING GOES AWAY SOMEDAY SOON: +Note also that tab characters in the code file may not be treated +exactly correctly. In the present implementation of \TeXsis\ they will +simply be replaced with eight spaces. We hope to be able to improve how +this macro deals with tabs in in a future release of \TeXsis, but it is +difficult to do it exactly right in all cases, so for now it may be best +to change tabs to spaces in the source file if proper tab stops are +needed. Most good editors (like emacs) already do this for you, so this +should not pose much of a problem. + + +%==================================================* +\subsection{List Environments} + + When you want to make a list of things there are several ways +to do it. The items in the list can be marked by a simple marker +(like a bullet: $\bullet$), by a number or numbers and letters (as in +an outline), or by some sort of descriptive text in the margin. +In Plain \TeX\ you +would make all of these kinds of lists using the |\item| macro. The +``list environments'' described below are generalizations of |\item| for +making these various kinds of lists:\index{lists!different kinds} +\description{~description~\qquad}\clump +\itm{\CS{itemize}} +List of paragraphs marked by a bullet ($\bullet$) or other symbol. +\index{lists!itemized}% + +\itm{\CS{enumerate}} +List of paragraphs labeled by numbers or by combinations of +numbers and letters, as for an outline. +\index{lists!enumerated}% + +\itm{\CS{description}} +List of items and paragraphs describing them.\index{lists!text labels} +\enddescription +In each list environment \cs{itm} is used to introduce each individual +item. The environments are terminated with \cs{enditemize}, +\cs{endenumerate} and \cs{enddescription}, respectively. The three +different kinds of environments can be nested to produce a list with +several levels. The indentation of and spacing above and below the list +environments can be easily controlled. This is described in +Section~\use{sect.env-indent}. + + +% ---------- +\subsubsection{Itemized lists}\relax +\CS{itemize} produces paragraphs marked by \idx{bullets}~($\bullet$) +or some other appropriate symbol; {} % a little extra space in this line +this is usually used for a short list with only a single level of +nesting where the order \hbox{either} does not matter or is already +contained in the items of the list. +\index{lists!itemized}\index{itemizing}% +%% WE NEED A BETTER SHORT EXAMPLE THAN THIS -- SOMETHING SIMPLER? +For example, |\itemize| was used to produce the list of +sections of this manual which begins +on \linkto{page.itemize}{page~\use{page.itemize}}. The first few items in +this list were produced by saying: +\TeXexample +|tentt\itemize +\itm Sect.~\use{sect.intro}: +An introduction to \TeXsis\ and the philosophy behind the macros, and +instructions on how to begin using \TeXsis. +\itm Sect.~\use{sect.fonts}: +Selecting sizes and fonts of type, choosing single, +double, or triple spacing, and automatically handling +quotation marks. +\itm Sect.~\use{sect.eqns}: +Automatic numbering of equations, automatic sizing of +parentheses and brackets, and special symbols for +physics equations.... +|endTeXexample +\goodbreak\noindent +A paragraph begun by |\itm| is not indented beyond the new left margin, +but paragraphs that follow {\sl are} indented unless |\noindent| is +specified (or if they also begin with |\itm|). + +You can change the symbol used to mark each item in the list to be +anything you want by creating your own definition of \CS{itemmark}. +For example, if you want the symbol to be a \cs{square} you +would define \CS{itemmark} to be +\TeXexample +\def\itemmark{$\square$} +|endTeXexample +\noindent +before invoking \CS{itemize}, or at least before the first |\itm|. +An example is the following important checklist:\reference{Banzai, 1984} +\booktitle{The Adventures of Buckaroo Banzai across the Eighth +Dimension}, (Twentieth Century Fox, 1984) +\endreference +\itemize +\def\itemmark{$\square$} +\itm Event timer started (display: SINED) +\itm Antenna Aligned (display: SEELED) +\itm Oscillation overthruster armed (display: DELIVERED) +\enditemize +This was produced by saying: +\TeXexample +\itemize +\def\itemmark{$\square$} +\itm Event timer started (display: SINED) +\itm Antenna Aligned (display: SEELED) +\itm Oscillation overthruster armed (display: DELIVERED) +\enditemize +|endTeXexample +\noindent +\CS{itemize} starts a new group, which is ended by the \cs{enditemize}, +so in this example \CS{itemmark} reverts back to its +previous definition when the list is finished. +You can get a ``check-mark'' symbol instead of a square by +replacing \cs{square} with \cs{surd}, or you can use any other symbol +that suits you. Note though that in this example +the \cs{square} is enclosed in math +quotes --- you will have to remember this for any symbol which is defined +in math mode. + +% ---------- +\subsubsection{Enumerated lists} + + \cs{enumerate} produces numbered paragraphs, either with a single level +or nested several levels deep, like so: +\index{lists!enumerated}% +\TeXexample +|tentt\tenpoint\parskip=0pt % this just makes our examples smaller +\enumerate +\itm Paragraph 1. +\enumerate +\itm sub-paragraph 1a. +\enumerate +\itm sub-sub-paragraph 1a(i). +\itm sub-sub-paragraph 1a(ii). +\endenumerate +\itm sub-paragraph 1b. +\itm and so on... +\endenumerate +\itm Paragraph 2. +\itm and so on... +\endenumerate +|endTeXexample +\noindent +This produces the enumerated list: +\def\ListExample{% Define once, use several times... + \tenpoint\parskip=0pt\medskip + \itm Paragraph 1. + \enumerate + \itm sub-paragraph 1a. + \enumerate + \itm sub-sub-paragraph 1a(i). + \itm sub-sub-paragraph 1a(ii). + \endenumerate + \itm sub-paragraph 1b. + \itm and so on... + \endenumerate + \itm Paragraph 2. + \itm and so on...} +\enumerate +\ListExample +\endenumerate +The default form for the paragraph numbering is called \CS{enumPoints}, +which produces numbers of the form $ii.jj.kk$. You can also have the +list printed in a standard outline format with a mixture of Roman +numerals, letters, and Arabic numerals by saying \CS{enumOutline}. +\index{lists!enumerated!styles}% +Doing so to the example above produces: +\enumOutline\enumerate +\ListExample +\endenumerate +Unless enclosed within a group, +the \CS{enumPoints} or \CS{enumOutline} style selected remains in effect +until it is changed. The punctuation following the item number is +\CS{enummark}, which by default is a period (\hbox{.}) but which can be +redefined by the user [for example, you can change it to |\rparen| to +obtain numbering of the form ``\hbox{2\rparen}'']. \CS{enummark} can +also be used to change the spacing between the numbers and the text that +follows. + +A third enumeration style, called \CS{enumNumOutline}, is also available. +Top level items are labeled by arabic numbers, the level below by +lower case roman letters, and the level below that by lower case +roman numerals. With \CS{enumNumOutline} the example above becomes: +\enumNumOutline\enumerate +\ListExample +\endenumerate + +If you prefer a different style of enumeration you can create your +own |\enumWhatever| to use in place of \CS{enumPoint} or +\CS{enumNumOutline}. To do so, copy the definition of \CS{enumPoints} or +one of its brothers, along with the comments that go with them, from the +file |TXSenvmt.tex| into a file called |TXSmods.tex| (see +Appendix~\use{install}) and then make the appropriate changes as +described in those comments. +\index{lists!enumerated!styles}% + +% ---------- +\subsubsection{Lists Labeled by Text}\relax +\CS{description} is used to create a list of words or other +items labeled by some text. +The syntax is\index{lists!text labels} +\example\tenrm +\CS{description}\arg{sample text} \n +\cs{itm}\arg{label 1} |Paragraph 1...| \n +\cs{itm}\arg{label 2} |Paragraph 2...| \n +\cs{itm}|{...}| \n +|\enddescription| +\endexample +The argument \meta{sample text} is not printed, but its length is used +to determine the indentation for the labels on the items, so it +should be the longest item, followed by some extra space. For example, the +descriptions of the flush and centered environments at the beginning of +this section of the manual were typeset with +\TeXexample +|tentt\description{~flushright~\qquad} +\itm{\CS{center}} +Center each line. +\itm{\CS{flushleft}} +Set each line flush left. +\itm{\CS{flushright}} +Set each line flush right. +\enddescription +|endTeXexample +since |\flushright| is the longest of the three items. (|\CS| is a +special macro defined for this manual for printing control sequence +names.) Each item in the list is separated by a \cs{parskip}, +just as in itemized or enumerated lists. + +If the label text for an item comes out wider than the space +allowed, the text will usually be broken into several lines +so that it will fit in the indented margin (if this is possible!). +Saying \CS{singlelinetrue} will instead put the label text on a +line by itself, above the item. \CS{singlelinefalse} is the default, +but this manual has been printed with \CS{singlelinetrue}. + + +%==================================================* +\subsubsection{Spacing of List Environments \label{sect.env-indent}} + +Each of the list environments described above is surrounded by the +following skips: +\index{lists!indentation}% +\TeXexample +\EnvTopskip = \medskipamount % space above the list +\EnvBottomskip = \medskipamount % space below the list +\EnvLeftskip = 2\parindent % left indent for the list +\EnvRightskip = \parindent % right margin moves in too +|endTeXexample +\noindent +You can change these as you please to any legal \TeX\ dimension. The +space between +items which are begun by \cs{itm} is taken from the \cs{parskip}. Since the +list environment begins a group you can change the |\parskip| inside +this group to control the spacing between |\itm|'s. For example, if you +wanted no extra space between the items in the list you could say +set the |\parskip| to zero, as in, +\TeXexample +\itemize +\parskip=0pt \def\itemmark{$\triangleright$} +\itm Event timer started (display: SINED) +\itm Antenna Aligned (display: SEELED) +\itm Oscillation overthruster armed (display: DELIVERED) +\enditemize +|endTeXexample +\noindent +which would produce: + +\itemize +\parskip=0pt \def\itemmark{$\triangleright$} +\itm Event timer started (display: SINED) +\itm Antenna Aligned (display: SEELED) +\itm Oscillation overthruster armed (display: DELIVERED) +\enditemize + + +%==================================================* +\subsection{\TeX\ example macros} + + Typing \TeX\ examples can't be done in either the \cs{example} +environment nor the |\Listing| environment, because the backslash must +be turned into a simple printing character. There are several ways \TeXsis\ +allows you to show examples of \TeX\ code. First, to display \TeX\ +instructions separately, use +\index{TeX@\TeX, typing examples}% +\description{~TeXexample~\qquad}\clump +% +\itm{\CS{TeXexample}} +Prints like an \cs{example}, but verbatim in \cs{tt} type, with +``{\offtt |}'' made the escape character. Note that you must therefore +say {\offtt |endTeXexample} to end the example, since "{\tt\bs}" is no +longer the escape character! +\enddescription +To display \TeX\ instructions in running text use +\description{~TeXexample~\qquad}\clump +% +\itm{\CS{TeXquoteon}} +Make ``{\offtt |}'' a "\TeX\ quote" so that everything between +{\offtt |}'s is printed verbatim in |\tt| type. +% +\itm{\CS{TeXquoteoff}} +Turns off "\TeX\ quotes." +% +\enddescription + +All of the displayed examples in this document have been typed using +\CS{TeXexample}, and many of the inline examples have been typed by +putting \CS{TeXquoteon} at the beginning of the document and then typing +{\offtt |\bs whatever\ttdots|}. For both \CS{TeXexample} and +\CS{TeXquoteon} the only special character is the escape character +``{\offtt |}''. In particular one must type +\example\obeylines\tt +\bs TeXexample +\meta{TeX stuff} +\char124endTeXexample +\endexample +with {\offtt |endTeXexample} instead of |\endTeXexample|. All other +characters are set in |\tt| type without any interpretation. The input +line breaks and spacing are respected, including any leading spaces on +the lines. \TeX\ commands can be used within a |\TeXexample| environment +by typing {\offtt |macro} in place of |\macro|, {\offtt |bgroup} and +{\offtt |egroup} in place of |{| and |}|, etc. In particular, a {\offtt +|} can be obtained by typing {\offtt |char124}. If you want to display +the results of a complicated macro inside the |\TeXexample| environment +you should probably define a different macro to display these results +and then invoke that macro inside the environment. For example, in this +manual we have sometimes inserted ``meta'' constructions showing where +to insert a particular piece of text by using a |\meta| macro which +encloses its argument in angle brackets (see the example immediately +above). But in a |\TeXexample| you cannot say ``{\tt \VT meta\lb TeX +stuff\rb},'' because the ``|{|'' and ``|}|'' are no longer grouping +characters. Instead you could define the temporary macro |\tmp| as +\TeXexample +\def\tmp{\meta{TeX stuff}} +|endTeXexample +\noindent +and then inside the |\TeXexample| environment simply type {\tt \VT tmp} +to insert the phrase ``\meta{TeX stuff}''. + +The indentation and +spacing of the |\TeXexample| environment are controlled by the same +parameters that control the indentation of the list environments, as +described in Sect.~\use{sect.env-indent}. +The general method used by all of these macros to turn off \TeX's usual +mechanism for interpreting special characters is discussed in \TeXbook, +p.~421ff. The \cs{begintt} and \cs{beginlines} macros described there are +included in \TeXsis\ for completeness. + +%>>> EOF TXSenvmt.doc <<< |