summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/otherformats/texsis/base/TXSenvmt.doc
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/otherformats/texsis/base/TXSenvmt.doc')
-rw-r--r--Master/texmf-dist/doc/otherformats/texsis/base/TXSenvmt.doc610
1 files changed, 610 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/otherformats/texsis/base/TXSenvmt.doc b/Master/texmf-dist/doc/otherformats/texsis/base/TXSenvmt.doc
new file mode 100644
index 00000000000..34de0ac5927
--- /dev/null
+++ b/Master/texmf-dist/doc/otherformats/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 <<<