%% 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 main() { printf("hello, world\\n"); } \endListing \noindent which was created by simply typing, \TeXexample |tentt\Listing #include 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 <<<