path: root/Master/texmf-dist/doc/texsis/base/TXSenvmt.doc

%% 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 <<<