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

%% file: TXSmisc.doc  - Miscellaneious Macros - TeXsis version 2.18
%% @(#) $Id: TXSmisc.doc,v 18.2 2000/05/17 00:19:46 myers Exp $
%======================================================================*
% (C) Copyright 1992 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\input Manual.aux\draft\fi

\section{Miscellaneous Macros                  \label{sect.misc}}

There are a number of useful macros in \TeXsis\  which don't fit into any
of the topics covered in previous sections but which still deserve some
discussion.  We will simply lump them all together in this final
section.

\subsection{{\tt\string\draft} mode}

Saying \CS{draft} turns on a number of features which are useful for 
making a draft copy of a document.  The disclaimer ``{\tt Preliminary
Draft}'' is added to the bottom of each page of the document, along with
the page number and a time and date stamp.  The page number will let you
keep track of the page order even when using a document format which
does not print page numbers (such as the \cs{nuclproc} or
\cs{NorthHollandTwo} camera-ready formats).    The date/time stamp
can help you tell later drafts from earlier versions of the same
document.  \CS{draft} sets \cs{eqnotracetrue} so that equations
are marked with their internal labels in the right margin next to
the equation number (as described in Section~\use{sect.eqns}).
Other kinds of errors, such as trying to use undefined labels for citations
equations, are also marked in the right-hand margin.  \CS{draft} also
sets \cs{overfullrule}|=1em| so that over full \cs{hbox}es are marked
with a black box.  
Without \CS{draft}, initializing \TeXsis\  with \cs{texsis} sets
\cs{overfullrule}|=0pt| so that over-full hboxes don't 
get these kinds of marks (while with plain \TeX\  you do get these
marks).

\bigskip
%======================================================================*
\subsection{Ignoring blocks of text}

Sometimes you'd really like to take out a whole paragraph or an even 
larger section of a document, but only temporarily, and you don't want
to actually delete it from the manuscript file.  Recalling that in
\TeX\  everything on a line following the comment character ``{\tt\%}'' is
discarded, you could put a {\tt\%} on each line to be ignored,
but that could be a lot of work.  Instead, you can use \CS{comment}.
The syntax is:
\TeXexample
\comment/*  anything in here is ignored */
|endTeXexample
\noindent
Everything between the |/*| and the |*/| is completely ignored.  By
removing the |\comment/*| and the |*/| the text can easily be restored
to its previous state.  You can include several paragraphs of text in
the material to be ignored, or even several pages, but with one
important restriction: All the curly brackets |{| and |}| must match in
the text to be ignored.  If there is a |{| with no closing |}| in the
commented text then \TeX\  will skip the |*/| while searching for the
closing |}|!

Along the same lines is \CS{Ignore}, which will ignore everything
following it up to \cs{endIgnore} (with the same restrictions above
about matching grouping brackets).  The useful thing about these is that
if an \cs{endIgnore} is encountered before an \CS{Ignore} then the
\cs{endIgnore} is simply ignored.  Is that too confusing?  What this means
is that if you have a document with a large block of conditional text
that you may or may not want included you can choose to include the text
by simply removing (or commenting out) the \CS{Ignore}.  If the block of
conditional text looks like 
\smallskip\goodbreak
\def\1{\meta{unconditional text}}\def\2{\meta{more unconditional text}}
\TeXexample
|1
\Ignore
Having obtained these eigenvalues we would like to 
know their degeneracies.  For a given $l$ the ...
...
It is relatively easy to show that the number of 
independent components of such a tensor is ${N+l \choose l}$.
\endIgnore
|2
|endTeXexample
\noindent
then even if the block of text to be ignored spans many pages it can be
restored simply by changing the ``|\Ignore|'' to ``|%\Ignore|.''  Then
the |\Ignore| is itself ignored, and when \TeX\  reaches the |\endIgnore|
this also does nothing.  The effect is the same as if these two commands
were completely removed from the manuscript file, but it is easily
reversed.

Why are there two ways to ignore blocks of text?  \cs{comment} was
created first, and some programmer-types may prefer it because of the
similarity it bears to comments in the C programming language.
\cs{Ignore} is newer and probably a little more useful, but \cs{comment}
will remain for those who want to use it.

%======================================================================*
\subsection{Checkpoint/Restart \label{sect.chkpt}}

   The checkpoint/restart feature allows long documents to be printed in
pieces.  You can, for example, process and print the first chapter of a
thesis (or a book) and then later do the same for following chapters.
Saying \CS{checkpoint}|{NAME}| saves the settings of important counters
like the current page number and the last equation number in a file
called |NAME.chk|.  Saying \CS{restart}|{NAME}| reads in this file and
resets the counters to their previous values.
\index{checkpoint}\index{restart}\index{restore|see{restart}}

   As an example consider a document with two major chapters.
Using a Master File you would first process the first chapters
with the following:
\TeXexample
\thesis
\input chap1
\checkpoint{chap1}
\bye
|endTeXexample
With this printed you could resume at the next page number with
the correct subsequent numbers for equations, figures and tables
by saying:
\TeXexample
\thesis
\restart{chap1}
\input chap2
\bye
|endTeXexample 
\noindent 
Normally |\checkpoint| and |\restart| are silent,
but you can say \CS{endstat} to see the values of the counters
saved by |\checkpoint|.  The output looks like this:
\TeXexample
% Last PAGE      number IS 63.
% Last CHAPTER   number IS 0.
% Last EQUATION  number IS 47.
% Last FIGURE    number IS 1.
% Last REFERENCE number IS 9.
% Last SECTION   number IS 13.
% Last TABLE     number IS 0.
|endTeXexample

Modern laser printer drivers or filter programs like |dvips|, |dvi2ps|, 
or QTeX have 
options that let you select which pages of a document are printed,
or there is a useful program called |dviselect|, which can select
certain pages out of a dvi file into a smaller dvi file.  These offer
other ways to selectively print only part of a document
and still get the page and equation numbers correct.

%======================================================================*
\subsection{Other Goodies...}

These macros do various useful things:
\singlelinetrue                         % make label overhang
\description{unobeyspaces}\clump                %


\itm{\CS{jtem}\arg{label}\arg{dimen}}
Similar to plain \TeX's |\item|, but sets the label \arg{label} with a
variable hanging indentation \arg{dimen}.

\itm{\CS{leftpar}\arg{text}}
Turns the \meta{text} into a paragraph with a ragged {\sl left} margin.

\itm{\CS{pagecheck}\arg{dimen}}
Checks the amount of space remaining on the current page, and if this is
less then \meta{dimen} then skips to a new page.

\itm{\CS{topspace}}
Use this like \cs{vskip} to create a blank space to the top of a page 
(because any space inserted with \cs{vskip} is thrown out if it appears
at the top of a page).  Example: |\topspace 2.54cm|.

\itm{\CS{unobeylines}}
The opposite of \cs{obeylines}, so line endings are no longer respected.

\itm{\CS{unobeyspaces}}
The opposite of \cs{obeyspaces}, so that spaces in the manuscript file
are not counted exactly.

\enddescription

%----------------------------------------%
\pagecheck{3cm}

\subsubsection{Underlines}

These macros let you underline words or create a ``blank'' line:
\index{underlines}

\description{unobeyspaces}\clump                %

\itm{\CS{undertext}\arg{text}}
Underlines the \meta{text}, as in this \undertext{example}.  This is
generally okay for words but not phrases or sentences.

\itm{\CS{theBlank}\arg{length}}
Creates an underline of the specified length where one can ``fill in the
blank.''  For example, saying `` |Name: \theBlank{6cm}| produces:
``\hbox{Name:~\theBlank{6cm}}''.

\enddescription

%----------------------------------------%
\subsubsection{Boxes}

These macros let you put boxes around text or equations, or 
something similar:
\index{boxes}

\description{unobeyspaces}\clump                %

\itm{\CS{tightbox}\arg{box}}
Puts a ruled box around the argument (which must be a box), with no
intervening space.
Example: |\tightbox{\hbox{Boo}}| produces ``\tightbox{\hbox{Boo}}'', 


\itm{\CS{loosebox}\arg{box}}
Puts a ``loose'' box around the \meta{box}, with about one \cs{jot} of
space between the edge of the \meta{box} and the enclosing box. What you
do with this resulting box is up to you.  Rules are {\sl not\/} put
around this outer box, but you can enclose it in a \CS{tightbox} to do
so, as in |\tightbox{\loosebox{Boo}}|, which gives
``\tightbox{\loosebox{Boo}}.''  If you want the contents of this box to
match the baseline of the current line, lower it by a \cs{jot}, as in
|\lower\jot\tightbox{\loosebox{Boo}}|, which gives
``\lower\jot\tightbox{\loosebox{Boo}}''.


\itm{\CS{spine}\arg{text}}
Creates a label enclosed in a ruled box, suitable for the spine of a
3-ring binder.  The box will be at least 15~cm long, but will extend if
the text requires more space.  The default type size is 24~pt, but can
be changed in the \meta{text}.  If the label is longer than the width of
a page then it should be printed in landscape mode.  Instructions for
installing the label in the spine of a binder are printed (but only once).

\pagecheck{5\baselineskip}

\itm{\CS{eqnbox}\arg{math-expr}}
Puts a box around the mathematical expression \meta{math-expr}.
This can be useful for highlighting an important result. 
You can use this in any kind of math
mode, but usually you will want to use it in a displayed equation, 
like so:
\TeXexample
$$
\eqnbox{E=mc^2}
\EQN 47$$
|endTeXexample
which produces:
$$
\eqnbox{E=mc^2}
\EQN 47$$
In an in-line math expression it appears like so: \eqnbox{E=mc^2}.\n
Be careful not to over-use this, or its utility is lost!

\itm{\CS{eqnmark}}
Putting a box around an equation can be to distracting, but it is nice
to have a way to mark ``important'' results.  This is an alternative
to \CS{eqnbox}.  Simply put \CS{eqnmark} at the beginning of the
displayed equation, immediately after the |$$|, and it will put a marker
defined by \CS{eqnmarker} at the left edge of the equation (the default
is ``$\eqnmarker$'').
For example, typing
\TeXexample
$$\eqnmark
E=mc^2  
\EQN 47$$
|endTeXexample
\noindent 
produces
$$\eqnmark
E=mc^2          
\EQN 47$$
Note that \CS{eqnmark} does not work with \cs{eqalignno} or \cs{EQNalign} 
(which is just as well, so that you can't overuse it).

\enddescription

%==================================================*

\subsubsection{Read the Code}

There are a number of other macros in \TeXsis\  which  are not
described in this manual, either because (a) we didn't have time
to describe everything, or (b) they are works in progress.
In either case, if you are familiar enough with \TeX\  to write
some simple macros for yourself, then you are familar enough to
read through the code and find other useful goodies, or learn some new
tricks.  Just keep in mind that anything not described in the manual
may be subject to change in a future release.  And let us know if you
find any mistakes.

%>>> EOF TXSmisc.doc <<<