From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- macros/latex/contrib/tugboat/ltubguid.ltx | 868 ++++++++++++++++++++++++++++++ 1 file changed, 868 insertions(+) create mode 100644 macros/latex/contrib/tugboat/ltubguid.ltx (limited to 'macros/latex/contrib/tugboat/ltubguid.ltx') 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 ! is long ... +\end{verbatim} +produces: +\begin{verbatim}[\small\makevmeta] +The ! 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} -- cgit v1.2.3