doc 5

git-svn-id: svn://tug.org/texlive/trunk@81 c570f23f-e606-0410-a88d-b1316a301751

2 files changed, 844 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/plain/tugboat/tubguide.pdf b/Master/texmf-dist/doc/plain/tugboat/tubguide.pdf
new file mode 100644
index 00000000000..19e97d6f1f0
--- /dev/null
+++ b/Master/texmf-dist/doc/plain/tugboat/tubguide.pdf
diff --git a/Master/texmf-dist/doc/plain/tugboat/tubguide.tex b/Master/texmf-dist/doc/plain/tugboat/tubguide.tex
new file mode 100644
index 00000000000..ef930b2ebaa
--- /dev/null
+++ b/Master/texmf-dist/doc/plain/tugboat/tubguide.tex
@@ -0,0 +1,844 @@
+%% @texfile{
+%%     filename="tubguide.sty",
+%%     version="1.02",
+%%     date="9-Mar-1992",
+%%     filetype="TUGboat Authors' Guide",
+%%     copyright="Copyright (C) TeX Users Group.
+%%            Copying of this file is authorized only if either:
+%%            (1) you make absolutely no changes to your copy, OR
+%%            (2) if you do make changes, you first rename it to some
+%%                other name.",
+%%     author="TeX Users Group",
+%%     address="TeX Users Group",
+%%            P. O. Box 9506,
+%%            Providence, RI 02940,
+%%            USA",
+%%     telephone="401-751-7760",
+%%     email="Internet: TUGboat@Math.AMS.com",
+%%     codetable="ISO/ASCII",
+%%     checksumtype="line count",
+%%     checksum="844",
+%%     keywords="tex users group, tugboat, authors' guide",
+%%     abstract="This file is an updated version of the file
+%%            that produced the original Authors' Guide in
+%%            TUGboat 10, no. 3, November 1989."
+%%     }
+%% *********************************************************
+%%
+%%  TeXing this file requires the following files:
+%%      TUGBOAT.STY (version 1.09+)
+%%      TUGBOAT.CMN (version 1.08+) (loaded by TUGBOAT.STY)
+%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\input tugboat.sty
+
+\enablemetacode
+\everyverbatim{\enablemetacode}
+\def\halfline{\vskip 0.5\baselineskip \ignoreendline}
+
+% ****************************************************************
+
+\title *\TUB\/ Authors' Guide*
+
+\author * Ron Whitney *
+\address * \TUG\\
+	   \POBox 9506\\
+	   Providence, RI 02940-9506 *
+\netaddress * TUGboat@Math.AMS.com *
+
+\author  * Barbara Beeton *
+\address * American Mathematical Society\\
+	   \POBox 6248\\
+	   Providence, RI 02940-6248 *
+\netaddress * TUGboat@Math.AMS.com *
+
+
+\vfootnote{}{Revised March 1992; the original appeared in \tubissue 10(3),
+November 1989.}
+
+\article
+
+With this article we hope to fill a lacuna (some might say ``void'')
+whose existence we have been attributing to the usual factors: tight
+schedules, alternative priorities and warty \TeX\ code.  We now feel
+the macros in use for \TUB\/ have stabilized to the extent that
+documentation and suggestions for authors will remain fairly constant,
+and we hope this article can serve as a reasonable guide to
+preparation of manuscripts for \TUB.  Authors who have used the \TUB\/
+macros before will note several changes (including more modern names
+for the style files).  Suggestions and comments are quite welcome at
+the addresses listed below.
+
+\TUB\/ was originally typeset with a package based only on \plain.
+Later, as demand for style files follows wherever
+\LaTeX-devotees wander, a \TUB\/ variant of the \LaTeX\ {\tt article}
+style was also created.  The two macro sets yield
+much the same output, differing in certain ways for input.  Below we
+make comment on various aspects of the \TUB\/ package, first for the
+\plain-based macros, then for \LaTeX.  The macro sets share
+the file |tugboat.cmn|,\footnote{$^1$}{This file used to be named
+{\tt tugboat.com}, but that notation was in conflict with conventions
+of MS-DOS and other operating systems; no conflicts are known to
+exist for the new name.} and users of either style should read the
+section entitled ``Common Abbreviations and Utilities''.  We conclude
+with some general suggestions to help make the lives of those on the
+receiving end of (any kind of) electronic copy a little easier.
+
+
+\head * The \plain-based macros: {\tt tugboat.sty} *
+
+The macros are contained in two files, |tugboat.sty| and |tugboat.cmn|.$^1$
+
+\subhead * General description of tags *
+We attempt wherever possible to tag the various elements of \TUB\/
+articles in a ``generic'' way, modified in some respects by
+convenience.  Authors and editors, of course, need tools to shape
+their articles to the form they desire, but we also wish to encourage
+a tagging style which is appropriate for electronic interchange.  It
+seems unfair to expect much thought from authors concerning the
+markup of their information if we only provide a bag of widgets and
+do-hickies to hack and pound an article together.  The tags whose use
+we encourage are the higher-level tags that mark the logical
+document structure.  Below these are formatting macros that we
+recognize may be essential for certain applications.  Both sorts of
+tags are described in the following article.
+
+Generally, to ``mark up'' the data <foo>, a tag |\xxx| will precede
+<foo> and |\endxxx| will follow (thus: |\xxx <foo>\endxxx|).  We use
+the |{...}| form to delimit arguments of lower-level formatting
+macros.  Optional commands follow tags and are enclosed in
+|[\lastoption][...]|, \`a la \LaTeX.  Several options may be enclosed
+within one set of square brackets, or each
+option may be enclosed in its own set of brackets.  These ``options''
+are actually just \TeX{} commands, and it is always possible to
+insert raw \TeX{} code as an option.  Such practice violates truly
+generic markup, but it is {\it helpful\/} and at least confines
+The Raw and Dirty to a smaller area.
+\subtext
+Perhaps a little more detail is of use to some readers here.
+Upon encountering a tag, the general operational scheme of the
+macros is as follows:
+\verbatim[\makecomment\%]%
+[\def\lquote{`}\def\rquote{'}\makeescape\|\makebgroup\`\makeegroup\']%
+[\displaystyle{\everypar{\hangindent2\parindent}\advance\baselineskip by 1pt}]
+<read tag>
+\begingroup
+<set defaults>
+\the\every...
+<read options>
+<branch to appropriate action,|hfil|break|ignoreendline
+using `|rm|lquote|lquote'argument|/`|rm|rquote|rquote' as necessary>
+<cleanup>
+\endgroup
+\endverbatim
+The scheme shows that code inserted as an option is localized and that
+it may be used to override certain defaults and to guide branching.
+Things are not always simple, however.  Sometimes parameters are set
+after a branch is taken (e.g.\ the macros might only call |\raggedright|
+after determining whether the mode is ``|\inline|'' or
+``|\display|''), and, despite localization, parameter setting might
+affect the current paragraph if a branch has yet to be taken.
+This is {\it not\/} to say the macros don't work, but rather that
+those authors who venture beyond the documented regions of the
+macros should do so with their eyes open.
+\endtext
+
+For convenience, we also allow the |*| as a delimiter for the
+higher-level tags; thus we could use either
+||\title \TUB\/ Authors' Guide \endtitle||
+or
+||\title * \TUB\/ Authors' Guide *||
+to indicate the title of this paper.  To typeset a \ast{} within text
+delimited by |*|, the \plain\ control sequence |\ast| has been extended
+to give
+\ast{} in text and the usual $\ast$ in math.
+\subtext
+This markup scheme may suffer at the hands of \TeX's parsing mechanism
+when tagged data is nested.  In these cases, one may group (|{...}|)
+embedded data so that \TeX{} knows to proceed to the next |\end...|
+or |*|.
+\endtext
+
+In the cases where we show extra spaces and carriage returns around
+arguments in this article, those (discretionary) spaces are
+accommodated in the macros.  Thus, for example, when the argument to
+|\title| above is typeset, |\ignorespaces| and |\unskip| surround it
+and the extra spaces have no untoward effect.  Spaces are also
+gobbled between options.
+
+
+\subhead * Outer form *
+At the outermost level, a source file will have the form (using the
+|*...*| delimiters):
+\verbatim[\makeescape\|]
+\input tugboat.sty
+|halfline
+<perhaps additional macros for article>
+|halfline
+\title * <title> *
+\author * <author> *
+\address * <address> *
+\netaddress * <network address> *
+|halfline
+\article
+|vellipsis
+<body of article>
+|vellipsis
+\makesignature
+\endarticle
+\endverbatim
+
+Data preceding |\article| is saved and typeset when |\article|
+is encountered.  Each author should have his/her own
+||
+\author ...
+\address ...
+\netaddress ...
+||
+block, and the macros will do their best to combine the information
+properly in the appropriate places.  Explicit linebreaks can be
+achieved within any of these items via |\\|.  Title and authors are,
+of course, set at the beginning of an article; the address
+information is listed separately in a ``signature'' near the end of
+an article, and is present for the convenience of those who might
+photocopy excerpts from an issue of \TUB.  |\makesignature| does the
+typesetting work.  Generally authors are listed separately in the
+signature.  In cases where authors and addresses are to be combined,
+one may use |\signature{...}| and |\signaturemark| with some or all
+of
+||
+\theauthor {<author number>}
+\theaddress {<author number>}
+\thenetaddress {<author number>}
+||
+to get the desired result.  For example, for an article with
+\verbatim[\outputtofile{ray.vbm}]
+\author * Ray Goucher *
+\address * \TUG *
+\netaddress *TUG@Math.AMS.com*
+
+\author * Karen Butler *
+\address * \TUG *
+\netaddress *TUG@Math.AMS.com*
+\endverbatim
+we could say
+\verbatim[\outputtofile{sig.vbm}]
+\signature {
+  \signaturemark
+  \theauthor1 and \theauthor2\\
+  \theaddress1\\
+  \thenetaddress1}
+\endverbatim
+to obtain the signature
+\begingroup
+\authornumber=0
+\input ray.vbm
+\input sig.vbm
+\makesignature
+\medskip
+\endgroup
+
+\noindent
+Use of at least |\thenetaddress| is recommended for this just so that
+the network address gets formatted properly.  The optional command
+|[\lastoption][\network{...}]| will introduce the network address
+with a network name, so
+||[\outputtofile{code.vbm}]
+\netaddress[\network{Internet}]
+   * TUGboat@Math.AMS.com *
+||
+produces
+{\authornumber=1
+ \input code.vbm
+ \figure[\mid\nofloat] \leftline{\kern\parindent\thenetaddress1} \endfigure
+}
+
+\leavevmode|\endarticle| marks the end of input and is defined as
+|\vfil\end| for most uses.  We redefine it as |\endinput| to
+assemble streams of articles in \TUB.
+
+
+\subhead * Section Heads *
+Heads of sections, subsections, etc.\ are introduced with |\head|,
+|\subhead|, etc., respectively.  The underlying macros all use
+|\head|, so |\endhead| is the long-form ending for all these tags. 
+For example, the first two heads of this article could have been
+keyed as
+||
+\head The \plain-based macros:
+   {\tt tugboat.sty} \endhead
+||
+and
+||
+\subhead General description of
+   tags \endhead
+||
+
+In \TUB\/ style, the paragraph following a first-level head is not
+indented.  This is achieved by a look-ahead mechanism which gobbles
+|\par|s and calls |\noindent|.  Actually all of the |\...head| tags
+gobble pars and spaces after their occurrence.  This allows one to
+enter a blank line in the source file between head and text, such
+practice being a visual aid to your friendly \TUB\/ editors (if not to
+you).  Be careful of that |\noindent| after a first-level head:
+you will be in horizontal mode after the |\head *...*|, so spaces
+which {\it appear\/} innocuous, may not be so.
+
+
+\subhead * Lists *
+Lists are everywhere, of course, and a simple list hierarchy can
+transform a one-dimensional typesetting problem into something
+nasty.  All of which is to say, we are certainly not done with
+this area of tagging, but here are the available macros.
+
+Not surprisingly, |\list| marks the beginning of a list.  A list
+can be itemized, wherein each item is tagged with |\item|, or
+unitemized wherein items are delimited by |^^M| (the end of your
+input line).  The itemized
+style is the default and |[\lastoption][\unitemized]| will get
+the other.  Tags for the items default to the |\bullet|
+($=\bullet$), but can be changed by feeding an argument to
+|\tag{...}|.  The |[\lastoption][\tag{...}]| option
+used with |\list| assigns the tag for each item of the entire
+list, while |[\lastoption][\tag{...}]| used with |\item| changes
+only the tag for that item.  The obvious dynamical tags are available
+with options
+\verbatim[\makeescape\|\makebgroup\`\makeegroup\']
+\numbered
+\romannumeraled
+\lettered    `|rm(lowercase)'
+\Lettered    `|rm(uppercase)'
+\endverbatim
+
+Lists can be set in several columns by setting |\cols=...|.  The
+columns are aligned on their top baselines and the user must
+break the columns with |\colsep|.  Thus,
+\verbatim[\outputtofile{code.vbm}]
+\list[\unitemized\numbered][\cols=2]
+Fourscore
+and seven
+years ago
+our fathers
+\colsep
+brought forth
+on this
+continent
+\endlist
+\endverbatim
+yields
+\input code.vbm
+
+|\everylist| is a token register which is scanned at the beginning
+of each list
+after the default parameters are set and before
+options are read.  If you want all your lists numbered, for example,
+you might insert ||\everylist{\numbered}|| at the top of your file
+rather than giving an option to each list.
+
+Implementation of sublists is under construction.
+
+\subhead * Verbatim Modes *
+
+There are several variations on this theme.  In each case, text is
+printed in a typewriter font and (almost) all input characters
+produce the glyph in the font position of their character-code (i.e.\
+you get what you type, no escaping it).  In addition to the long form
+||\verbatim...\endverbatim|| the \verbinline|\endverbatim\ character
+can be used to enter and leave verbatim mode, acting as a toggle much
+as the |$| does with math.  \verbinline|...|\endverbatim\space
+produces inline verbatim text, while \verbinline||...||\endverbatim
+displays its output.  |\verbatim| itself defaults to display form,
+but |\verbatim[\inline]| and its contraction |\verbinline| (both
+terminated by |\endverbatim|) produce the inline form.  |^^M| yields
+a space inline, and a new paragraph in display.  Generally, for
+snippets of text we use the \verbinline|...|\endverbatim form, and
+for longer items the
+||[\makeescape\!]
+\verbatim
+!vellipsis
+\endverbatim
+||
+form (although \verbinline||...||\endverbatim is a good way to
+display a single line of code).
+
+In addition to formatting text between |\verbatim| and
+|\endverbatim|, |\verbatim| may read and write data from and to
+files.  We find this variant useful in ({\it almost\/}) guaranteeing
+consonance between macros in use and their published listings.
+||[\makeescape\!]
+\verbatim[\inputfromfile{foo.inp}]
+!vellipsis
+\endverbatim
+||
+will incorporate the contents of file |foo.inp| in the listing before
+the text between |\verbatim| and |\endverbatim|.  The shortened form
+||\verbfile{foo.inp}\endverbatim|| accomplishes the above in the case
+that the text is empty.  While the code around the data, |foo.inp|,
+above looks excessively long, do remember the implementation
+uses the basic |\verbatim| macro, so options can also be read after
+the filename.  For example,
+||
+\verbfile{foo.inp}[\numbered]
+\endverbatim
+||
+would number the lines of the listing.
+
+We often rearrange code supplied to us so
+that it fits in the narrow measure of \TUB's two-column format, and
+we sometimes make corrections to macro sets (you thought you were
+perfect!).  Since errors can (and do\Dash we aren't perfect either)
+creep in with these modifications, we use the above technique to
+maintain consistency between the listing published in \TUB\/ and the
+underlying macros used for examples.
+
+To write out information, use
+||[\makeescape\!]
+\verbatim[\outputtofile{foo.out}]
+!vellipsis
+\endverbatim
+||
+An added bonus here is that characters which get internalized as
+moribund ``letters'' or ``others'' in the process of listing them,
+can return revitalized for perhaps their real use when written out to
+another file and read in again.  The example above involving Ray
+and Karen was coded as
+||[\makeescape\/][\makeactive\!][\def!{\VertChar}]
+... to get the desired result.  For
+example, for an article with
+\verbatim[\outputtofile{ray.vbm}]
+\author * Ray Goucher *
+/vellipsis
+\endverbatim
+we could say
+\verbatim[\outputtofile{sig.vbm}]
+\signature {
+  \signaturemark
+  \theauthor1 and \theauthor2\\
+  \theaddress1\\
+  \thenetaddress1}
+\endverbatim
+to obtain the signature
+\begingroup
+\authornumber=0
+\input ray.vbm
+\input sig.vbm
+\makesignature
+\endgroup
+||
+This is perhaps not the most edifying example, but you get the gist.
+(We localize the process of storing and retrieving these
+authors and addresses so as not to clobber our own.)
+We would encourage our authors to use these mechanisms for connecting
+verbatim text to external files for the sake of maintaining
+consistency between active code and its documentation.
+
+\leavevmode|\verbatim| scans to |\endverbatim| (a 12-token sequence
+since the |\| is of type `other' after |\verbatim| gets going).  Only
+this sequence of characters will interrupt the scan.  On the other
+hand, \verbinline|\endverbatim and \verbinline||\endverbatim scan to
+the next \verbinline|\endverbatim and \verbinline||\endverbatim,
+respectively.  Needless to say, one should use forms of |\verbatim|
+to set text which contains \verbinline|\endverbatim (and
+\verbinline|\endverbatim or \verbinline||\endverbatim to set text
+containing |\endverbatim| if you are writing an article like this
+one).  Both the \verbinline|\endverbatim and |\verbatim| tags scan
+ahead for the usual |[\lastoption][| to check for options.  In those
+rare cases when the |[\lastoption][| is really supposed to be the
+first character of the verbatim text, use the option
+|[\lastoption][\lastoption]| to stop option parsing.  For example, to
+show ||[\lastoption][\lastoption]|| we keyed
+\verbatim
+|[\lastoption][\lastoption]|
+\endverbatim
+
+There are situations where one wants to typeset most things verbatim,
+but ``escape'' to format something exceptional.  For example, the
+insertions of metacode given in the listings above require some
+access to the italic font.  By giving the option
+|[\lastoption][\makeescape\!]| to |\verbatim|, the |!| is made an
+escape character in that block.  Thus,
+||[\makeescape\/]
+\verbatim[\makeescape\!]
+/vellipsis
+...!it...
+/vellipsis
+\endverbatim
+||
+really calls the italic font in the middle of the listing (one might
+also want to use |\makebgroup| and |\makeegroup| in the options to define
+characters to localize this call; see p.~384).  Situations
+will dictate preferences for what character may be used as an escape
+(we use the \verbinline|\endverbatim, |!|, and |/| in this article).
+There is also a means of changing the setup of every occurrence of
+verbatim mode.  The contents of token register |\everyverbatim|
+is scanned after the defaults of verbatim mode
+have been set.  In this article, for example, we have made 
+|[\makeother\<]<| active and defined it in such a way that
+|[\makeother\<]<...>| typesets as metacode.  Since |\verbatim|
+ordinarily changes |[\makeother\<]<| to type `other' on startup, we key
+||\everyverbatim{\enablemetacode}|| at the beginning of the file
+to have the proper adjustment made whenever verbatim is started.
+
+When ``escaping'' within a verbatim block, one should be aware that
+spaces and carriages returns are {\it active\/} and hence not gobbled
+as usual.  Using the |!| as the active character, one might key
+||[\makeescape\/]
+\verbatim[\makeescape\!]
+/vellipsis
+!vskip .5!baselineskip
+/vellipsis
+\endverbatim
+||
+to get an extra half line of space in the middle of the listing.  The
+space and carriage return on this line, however, cause problems.  The
+space expands to |\ifvmode\indent\fi\space| and \TeX\ will not like
+the |\indent| after |\vskip|.  The |^^M| expands to
+|\leavevmode\endgraf|, and therefore puts an extra line into the
+listing.  The solutions, in this case, are to drop the space and to
+use |!ignoreendline| (which just gobbles the |^^M|), but one should
+be aware, generally, that some thought may be required in these situations.
+
+The option |[\lastoption][\numbered]| causes the lines of a
+verbatim listing to be numbered, while |[\lastoption][\ruled]|
+places rules around the whole thing:
+\verbatim[\numbered\ruled]
+<code>
+<more code>
+<yet more code>
+...
+\endverbatim
+The option |[\lastoption][\continuenumbers]| picks up the numbering
+where it last left off.
+\verbatim[\continuenumbers]
+<more>
+<and more>
+...
+\endverbatim
+
+The code underlying |\verbatim| in display style implements each line
+as a paragraph and places math-display-size whitespace above and
+below the verbatim section.  Page and column breaks {\it are\/}
+permitted within these listings.  To prohibit breaks at specific
+points or globally, one must insert penalties or redefine |^^M| to
+insert |\nobreak| in the vertical list at the end of each
+``paragraph'' (i.e.\ line).  We should also note that the bottom of
+such a verbatim listing is implemented so that ensuing
+text may or may not start a new paragraph depending on whether an
+intervening blank line (or |\par|) is or is not present.
+
+
+\subhead * Figures and Page Layout *
+Figures are keyed as
+\verbatim[\makeescape\|]
+\figure
+|halfline
+<vertical mode material>
+|halfline
+\endfigure
+\endverbatim
+These are generally implemented as single-column floating
+top-insertions, but the options |[\lastoption][\mid]| and
+|[\lastoption][\bot]| can change specific items to be mid- or
+bottom-insertions, respectively.  Here we recommend that the
+long-form terminator be used ({\it not\/} the |*...*| form).  One can
+think of the information ``passed'' as being ``long'' in the sense of
+possibly containing paragraphs, this being a mnemonic device only. 
+The primary reason for the recommendation is that one is (in some
+sense, maybe) more likely to encounter a rogue |*| in longer text
+than in shorter text and hence more likely to encounter a surprising
+result due to a macro stopping short at the wrong |*|.
+
+\subtext
+Perhaps here is a natural place to mention also that these macros
+sometimes read their arguments and then act, and sometimes act on the
+fly, not actually storing an argument as a string of tokens at all. 
+|\title|, for example, is in the former category, while |\figure| is
+in the latter.  Reasons may vary for the choice in
+methods.  Storing a string of tokens as an argument does not allow
+re-interpretation of the category codes of the underlying
+character string.  Thus, storing
+the ``argument'' of |\figure| all at once might misinterpret some
+characters which should appear as verbatim text.  For this reason we
+set figures as we go and just close off the box with |\endfigure|. On
+the other hand, using information in multiple situations (e.g.\
+titles and running heads) requires storing the information as a token
+string, not as a typeset list.
+
+When text delimited by |*...*| is read as an argument, the |*|s are
+dropped by the parsing process.  When the text is handled on the fly,
+the first |*| is gobbled and the second is made active to perform
+whatever action is necessary at the close of the macro.  When
+possible, we prefer to operate on the fly since nested tags are
+handled properly in that case and no memory is consumed to store
+arguments.  Examination of |tugboat.sty| will show which case applies
+in a given situation, but this general knowledge may help when trying
+to debug those situations in which an unexpected |*| has disrupted
+things.
+\endtext
+
+
+A primitive |\caption{...}| option is available to |\ulap|
+(i.e.\ lap upward) its argument into the figure space, but
+formatting of the caption is left to the user.  For example,
+the code:
+\verbatim[\outputtofile{code.vbm}]
+\figure[\top]
+  [\caption{\centerline{Odd Fig.~1}}]
+\vbox to 5pc{}
+\endfigure
+\endverbatim
+produces the figure at the top of this column or the next.
+
+\input code.vbm
+
+Figures spanning columns at the top and bottom of a page are currently
+supported only on the first page of an article, but we expect they
+will soon be allowed on any page (a general rewrite of the output
+routine is in progress).  |\twocolfigure| (terminated by |\endfigure|)
+starts up such a figure and currently {\it must\/} occur before any
+material has been typeset on the first page (i.e.\ {\it before\/}
+|\article|).
+
+
+Macros |\onecol|, |\twocol|, and |\threecol| provide one-, two-, and
+three-column layouts, but these cannot currently be intermixed on a
+page.  We hope to provide automatic column-balancing and convenient
+switching between one- and two-column format within a year.
+|\newpage| in each format is defined to fill and eject enough columns
+to get to the next page.  |\newcol| is just |\par\vfill\eject|.
+
+\subhead * Command List Summary *
+Tags are listed in the order discussed.  Options are
+listed under tags.
+||
+\title
+\author
+\address
+\netaddress
+   \network
+\signature
+\article
+\makesignature
+\endarticle
+\head
+\subhead
+\subsubhead
+\list
+   \numbered
+   \romannumeraled
+   \lettered
+   \Lettered
+   \ruled
+   \tag{...}
+\item
+   \tag{...}
+\everylist
+\verbatim
+   \numbered
+   \ruled
+   \inputfromfile{...}
+   \outputtofile{...}
+\verbinline
+\verbfile
+\figure
+   \mid
+   \bot
+   \caption{...}
+\twocolfigure
+||
+and, of course, \verbinline|\endverbatim and \verbinline||\endverbatim.
+
+\head * The \LaTeX\ macros: {\tt ltugboat.sty} *
+
+|ltugboat.sty| is the primary macro file, and is based on the \LaTeX{}
+|article.sty|.  |tugboat.cmn|, a collection of items common to both
+\LaTeX\ and \plain\ input, is also required.  Articles will have
+the form:\footnote{$^2$}{{\tt ltugboat} used to be a substyle; it now
+stands on its own, by automatically inputting {\tt article.sty}.}
+\verbatim[\makeescape\|]
+\documentstyle{ltugboat}
+|halfline
+<perhaps additional macros for article>
+|halfline
+\title {<title>}
+\author{<author>}
+\address{<address>}
+\netaddress{<netaddress>}
+
+\begin{document}
+\maketitle
+|vellipsis
+<body of article>
+|vellipsis
+\makesignature
+\end{document}
+\endverbatim
+This is the usual form for \LaTeX\ documents, of course, except
+that now each author will have his/her own
+\verbatim
+\author{...}
+\address{...}
+\netaddress{...}
+\endverbatim
+block.  As with the \plain{} style, the author and address
+macros will store their information for later display.
+See the discussion of |\address|, |\netaddress| and |\makesignature|
+on the second page of this article to understand more.  Linebreaks
+within |\title|, |\author|, and |\...address| are specified with |\\|.
+
+We refer the user to the \LaTeX\ manual for description of section
+heads, verbatim mode, insertions, and movement between one- and
+two-column format.  The style of printed output has, of course, been
+somewhat modified to fit \TUB\/ style.  |ltugboat.sty| might be of some
+use to others wishing to modify the |article| option in this
+direction.
+
+
+
+\head * Common Abbreviations and Utilities *
+
+Definitions of a number of commonly used abbreviations such as |\MF|
+and |\BibTeX| are contained in |tugboat.cmn|.  Please use these whenever
+possible rather than creating your own.  We will add to the list as
+necessary.
+
+Several other constructions that we have found useful for both
+\plain- and \LaTeX-style input have been incorporated in
+|tugboat.cmn|.  Various |\*lap|\,s (|\ulap|, |\dlap|, |\xlap|,
+|\ylap|, |\zlap|) and |\*smash|\,es provide means of setting type
+which ``laps'' into neighboring regions.  |\dash| and |\Dash| are en-
+and em-dashes that break properly.  |\slash| is a breakable slash.
+The macro
+\verbatim
+\makestrut [<ascender dimen>;
+            <descender dimen>]
+\endverbatim
+allows {\it ad hoc\/} construction of
+struts.
+
+|\makeatletter| |\catcode|s the |@| for internal control-sequences.
+There are also more general functions
+\verbatim
+\makeescape
+\makebgroup
+\makeegroup
+\makeletter
+\makeother
+\makeactive
+\endverbatim
+that change the category of a given character into the type mentioned
+at the end of the macro name.  For example, |\makeactive\!| changes the
+category of the |!| to 13.  We have given many other examples of these in
+this article.  Readers may look at the end of |tugboat.cmn| after the
+|\endinput| statement to see further documentation on the contents of the file.
+
+
+\subhead * Issue Makeup *
+Constructing an entire issue of \TUB\/ requires use of a few features
+that authors may notice when articles are returned for proofing.
+|\xrefto| allows for symbolic cross-referencing, but is enabled only
+late in the production process.  The distribution version of
+|tugboat.cmn| defines |\xrefto| so that ``???'' is typeset whenever it
+is called.  Not to worry.
+
+We also put notes into the file since there are many things to
+remember, and these appear as |\TBremark{...}|.  Authors can look for
+such things, if they are interested.
+
+
+\head * General Coding Suggestions *
+
+Probably 90\% of the code we receive is easily handled, and for this
+we are most appreciative.  We do have suggestions of a general nature
+that authors should keep in mind as they create articles for
+transmission here or anywhere else.
+
+Those who create code find it much easier to read and understand their
+own code than do others who read the ``finished'' product.  In fact,
+some people seem to forget that the electronic file will be viewed (in
+fact, studied) in addition to the printed copy.  Documentation and
+uniform habits of presentation always help.  Blank lines are easier to
+digest by eye than |\par|s.  Tables and display math can often be
+keyed in such a way that rows and columns are clear in the source file
+on a display screen as well as in print.  Explanations or warnings of
+tricky code can be {\it very} helpful.  Authors should place font and
+macro definitions in one location at the beginning of an article
+whenever possible.
+
+Authors should anticipate that articles will undergo some
+transformation, and that positioning of some elements may change
+simply because articles are {\it run together\/} in \TUB.  Decisions
+on linebreaks, pagebreaks, figure and table placement are generally
+made after the text is deemed correct. We avoid inserting ``hard''
+line- and page-breaks whenever possible, and will not do so, in any
+case, until the last minute.  We also use floating insertions for
+figure and table placement when we first receive an article.  It is
+easier for us to work with a clean file containing some bad breaks,
+overfull boxes or other unsightliness, than it is to handle a document
+containing {\it ad hoc\/} code dedicated to a beauteous (albeit
+narrowly specific) result.
+
+
+When authors proof their articles in formats other than that of \TUB\/
+(for example), they should expect that \TUB's changes in pagewidth and
+pagedepth may drastically alter text layout.  Paragraphs are rebroken
+automatically when |\hsize| and |\vsize| change, but |\centerline|
+does not break, and we often see tables and math displays which are
+rigidly laid out.  When possible, authors might use paragraphing
+techniques instead of calls to, say, |\centerline| (Beeton will be
+writing up her lectures on paragraphing techniques for a future issue
+of \TUB\/), and they should try to code tables in such a way that
+widths of columns can be changed easily.  Generally, authors should
+attempt to anticipate the work that might be necessary if requests for
+other reasonable formats of their texts are made.  In the case of
+\TUB, we make a strong effort to stuff macro listings and tables into
+the two-column format.  Since these types of items are not generally
+susceptible to automatic line-breaking, we give thanks to stuffings
+made by authors ahead of time.  In this context, we recommend the use
+of |\verbfile{...}| (see the section {\bf Verbatim Modes}) to maintain
+consistency between documentation and reality.
+
+Specifically in the domain of \TeX\ macros, we find that many authors
+throw in unnecessary |%| characters to end code lines.  Except in
+cases where the |^^M| means something other than end-of-line,
+linebreaks can reliably be placed after control-words and numerical
+assignments.  We have seen \TeX's buffer size exceeded when |%|
+was placed after {\it every\/} line.
+
+A wider perspective in the matter of naming macros can prevent
+problems that occur when definitions are overwritten as articles are
+run together.  The names of control sequences used in \plain, \LaTeX,
+and \AmSTeX\ are documented and authors should avoid using them for
+other purposes.  It is also wise to avoid commonly used names such as
+|\temp|, |\result|, |\1|, and |\mac| in presenting code that might be
+cribbed by other users.  The frequently used technique of temporarily
+|\catcode|ing a character to be a letter (e.g.\ the |@|) provides a
+good method of hiding control sequences so that they will not be
+clobbered later.  Readers are in need of small macros to do little
+tricks, and they often try suggestions brought forth in \TUB.  A
+little extra effort in making these macros consistent with the macros
+in wide distribution and in making them robust will be much
+appreciated.
+
+\TBremark{Anything about formatting macros?}
+
+
+\head * Electronic Documentation and Submission Procedure *
+
+In addition to |tugboat.sty|, |ltugboat.sty|, and |tugboat.cmn|,
+a copy of this article, |tubguide.tex|, will be available at
+most \TeX{} archives, including those at SHSU, Aston, and Stuttgart.
+
+Please address all electronic correspondence to the \TUB{} maildrop:
+||TUGboat@Math.AMS.com||
+Mail to either of our personal addresses is liable to go unseen if
+vacation or illness intervenes.  We also request that you supply
+an abstract of any expository article.  This will be used as the
+basis for translation of abstracts to languages other than that
+in which the article is published.
+
+
+\makesignature
+
+\endarticle