%% $Id: tubguide.tex 607 2024-10-26 22:26:03Z karl $
%% @texfile{
%%     filename   = "tubguide.tex",
%%     version    = "1.31",
%%     date       = "2024-10-26",
%%     filetype   = "TUGboat Authors' Guide",
%%     copyright  = "Copyright 1989, 1992, 2006, 2012-2024 TeX Users Group.
%%                   Unlimited copying and redistribution of this file
%%                   are permitted as long as this file is not
%%                   modified.  Modifications (and redistribution of
%%                   modified versions) are also permitted, but only if
%%                   the resulting file is renamed."
%%     email      = "TUGboat@tug.org",
%%     codetable  = "ISO/ASCII",
%%     keywords   = "tex users group, tugboat, plain authors' guide",
%%     supported  = "yes",
%%     abstract   = "This file is an updated version of the file
%%                   that produced the original Authors' Guide in
%%                   TUGboat 10, no. 3, November 1989.",
%%     }
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\input tugboat.sty

% tugboat.sty used to default to this, and no point in changing lots of
% text to fix overfull boxes.
\StretchyTenPointSpacing
\StretchyNinePointSpacing
\StretchyEightPointSpacing

\enablemetacode
\everyverbatim{\enablemetacode}
\def\halfline{\vskip 0.5\baselineskip \ignoreendline}

% ****************************************************************

\pageno=1
\def\rtitlex{\def\tubfont{\tenpoint\rm}\TUB{} Authors' Guide, March 2022}
\def\midrtitle{}

\title *\TUB\/ authors' guide*

\author  * Barbara Beeton *
\address * \TeX\ Users Group *
\netaddress * TUGboat@tug.org *

\author * Ron Whitney *
%\address * \TUG *
%\netaddress * TUGboat@Math.AMS.com *


\vfootnote{}{Revised March 1992, May 2006, May 2012, September 2016; the
original appeared in
\tubissue 10(3), November 1989.}

\article

With this report 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 only a \plain-based package. Later,
as demand for style files follows wherever \LaTeX\ devotees wander, a
\TUB\/ variant of the \LaTeX\ {\tt article} class was created\Dash see
the separate package |tugboat| (|https://ctan.org/pkg/tugboat|). The
two macro sets yield much the same output, and many input conventions
are identical, with differences where they seemed natural.

Below we describe various aspects of the \TUB\/ package for the
\plain-based macros. 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|.\footnote{$^1$}{1) A file |tugproc.sty| is also
distributed, but no longer used. 2) |tugboat.cmn| used to be named {\tt
tugboat.com}, but that notation was in conflict with conventions of
\acro{MS-DOS} and other operating systems; no conflicts are known to
exist for the new name.}

\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 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
...
<body of article>
...
\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%
\footnote{$^2$}{\xEdNote The \TUB{} email address shown in examples
was current when this article first appeared, but is now obsolete;
it has been left intact to avoid other problems.  The correct address
is now {\tt TUGboat@tug.org}.}
\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, 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
...
\endverbatim
||
form (although \verbinline||...||\endverbatim is a good way to
display a single line of code).

The display verbatim output is in nine-point typewriter by default, as
shown in this document.  We've found the extra characters of width
gained as a result are very useful.  If |\smallverbdisplay| is defined
to be a no-op, it will be in the usual ten-point.  (This change was
introduced in 2012.)

As well as formatting verbatim text between |\verbatim| and
|\endverbatim|, |\verbatim| can 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}]
...
\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}]
...
\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 *
...
\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\!]
...
...!it...
...
\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.~7).  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\!]
...
!vskip .5!baselineskip
...
\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 * Hyperlinks and urls *

As of version~1.31 of the \plain-based \TUB\ macros, released in October
2024, simple commands to create hyperlinks are available.

\list\raggedright
\item |\tbsurl{tug.org}| produces an https url, with the argument
      typeset in \cs{tt}: \tbsurl{tug.org}.
\item |\tbhurl{tug.org}| is analogous, for http urls: \tbhurl{tug.org}.
\item |\tbmailto{tugboat@tug.org}| produces a mailto url, again with the
      argument in \cs{tt}: \tbmailto{tugboat@tug.org}.
\item |\tbhref{https://tug.org}{the \acro{TUG} home page| is the general
      command, which typesets the second argument (no implicit font
      changes) as a link to the first argument (no implicit protocol
      added): \tbhref{https://tug.org/}{the \acro{TUG} home page}.
\endlist

At present, these commands only work in pdf\TeX. Other engines will be
supported as needed.

The links are displayed without a border, since we find link borders
distracting rather than helpful. There are no display options, to keep
things simple.

\subhead * Figures and page layout *
Figures are keyed as
\verbatim[\makeescape\|]
\figure
<vertical mode material>
\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 \verbinline|\endverbatim and \verbinline||\endverbatim input syntax.


\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.

A nicety for the sake of appearance is the command |\acro|, which
sets an acronym in caps one size smaller than the surrounding text.
Compare CTAN (full size), \CTAN{} (|\acro{CTAN}|) and {\smc ctan}
(small caps).  Acronyms in |tugboat.cmn| use |\acro| consistently,
except in (some) bibliographies.

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| is an em-dash with surrounding thinspaces, our preferred style.
|\slash| is a breakable slash.
|\cs{foo}| typesets |\foo|, just like \verbinline|\foo|\endverbatim (but
since |\cs| is the usual \TUB\ \LaTeX\ convention, we support it here too).
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 (but
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|, 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 `{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.


\head * Electronic documentation and submissions *

The TUGboat styles for both \LaTeX\ and plain \TeX\ are available on
\CTAN\ and already included in most \TeX\ distributions:

||https://ctan.org/pkg/tugboat
https://ctan.org/pkg/tugboat-plain||

Please address all electronic correspondence to the \TUB{} maildrop:
||TUGboat@tug.org||
Mail to 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.

\smallskip
The \TUB\ home page on the web is |https://tug.org/TUGboat|.

\makesignature

\endarticle