summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/tugboat/ltubguid.ltx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/tugboat/ltubguid.ltx
Initial commit
Diffstat (limited to 'macros/latex/contrib/tugboat/ltubguid.ltx')
-rw-r--r--macros/latex/contrib/tugboat/ltubguid.ltx868
1 files changed, 868 insertions, 0 deletions
diff --git a/macros/latex/contrib/tugboat/ltubguid.ltx b/macros/latex/contrib/tugboat/ltubguid.ltx
new file mode 100644
index 0000000000..dcb817f014
--- /dev/null
+++ b/macros/latex/contrib/tugboat/ltubguid.ltx
@@ -0,0 +1,868 @@
+% $Id: ltubguid.ltx 216 2018-12-13 21:40:11Z karl $
+% ltubguid.ltx - documentation for ltugboat classes.
+%
+% Copyright 1994,1995,1996,2001,2005,2006,2010,2013,2014,2017,2018
+% TeX Users Group.
+%
+% This file is part of the tugboat package.
+%
+% This work may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.3
+% of this license or (at your option) any later version.
+% The latest version of this license is in
+% http://www.latex-project.org/lppl.txt
+% and version 1.3 or later is part of all distributions of LaTeX
+% version 2003/12/01 or later.
+%
+% This work has the LPPL maintenance status "maintained".
+%
+% The Current Maintainer of this work is the TeX Users Group
+% (https://tug.org/TUGboat).
+%
+% The list of all files belonging to the distribution is
+% given in the file `manifest.txt'.
+%
+% The list of derived (unpacked) files belonging to the distribution
+% and covered by LPPL is defined by the unpacking scripts (with
+% extension .ins) which are part of the distribution.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% tubguide.bib -- the bibliography for this paper (apart from the
+% references to TUGboat itself)
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+\begin{filecontents}{tubguide.bib}
+% BibTeX bibliography file (generated by aux2bib)
+
+@Misc{pkg:fancyvrb,
+ author = {Timothy Van Zandt and others},
+ title = {The {\textsf{fancyvrb}} package},
+ howpublished = {\url{ctan.org/pkg/fancyvrb}},
+}
+
+@Misc{pkg:listings,
+ author = {Carsten Heinz and others},
+ title = {The {\textsf{listings}} package},
+ howpublished = {\url{ctan.org/pkg/listings}},
+}
+
+@Misc{Arseneau:url:1996,
+ author = {Donald Arseneau},
+ title = {The {\textsf{url}} package},
+ howpublished = {\url{ctan.org/pkg/url}},
+}
+
+@Misc{Rahtz:hyperref:1997,
+ author = {Sebastian Rahtz and Heiko Oberdiek and others},
+ title = {The {\textsf{hyperref}} package},
+ howpublished = {\url{ctan.org/pkg/hyperref}},
+}
+
+@Book{Lamport:1994,
+ author = {Leslie Lamport},
+ title = {{\LaTeX}: A Document Preparation System},
+ edition = {\nth{2}},
+ year = {1994},
+ publisher = {Addison-Wesley},
+}
+
+@Misc{Schoepf:verbatim:1996,
+ author = {Rainer Sch{\umlaut{o}}pf},
+ title = {The {\textsf{verbatim}} package},
+ howpublished = {\url{ctan.org/pkg/verbatim}},
+}
+
+@Misc{Vieth:mflogo:1995,
+ author = {Ulrik Vieth},
+ title = {The {\textsf{mflogo}} package},
+ howpublished = {\url{ctan.org/pkg/mflogo}},
+}
+
+@Article{Whitney:TB10-3-378,
+ author = {Ron Whitney and Barbara Beeton},
+ title = {{{{\TUB} authors' guide}}},
+ journal = {{\TUB}},
+ year = {1989},
+ month = {November},
+ volume = {10},
+ number = {3},
+ pages = {378--385},
+ note = {\url{ctan.org/pkg/tugboat-plain}},
+}
+
+\end{filecontents}
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% ctandir.sty -- an experimental style file to go with Donald
+% Arseneau's url.sty. Not recommended these days, better to use
+% https://ctan.org/pkg/..., but don't feel like rewriting.
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+\begin{filecontents}{ctandir.sty}
+%
+% Experimental CTAN location information macros for use with Donald
+% Arseneau's |url.sty|
+%
+% we need url.sty; we can rely on it to demand anything it needs of
+% LaTeX. Not
+\IfFileExists{url.sty}%
+ {\RequirePackage{url}}%
+ {\PackageWarning{ctandir}{You should acquire a copy of url.sty}%
+ \newcommand\urldef[3]{\def#1{\texttt{#3}}}%
+ \let\url\texttt
+ }
+%
+\newcommand\CTANdirectory[1]{\expandafter\urldef
+ \csname CTAN@#1\endcsname\path}
+\newcommand\CTANfile[1]{\expandafter\urldef
+ \csname CTAN@#1\endcsname\path}
+%
+% Use the standard label-referencing mechanism to get the warning for
+% an undefined label
+\newcommand\CTANref[1]{\expandafter\@setref\csname CTAN@#1\endcsname
+ \relax{#1}}
+\end{filecontents}
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+\documentclass[final]{ltugboat}
+\usepackage{microtype}
+\usepackage{ctandir}
+\IfFileExists{booktabs.sty}%
+ {\usepackage{booktabs}}%
+ {\let\midrule\hline}
+%
+\vbadness=10000 % imperfectly broken pages are ok
+\overfullrule=4pt % want to see
+%
+% define CTAN addresses using the commands of the |ctandir| package
+\CTANdirectory{packages}{macros/latex/required}
+\CTANdirectory{tub-latex}{macros/latex/contrib/tugboat}
+%
+% ***** Commands provided by this paper *****
+%
+% Typeset the name of an environment, class, package, option, program
+\providecommand\envname[1]{\textsf{#1}}
+\providecommand\clsname[1]{\textsf{#1}}
+\providecommand\pkgname[1]{\textsf{#1}}
+\providecommand\optname[1]{\textsf{#1}}
+\providecommand\progname[1]{\textsf{#1}}
+%
+% A list of options for a package/class
+\newenvironment{optlist}{\begin{description}%
+ \renewcommand\makelabel[1]{%
+ \descriptionlabel{\mdseries\optname{##1}}}%
+ \itemsep0.25\itemsep}%
+ {\end{description}}
+%
+% A list of command names (using \mdwcmd, which as its name implies
+% comes from the work of Mark Wooding)
+\newenvironment{cmdlist}{\begin{description}%
+ \renewcommand\makelabel[1]{%
+ \descriptionlabel{\mdseries\mdwcmd##1}}%
+ \itemsep0.25\itemsep}%
+ {\end{description}}
+%
+\makeatletter
+\providecommand{\mdwcmd}[1]{%
+ \expandafter\texttt\expandafter{\string#1}%
+ \mdwcmd@i}
+\def\mdwcmd@i{\futurelet\@let@token\mdwcmd@ii}
+\def\mdwcmd@ii{%
+ \let\@tempa\relax%
+ \ifx\@let@token\bgroup%
+ \def\@tempa##1{\texttt{\char`\{}\textit{##1}\texttt{\char`\}}\mdwcmd@i}%
+ \fi%
+ \ifx\@let@token[%
+ \def\@tempa[##1]{\texttt{[}\textit{##1}\texttt{]}\mdwcmd@i}%
+ \fi%
+ \@tempa%
+}
+\makeatother
+%
+% To use umlauts in a bibliography entry in BibTeX 0.99, we have to
+% use a certain amount of subterfuge...
+\let\umlaut\"
+%
+%%%%%%%%%%%%%%%%
+\begin{document}
+%%%%%%%%%%%%%%%%
+%
+\title{The \LaTeXe\ \TUB{} macros}
+\author{Robin Fairbairns \& TUGboat editors}
+\EDITORnoaddress
+\netaddress{tugboat@tug.org}
+\personalURL{tug.org/TUGboat}
+\maketitle
+
+\section{Introduction}
+
+This is the documentation for the \LaTeXe\ macros to be used by \TUB{}
+authors. The macros represent a development of the earlier
+\clsname{ltugboat} and \clsname{ltugproc} styles that were written for
+use with \LaTeX~2.09; major contributors have been Robin Fairbairns,
+Sebastian Rahtz, Michel Goossens, Nico Poppelier and Johannes Braams.
+Many others have been involved, including Barbara Beeton, Karl Berry,
+Mimi Burbank, and the \LaTeX3 team.
+
+\section{Availability}
+
+The \TUB\ web pages are at:\\\centerline{\url{https://tug.org/TUGboat}}
+They provide \textbf{an article template}, information for authors and
+reviewers, and the complete run of all published \TUB\ issues, among
+other things.
+
+The macros are released for general use, and are distributed via \CTAN{}
+(directory \CTANref{tub-latex}) in the usual \LaTeX{} way as files
+\path|tugboat.dtx| and \path|tugboat.ins|. When the\,\verb|.ins| file
+is processed by \LaTeX{}, the files \path|ltugboat.cls| and
+\path|ltugbib.bst| (for use with articles) and \path|ltugcomn.sty| (a
+cooking pot of perhaps-useful macros, for documentation, etc.)\ are
+produced. (\path|ltugproc.cls| is also produced for compatibility, but
+is no longer used for proceedings or anything else.)
+
+The\,\verb|.dtx| file may itself be processed by \LaTeX{} to
+produce a formatted (somewhat `literate') source listing for those who
+would like more detailed descriptions of the \TUB\ macros.
+
+\section{The general structure of a paper}
+
+The basic idea is to start your \LaTeX\ document with
+\path|\documentclass{ltugboat}|, which defines the appearance of \TUB\
+articles. This uses the file \path|ltugboat.cls| as usual.
+
+Each paper, therefore, is written as a document that may stand on its
+own. It starts with a \cs{documentclass} command, and its body is
+enclosed in a \envname{document} environment. There are some options to
+the document class, described in the next section, but ordinarily the
+author needn't bother with them. The defaults are
+designed for creating proof copies of papers.
+
+The proof output differs from the final production output with respect
+to page numbers and other material. The changes required for final
+production are the responsibility of the \TUB{} editors, and the author
+need not be concerned with them.
+
+\section{Class options: The \clsname{ltugboat} class}
+\label{sec:boat-opts}
+
+The \clsname{ltugboat} class accepts many of the options of the
+\clsname{article} class (it suppresses the font-size selection
+and one/two-side options).
+\begin{optlist}
+\item[draft] Set up for a draft copy of a paper (this is the default
+ setting\Dash the author need not explicitly set it): page numbering
+ starts at a high number, black marks for overfull boxes.
+\item[extralabel] Use the extra label-distinguishing mark in the body
+ of the reference; see section~\ref{sec:biblio}.
+\item[final] Set up for the final copy of a paper: page numbering to
+ come from elsewhere, no cropmarks.
+\item[harvardcite] Specify Harvard-style citation (not
+ recommended in general; see section~\ref{sec:biblio}); see
+ section~\ref{sec:biblio}.
+\item[noextralabel] Don't use the extra label-distinguishing mark in
+ the body of the reference; see section~\ref{sec:biblio}.
+\item[nonumber] Sections are not numbered; section heading
+ layout is to be as in the `plain' \pkgname{tugboat} styles.
+\item[numbersec] Sections, subsections and subsubsections are to be
+ numbered (this is the default setting\Dash the author need not
+ explicitly set it).
+\item[onecolumn] Typeset article in one column.
+\item[preprint] Set up for a preprint.
+\item[rawcite] Explicitly specify the standard \LaTeX\ citation method,
+ which is the default; see section~\ref{sec:biblio}.
+\item[runningfull] Information in both header and footer (default).
+\item[runningminimal] Information in header only.
+\item[runningoff] Information in neither header nor footer.
+\end{optlist}
+
+\noindent Again, normally there is no need to use any document options.
+They are listed here for completeness.
+
+\section{Command syntax}
+\label{sec:syntax}
+
+In general, we have sought simply to keep to the spirit of \LaTeX\ in
+the commands provided by the \TUB\ class (\verb|ltugboat|).
+
+In the few cases that it has proved possible to emulate (what seems to
+a staid old \LaTeX{} programmer, such as the original author here) the gay
+abandon of the syntax of the `plain' \pkgname{tugboat} styles
+\cite{Whitney:TB10-3-378}, we have done so. Nevertheless, on the whole,
+the new \clsname{ltugboat} macros define \LaTeX{} commands and
+environments, or modify the definitions of \LaTeX{} `standard'
+commands. Section~\ref{sec:equiv} lists equivalences between macros
+defined by the `plain' package and those defined by the new package.
+
+\section{Divisions of the paper}
+\label{sec:divs-paper}
+
+Papers in \TUB{} may be subdivided in the normal way of a \LaTeX{}
+article (the classes are defined in terms of \LaTeX{}'s
+\clsname{article} class). Thus the author may use \cs{section},
+\cs{subsection}, \dots, \cs{paragraph} commands (but \cs{part} and
+\cs{subparagraph} from \clsname{article} are suppressed, and
+\cs{chapter}, which doesn't even appear in the parent class, receives
+the same treatment).
+
+Authors may note that the style of ordinary issues of \TUB{} makes
+no distinction between the titles of the divisions; the visual style
+relies on the section numbers to indicate where the divisions lie in
+the hierarchy.
+
+Reference may, however, be made to the `title' of divisions of the
+paper, whether they are numbered or not. The \cs{nameref} command
+(which uses the technique developed for the \textsf{hyperref} package
+\cite{Rahtz:hyperref:1997}) permits such references; for example, the
+present section was introduced by:
+\begin{verbatim}[\small]
+ \section{Divisions of the paper}
+ \label{sec:divs-paper}
+\end{verbatim}
+and the command \verb|\nameref{sec:divs-paper}| produces
+`\nameref{sec:divs-paper}'.
+
+\subsection{Abstracts}
+
+The \clsname{ltugboat} class provides two environments for abstracts,
+\envname{abstract} and \envname{longabstract}. The \envname{abstract}
+environment simply typesets its body as an un-numbered section whose
+title is `Abstract'. The \envname{longabstract} environment typesets its
+body in small text, and separates the abstract from the rest of the
+paper with a decorative line; this is rarely used.
+
+\subsection{Appendices}
+
+A paper may have appendices, which can be expressed in exactly the same
+way as they would be in the \LaTeX{} article class (confusing as that
+may be):
+
+\begin{verbatim}[\small]
+\appendix
+\section{This is appendix A}
+...
+\section{This is appendix B}
+\end{verbatim}
+Which will produce `section' headings similar to:
+\begin{quote}
+\textbf{A\quad This is appendix A}
+\end{quote}
+
+\TUB{} articles may have a small extension to this format using an
+\texttt{appendix} environment:
+
+\begin{verbatim}[\small]
+\begin{appendix}
+\section{This is the first one}
+...
+\end{appendix}
+\end{verbatim}
+which will produce `section' headings similar to:
+\begin{quote}
+\textbf{Appendix A\quad This is the first one}
+\end{quote}
+
+In both cases, the subsections are numbered as normal (i.e., as
+`A.\ensuremath{n}' in normal \TUB{} papers):
+
+\section{Titles, addresses and so on}
+
+The title and author(s) of a paper are quoted using commands that are
+familiar (in syntax, at least) to most \LaTeX{} users; the \cs{title}
+command is exactly that used in the standard \LaTeX{} classes. There is
+also \cs{shortTitle\char`{\meta{your-short-title}\char`}} to define the form
+used in running heads or footers; similarly \cs{shortAuthor}.
+
+The \cs{author} command is used once for each co-author of the paper,
+and for each \cs{author} there should be a \cs{address} command that
+gives a (postal) correspondence address. In addition (wherever
+possible), \TUB{} likes to quote an email address for authors: for this,
+the \cs{netaddress} command is used. Each author may also mention a web
+page, using a \cs{personalURL} command, and an \acro{ORCID} (from
+\url{orcid.org}), using \cs{ORCID}.
+
+For example, the present paper has (approximately) this at its start:
+
+\begin{verbatim}[\small]
+\title{The \LaTeXe\ \TUB{} Macros}
+\author{TUGboat editors}
+\address{\TeX\ Users Group}
+\netaddress{tugboat@tug.org}
+\personalURL{https://tug.org/TUGboat}
+\maketitle
+\end{verbatim}
+
+Lines in the title information can get quite long.
+If the information being given is
+to be typeset as ordinary text (as in the case of the \cs{address}
+line above), it can be `wrapped' perfectly happily, as in normal text.
+If one of the verbatim items (\cs{netaddress} or \cs{personalURL}
+commands) is going to be too wide for the column, what is the author
+to do? (Abbreviating the text, as in the \cs{personalURL} above, is
+\emph{not} usually an acceptable option!) Unfortunately, the \verb|%|
+sign is an entirely acceptable element of both email addresses and
+\acro{URL}s, so that the normal `fall-back' isn't available.
+Therefore, the classes typeset these electronic addresses in an
+environment where some of the characters (notably `\verb|.|' and
+`\verb|/|') are treated as word-divisions for the purposes of laying
+out the line.
+
+If the paper is the result of more than one author's labours, a sequence of
+\cs{author}, \cs{address}, \cs{netaddress} and \cs{personalURL}
+commands may be given, as in the following, which comes from a paper
+given at \tug'95 (abbreviated):
+
+\begin{verbatim}[\small]
+\author{Michel Goossens}
+\address{CN Division, CERN\\
+ ...}
+\netaddress{...}
+
+\author{Sebastian Rahtz}
+\address{Elsevier Science Ltd\\
+ ...}
+\netaddress{...}
+...
+\end{verbatim}
+
+The class files will take care of arranging author names and addresses
+between the \cs{maketitle} and (possibly) \cs{makesignature} commands.
+
+\subsection{Compilation articles}
+
+Compilation articles are written as a set of contributed parts under the
+general editorship of the author(s) of the article. The author of the
+article is presented (using \cs{author}, etc.)\ in the
+usual way, and writes the introductory text. Each contributors' part
+then follows. The contributor's name is quoted in the \cs{contributor}
+command, which is an analogue of the \cs{author} command; contributors'
+\cs{address}, \cs{netaddress} or \cs{personalURL}. The \cs{contributor}
+command opens a group in which the contribution appears, and the
+contributor's signature (produced with a \cs{makesignature} command)
+closes the group. The general scheme looks like:
+\begin{verbatim}[\small\makeescape\|\makebgroup\[\makeegroup\]]
+\title{Example compilation article}
+\author{Robin Fairbairns}
+\address{University of Cambridge ...}
+\netaddress{...}
+ ... |textsl[introductory text] ...
+\makesignature
+
+\contributor{Betsy the Dog}
+\address{Romsey Town, Cambridge}
+ ... |textsl[Betsy's contribution] ...
+...
+\makesignature ...
+\end{verbatim}
+
+\section{Verbatim text}
+\label{sec:verbatim}
+
+For inline verbatim text, authors should ordinarily employ the
+facilities of \LaTeX{} itself, that is, the \cs{verb} macro. This macro, of
+course, is highly restricted as to its usage\Dash primarily, it may
+not appear in the argument of \emph{any} other macro, even
+\cs{footnote}.
+
+For displayed verbatim text, the classes add a small increment to
+the functionality of \LaTeX{}'s \envname{verbatim} environment, by
+introducing an optional argument. The optional argument may contain
+commands to be executed before starting the verbatim text; the set of
+commands which have useful effect is strictly limited, but the
+following are common:
+\begin{itemize}
+\item Font size selection commands: for example, all the display
+ verbatim in the present paper starts with
+ \verb|\begin{verbatim}[\small]|.
+
+\item The command \cs{ruled}, which is available \emph{only} in
+ \envname{verbatim}'s optional argument, and specifies that a
+ column-wide rule should be drawn before and after the verbatim
+ text. (This is not the recommended style in general, but it's
+ available for when it helps.)
+
+\item The command \cs{makevmeta}, also available only in
+ \envname{verbatim}'s optional argument, and makes the construct
+ \verb|!<...>| inside verbatim execute \verb|\meta{...}|. For example,
+\begin{verbatim}[\small]
+\begin{verbatim}[\small\makevmeta]
+The !<duration> is long ...
+\end{verbatim}
+produces:
+\begin{verbatim}[\small\makevmeta]
+The !<duration> is long ...
+\end{verbatim}
+ The \verb|!| character is made a general escape character by
+ \cs{makevmeta}, but \verb|<>| are not made grouping characters.
+
+\item More generally, one of the \cs{make*} commands,\footnote{\cs{makeescape},
+ \cs{makebgroup}, \dots, \cs{makecomment}; used, for example, as
+ \cs{makeescape}\cs{|}.} which change the category code of
+ characters within the verbatim text. This is (of course) a facility
+ that should only be used with the utmost caution.
+
+\end{itemize}
+Two caveats about these optional arguments:
+\begin{itemize}
+\item The search for the optional argument can be confused by the
+ appearance of a \verb|[| character as the first character of the displayed
+ verbatim. An author who wishes to start verbatim text with a
+ \verb|[| character should provide an empty optional argument (i.e.,
+ `\verb|[]|') to the \envname{verbatim} environment.
+\item The \TUB\ facility is lost when any package is loaded that also
+ defines the \verb|verbatim| environment, as discussed next.
+\end{itemize}
+
+Authors may wish to use a more featureful verbatim package, such as such
+as \pkgname{verbatim}~\cite{Schoepf:verbatim:1996},
+\pkgname{listings}~\cite{pkg:listings}, or
+\pkgname{fancyvrb}~\cite{pkg:fancyvrb}. This is ok; it just means the
+\TUB\ optional-argument feature is not available.
+
+If you use the \pkgname{listings} package, please specify:
+\begin{verbatim}
+\lstset{columns=flexible}
+\end{verbatim}
+The other values for the \verb|columns| option don't work well in
+\TUB. Also, if you use \cs{small} for displayed verbatim, please reset
+inline verbatim to the normal text size:
+\begin{verbatim}[\small]
+\lstset{columns=flexible,
+ basicstyle=\ttfamily\small}
+\lstdefinestyle{inline}
+ {basicstyle=\ttfamily\normalsize}
+\end{verbatim}
+
+\section{Floating inserts}
+
+The classes do not make any change to \LaTeX{}'s built-in provision
+for floating inserts, so that authors may generate figures and tables
+just as they would in any `normal' \LaTeX{} document. Figure and
+table captions, and labels referring to them, are also substantially
+untouched.
+
+However, since both classes typeset in two columns, authors must
+distinguish between the \envname{figure} and \envname{table} environments
+(which produce floats that are the same width as the column) and the
+\envname{figure*} and \envname{table*} (which produce floats that are the same
+width as the page).
+
+%\begin{itemize}
+%\item figures and tables as normal
+%\item captions and labels work whatever (i.e., no restriction on
+% numbering)
+%\item twocolumn setting implies distinction between \envname{figure} and
+% \envname{figure*}
+%\end{itemize}
+
+\section{Special-purpose typesetting}
+
+The classes define a rather large set of commands for special-purpose
+typesetting. Some of them are available for historical reasons only,
+and many are only useful in somewhat restricted circumstances. For
+this reason, the present paper only outlines a representative, small
+set of the macros.
+
+\subsection{Acronyms and logos}
+
+The classes provide macros that produce `correct' representations of a
+large number of acronyms and logos; a small representative selection is
+shown in figure~\ref{fig:acro-logo}. The sample documents at
+\url{tug.org/TUGboat/location.html} have a more complete list,
+and of course the class sources are the ultimate reference.
+\begin{figure}[htbp!]
+ \begin{center}
+ \begin{tabular}{@{}ll@{}}
+ \small\textsl{\textsf{Macro}}&\small\textsl{\textsf{Output}}\\
+ \midrule
+ \verb|\ConTeXt| & \ConTeXt \\
+ \verb|\Cplusplus| & \Cplusplus \\
+ \verb|\CTAN| & \CTAN \\
+ \verb|\eTex| & \eTeX \\
+ \verb|\FAQ| & \FAQ \\
+ \verb|\HTML| & \HTML \\
+ \verb|\ISBN| & \ISBN \\
+ \verb|\KOMAScript| & \KOMAScript \\
+ \verb|\LaTeXe| & \LaTeXe \\
+ \verb|\MacOSX| & \MacOSX \\
+ \verb|\MathML| & \MathML \\
+ \verb|\MF| & \MF \\
+ \verb|\MP| & \MP \\
+ \verb|\OMEGA| & \OMEGA \\
+ \verb|\PDF| & \PDF \\
+ \verb|\SGML| & \SGML \\
+ \verb|\TUB| & \TUB \\
+ \verb|\TUG| & \TUG \\
+ \verb|\tug| & \tug \\
+ \verb|\XML| & \XML \\
+ \end{tabular}
+ \end{center}
+ \caption{A few of the provided acronyms and logos}
+ \label{fig:acro-logo}
+\end{figure}
+
+Authors are especially urged to note the \cs{acro} command, which is
+defined in the classes. The visual appearance of all-caps sequences
+among normal text is rather unpleasing in Computer Modern,
+unfortunately. Therefore, the \cs{acro} command typesets its argument
+one point size smaller than the surrounding text: compare `\acro{DANTE}'
+(\verb|\acro{DANTE}|) with `DANTE'\@. Many of the provided macros merely
+generate calls to \cs{acro}; two examples, \cs{CTAN} and \cs{tug} of the
+list in figure~\ref{fig:acro-logo} have already been used in the present
+paper.
+
+\subsection{Other special typesetting}
+
+A small list of special typesetting commands follows: a large set of
+such commands is defined in the classes, but the list covers most of
+the `everyday' ones.
+\begin{cmdlist}\raggedright
+\item[\Dash] Typeset an em-dash, ignoring preceding and following space,
+ surrounded by thin spaces, only breakable \emph{after} the dash; this
+ is the preferred method of specifying a dash in running text.
+\item[\cs{cmd}] Typeset a control sequence name:\\
+ \verb|\cs{fred}| produces \cs{fred}.
+\item[\env{environ}] Typeset the command to begin an environment:
+ \verb|\env{fred}| produces \env{fred}.
+\item[\meta{var}] Typeset meta-syntactic text:\\
+ \verb|\meta{fred}| produces \meta{fred}.
+\item[\tubbraced{text}] Typeset typewriter text in typewriter
+ braces: \verb|\tubbraced{fred}| produces \tubbraced{fred}.
+\item[\nth{n}] Typeset an ordinal number; \verb|\nth{1}| is
+ set as \nth{1}, \verb|\nth{27}| is set as \nth{27}, and so on.
+%\item[\sfrac{num}{denom}] Typeset a fraction to match running text;
+% for example \verb|\sfrac{3}{4}| is set as \sfrac{3}{4}\,.
+\end{cmdlist}
+
+\section{Use of packages}
+
+In general, authors can use non-standard packages in their papers.
+However, the paper does need to be processable on the \TUB{} production
+computers (running current \TeX\ Live). A sensible mechanism for
+submitting out-of-the-ordinary packages (as for paper-specific
+bibliographies) is by use of the \envname{filecontents} environment.
+
+In general, packages currently on \CTAN, and known to work with
+\emph{current} \LaTeX{} are unlikely to give problems. In particular,
+the team is happy to accept papers using packages that are supported by
+members of the \LaTeX3 team,\footnote{%
+ Those in the \LaTeX{} base distribution, or one of those in the
+ \CTANref{packages} sub-tree on \CTAN.} subject to the warning already
+mentioned (section~\ref{sec:verbatim}): that use of the standard
+\pkgname{verbatim} package eliminates the special \envname{verbatim}
+facilities provided by the \TUB\ classes.
+
+\tug{} has a policy that macro packages described in \TUB{} should be
+available for readers to use. Since typing macros from printed
+sources is such an error-prone undertaking, authors of publicly
+available packages are urged to submit their macros to the \CTAN{}
+archives. If a package is only available under restricted terms,
+authors are urged to make this fact clear when first submitting an
+article to the editor.
+
+At present, the list of canonically recommended packages consists of
+only two, \path|mflogo.sty| \cite{Vieth:mflogo:1995} and \path|url.sty|
+\cite{Arseneau:url:1996}.
+
+Both classes will load the \pkgname{mflogo} package if it is present on the
+author's system; if the package is not present, the classes will
+emulate its more important features; the package defines \MF{} and
+\MP{} logos using recent versions of Knuth's \verb|logo10| font family.
+
+The \pkgname{url} package is useful when one is typesetting significant
+numbers of file names, network addresses or \acro{URL}s; it is being
+used in the present paper (not least in the bibliography). Speaking of
+urls, nowadays we generally omit a leading \texttt{http://} or
+\texttt{https://}.
+
+Although not necessarily recommended in all cases, many additional
+packages are commonly used. To mention a few: \texttt{microtype} can
+help reduce overfull boxes; sometimes it may be preferable to use the
+Latin Modern fonts via \texttt{lmodern}; and \texttt{hyperref} allows
+for many internal links and other features.
+
+\section{Bibliography}
+\label{sec:biblio}
+
+In short: our basic recommendation for handling bibliographies is to use
+\BibTeX\ and the \pkgname{tugboat} bibliography style. No document
+options are needed or recommended. All that is required in the article
+source (as shown in the template available from
+\url{tug.org/TUGboat}) is the following:
+
+\begin{verbatim}[\small]
+\bibliographystyle{tugboat}
+\bibliography{yourbibfile}
+\end{verbatim}
+
+If you don't have \verb|tugboat.bst|, which was released in 2018, it's
+fine to use \pkgname{plain} or \pkgname{abbrv}. If you do have it,
+though, you may enjoy the following small but useful features:
+
+\begin{itemize}
+\item It is based on \pkgname{abbrvurl.bst} (see \url{ctan.org/pkg/urlbst}),
+
+\item thus supports \textsf{url} and \textsf{doi} fields, among others.
+
+\item The \textsf{url} field is ignored if either the \textsf{doi} or
+\textsf{howpublished} field is present, since in practice we observe
+that people put the same information in all those fields, and we don't
+want to use up space typesetting redundant information.
+
+\item Has even more abbreviations than \textsf{abbrv}, including
+printing only two author names (plus ``et~al\@.'') if there are more
+than four authors (thanks to Mico Loretan).
+
+\item Defines an \textsf{@online} entry type as an alias for \textsf{@misc}.
+
+\item For completeness only: \verb|tugboat.bst| provides ``secret''
+fields \textsf{newpage} to force a page break after the current item,
+and \textsf{urlnewline} to force a line break before the \textsf{url}
+value. We've found that these presentation tweaks are often necessary
+for the final typeset output. Authors need not worry about them.
+
+\end{itemize}
+
+If you use \BibTeX, feel free to take advantage of the accumulated
+bibliography of \TUB{} itself (\url{info/tugboat.bib} on \CTAN), and the
+various compilations by Nelson Beebe in that same directory.
+
+Bibliographies provide further problems because they're notoriously
+difficult to typeset at the best of times. \LaTeX{} sets \cs{sloppy}
+when typesetting the bibliography, but this often leads to unpleasant
+output in the narrow columns typical of \TUB{}. The author can control
+the typesetting using the command \cs{SetBibJustification}. The classes
+set \cs{sloppy}, by default (just like \LaTeX{}), but the author may
+(for example) say:
+\begin{verbatim}
+ \SetBibJustification{\raggedright}
+\end{verbatim}
+as the present article does, to achieve somewhat better results.
+
+A last note for bibliographies: for references to other issues of \TUB,
+please use the format \textsl{volno:issno}, e.g., ``\TUB\ 32:1'' for
+volume~32, number~1.
+
+\section{Non-recommended bibliography facilities}
+
+The preceding gives the bibliography recommendations for current \TUB\
+article. If, for whatever reason, you cannot follow the recommendation,
+this section is about some of the myriad historical and other
+possibilities.
+
+Notwithstanding the general recommendation for the \pkgname{tugboat}
+(falling back to \pkgname{plain}) \BibTeX\ style, \TUB's Harvard
+citation support may be selected by specifying \optname{harvardcite} as
+an option of the \cs{documentclass} command.\footnote{%
+ The macros used derive rather directly from the `harvard' styles
+ written by Glenn Paulley and now maintained by Peter Williams; the
+ \BibTeX{} style derives from one developed by Patrick Daly.}
+If your article demands Harvard-style citations, you may prefer to load
+\pkgname{natbib} or similar instead of using \TUB's facilities; that's
+ok.
+
+The basic citation format is `author(s), year', but the macros are
+capable of many variations: this in turn places somewhat of a load on
+the author to use the correct citation macro. The macros available are
+shown in figure~\ref{fig:citation-macros}; the figure assumes an entry
+in the bibliography with authors Tom, Dick, and~Harry, and with a 1990
+date.
+
+\begin{figure}[htbp!]
+ \begin{center}
+ \leavevmode
+ \begin{tabular}{@{}ll@{}}% @{ $\rightarrow$ } between columns removed
+ \small\textsf{\textsl{Macro}} &\small\textsf{\textsl{Output}}\\
+ \midrule
+ \verb|\cite{key}| & (Tom, Dick, and Harry, 1990)\\
+ \verb|\citeA{key}| & (Tom, Dick, and Harry)\\
+ \verb|\citeNP{key}| & Tom, Dick, and Harry, 1990\\
+ \verb|\citeANP{key}| & Tom, Dick, and Harry\\
+ \verb|\citeN{key}| & Tom, Dick, and Harry (1990)\\
+ \verb|\shortcite{key}| & (Tom et al., 1990)\\
+ & [also has \texttt{A} and \texttt{NP}
+ variants]\\
+ \verb|\citeyear{key}| & (1990)\\
+ & [also has an \texttt{NP} variant]
+ \end{tabular}
+ \end{center}
+ \caption{The range of citations in \optname{harvard} style}
+ \label{fig:citation-macros}
+\end{figure}
+
+Note that, if Tom, Dick, and Harry are a prolific team, there can
+easily be more than one reference to their work in one year. In such
+a case, the citations will be (Tom, Dick, and Harry, 1990a), (Tom,
+Dick, and Harry, 1990b), and so on. These extra `a', `b', etc., tags
+may also appear in the references section of the paper, attached to
+the year recorded for the reference: whether this indeed happens is
+controlled by the \optname{extralabel} and \optname{noextralabel} class
+options. The default state (option \optname{extralabel}) attaches the
+extra characters.
+
+As for \BibLaTeX, we don't recommend it for \TUB. If you feel you must
+use it, that is ok, but we may still change it to using the default
+\LaTeX\ and \BibTeX\ facilities in processing for publication if the
+output from \BibLaTeX\ is problematic, as we have often seen it to be.
+
+
+
+\section{Equivalences between the `plain' and \LaTeX{} \TUB\ packages}
+\label{sec:equiv}
+
+A good proportion of the commands in the `plain' packages also appear
+(with the same meaning) in the \LaTeX{} classes.
+Figure~\ref{fig:plain-equiv} gives a brief summary of where the macros
+differ significantly.
+
+\begin{figure}[htbp]
+ \begin{center}
+ \leavevmode
+ \begin{tabular}{@{}ll@{}}
+ \small\textsf{Plain macro} & \small\textsf{\LaTeX{} macro} \\
+ \midrule
+ \cs{head} & \cs{section} \\
+ \cs{subhead} & \cs{subsection} \\
+ \cs{subsubhead} & \cs{subsubsection} \\
+ \cs{list} & \envname{itemize}, \envname{enumerate}, etc., \\
+ & environments \\
+ \cs{verbatim} & \envname{verbatim} or \cs{verb} \\
+ \cs{figure} & \envname{figure} or \envname{figure*} environments \\
+ \end{tabular}
+ \end{center}
+ \caption{Equivalences between \pkgname{plain} and \LaTeX{} \TUB\ macros}
+ \label{fig:plain-equiv}
+\end{figure}
+
+\LaTeX{} itself makes comprehensive provision for lists; the \TUB{}
+classes make no attempt to emulate the list facilities of the `plain'
+macros.
+
+The `plain' styles' provision for verbatim text is also somewhat
+different from the \LaTeX{} approach; the \TUB{} classes offer a small
+subset of the extra facilities that the `plain' styles provide; for more
+elaborate facilities, the user is referred to the \pkgname{verbatim},
+\pkgname{listings}, and \pkgname{fancyvrb} packages (see
+section~\ref{sec:verbatim}).
+
+Of course, the syntax of commands given to the \LaTeX{} classes is
+different (as discussed in section~\ref{sec:syntax}); arguments are
+(almost always) enclosed in braces, and neither of the forms of
+argument provision promulgated by the `plain' macros
+(\cs{macro}\meta{argument}\linebreak[0]\cs{endmacro} and
+\cs{macro * }\meta{argument}\verb| *|) are provided by the \LaTeX{}
+classes.
+
+\SetBibJustification{\raggedright}
+\bibliographystyle{tugboat}
+\bibliography{tubguide}
+
+\advance\signaturewidth by 8pt
+\makesignature
+
+\end{document}