diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/tugboat/ltubguid.ltx')
| -rw-r--r-- | Master/texmf-dist/doc/latex/tugboat/ltubguid.ltx | 992 |
1 files changed, 992 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/tugboat/ltubguid.ltx b/Master/texmf-dist/doc/latex/tugboat/ltubguid.ltx new file mode 100644 index 00000000000..afc85ad0165 --- /dev/null +++ b/Master/texmf-dist/doc/latex/tugboat/ltubguid.ltx @@ -0,0 +1,992 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% 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{Arseneau:url:1996, + author = {Donald Arseneau}, + title = {The {\textsf{url}} package}, + year = {1996}, + howpublished = {Available from {\CTAN}, {\CTANref{url}}} +} + +@Article{Baxter:TB15-3-331, + author = {William Erik Baxter}, + title = {{{An object-oriented programming system in {\TeX}}}}, + journal = {{\TUB}}, + year = {1994}, + month = {September}, + volume = {15}, + number = {3}, + pages = {331--338} +} + +@Misc{Duggan:moreverb:1996, + author = {Angus Duggan and Rainer Sch{\umlaut{o}}pf and Victor Eijkhout and + Robin Fairbairns}, + title = {The {\textsf{moreverb}} package}, + year = {1997}, + howpublished = {Available from {\CTAN}, {\CTANref{moreverb}}} +} + +@Misc{Rahtz:hyperref:1997, + author = {Sebastian Rahtz}, + title = {The {\textsf{hyperref}} system}, + year = 1997, + howpublished = {Available from {\CTAN}, {\CTANref{hyperref}}} +} + +@Book{Lamport:1994, + author = {Leslie Lamport}, + title = {{\LaTeX}, a Document Preparation System}, + edition = {\nth{2}}, + year = {1994}, + publisher = {Addison-Wesley} +} + +@Article{Ogawa:TB15-3-325, + author = {Arthur Ogawa}, + title = {{{Object-oriented programming, descriptive markup, and {\TeX}}}}, + journal = {{\TUB}}, + year = {1994}, + month = {September}, + volume = {15}, + number = {3}, + pages = {325--330} +} + +@Article{Rowley:TB15-1-63, + author = {Chris Rowley}, + title = {{{{\LaTeXe} update, dateline: 31 January 1994}}}, + journal = {{\TUB}}, + year = {1994}, + month = {March}, + volume = {15}, + number = {1}, + pages = {63} +} + +@Misc{Schoepf:verbatim:1996, + author = {Rainer Sch{\umlaut{o}}pf}, + title = {The {\textsf{verbatim}} package}, + year = {1996}, + month = {June}, + howpublished = {Part of the \textsf{tools} bundle, available from {\CTAN}, + {\CTANref{tools}}} +} + +@Article{Swift:TB16-3-269, + author = {Matt Swift}, + title = {Modularity in {\LaTeX}}, + journal = {{\TUB}}, + year = {1995}, + volume = {16}, + number = {3}, + pages = {269--275} +} + +@Misc{Vieth:mflogo:1995, + author = {Ulrik Vieth}, + title = {The {\textsf{mflogo}} package}, + year = {1995}, + howpublished = {Available from {\CTAN}, {\CTANref{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} +} + +\end{filecontents} +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% ctandir.sty -- an experimental style file to go with Donald +% Arseneau's url.sty to perform some of the functions that we use the +% \FAQverb stuff in the UK TUG FAQ for +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +\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 +\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} +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +\listfiles +\setcounter{errorcontextlines}{999} +\documentclass[harvardcite]{ltugboat} +\usepackage{ctandir} +\IfFileExists{booktabs.sty}% + {\usepackage{booktabs}}% + {\let\midrule\hline} +% +% only tell me important overfulls, please +\hfuzz=2pt +% +% ahem, why not? +\hyphenation{col-umns} +% +% define CTAN addresses using the commands of the |ctandir| package +\CTANdirectory{bibextract}{biblio/bibtex/utils/bibextract} +\CTANdirectory{mflogo}{macros/latex/contrib/mflogo} +\CTANdirectory{moreverb}{macros/latex/contrib/moreverb} +\CTANdirectory{packages}{macros/latex/required} +\CTANdirectory{tools}{macros/latex/required/tools} +\CTANdirectory{tub-latex}{macros/latex/contrib/tugboat} +\CTANdirectory{hyperref}{macros/latex/contrib/hyperref} +% +\CTANfile{cite}{macros/latex/contrib/cite/cite.sty} +\CTANfile{tub-biblio}{digests/tugboat/biblio/tugboat.bib} +\CTANfile{url}{macros/latex/contrib/misc/url.sty} +% +% commands that would be defined by changebar if we were using it: +\providecommand\cbstart{} +\providecommand\cbend{} +% +% this isn't really all that much of a `proof' copy +\NoBlackBoxes +% +% ***** 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 +% +% for raggedy-footnotes (necessary for CTAN references, I find) +\newcommand\raggedfoot{\rightskip=\raggedskip plus\raggedstretch\relax} +% +% 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 New (\LaTeXe) \TUB{} Macros} +\author{Robin Fairbairns} +\address{University of Cambridge Computer Laboratory\\ + William Gates Building\\ + J J Thomson Avenue,\\ + Cambridge CB3 0FD,\\ + UK} +\netaddress{rf@cl.cam.ac.uk} +\personalURL{http://www.cl.cam.ac.uk/users/rf/robin.html} +\maketitle + +\section{Introduction} + +This note reports on a new set of macros for use 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. The +development was started by others than I, notably Sebastian Rahtz, +Michel Goossens, Nico Poppelier and Johannes Braams; I have been +assisted in my work both directly and indirectly by many others, +including Barbara Beeton, Mimi Burbank and (of course) the \LaTeX3 +team. + +The ultimate aim of the work is to provide a single production +environment for the whole of \TUB{}. That aim has not (yet) been +achieved, though it is still believed to be achievable for a +significant proportion of papers.\footnote{\TUB{} will continue to +accept papers written using the `plain' macros; it's probably +fanciful to hope that \emph{every} paper can be moulded into use +within \LaTeX.} + +\section{Availability} + +\begin{sloppypar} + The macros are released for general use, and are distributed via + \CTAN{}\footnote{\raggedfoot From 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|, \path|ltugproc.cls| and \path|ltugbib.bst| (for + ordinary production work) and \path|ltugcomn.sty| (a cooking pot of + useful macros, for documentation, etc.)\ are produced. The\,\verb|.dtx| + file may itself be processed by \LaTeX{} to produce a formatted + (somewhat `literate') source listing for those who feel they need + more detailed description of the macros than is offered in the + present note. +\end{sloppypar} + +\section{The general structure of a paper} + +The author need not understand the details of the production of +\TUB{}\Dash her business is to produce the text that the editor is to +mould into the body of an issue. + +However, any modern author wants to be able to view the progress of +her efforts; for this, she needs to use the \TUB{} class +\path|ltugboat.cls|\Dash it defines the way an article in a normal issue of +\TUB{} will appear, and is therefore a useful aid. + +Similarly, one submitting a paper for presentation at an annual \tug{} +conference may use the \path|ltugproc.cls|, which will set the paper as it +should appear in a proceedings issue of \TUB{}. + +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. Each of the document +classes specifies a set of options, described in the next two +subsections (\ref{sec:boat-opts} and~\ref{sec:proc-opts}). In the +ordinary course of events the author needn't bother with any of these +options, since the defaults are designed for creating proof copies of +papers. + +Since the author typesets her paper in a `proof mode', the paper's +published appearance will differ from its appearance at the time of +submission. The changes required in this process are the +responsibility of the \TUB{} production team, and the author need not +be concerned with them. + +\subsection{Class options: the \clsname{ltugboat} class} +\label{sec:boat-opts} + +The \clsname{ltugboat} class accepts all the options of the +\clsname{article} class (though it suppresses the font-size selection, +one/two-side and one/two-column 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 + to start at 1001, black marks for overfull boxes, and no + registration marks. +\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 black marks, and registration marks to be + used. +\item[harvardcite] Specify Harvard-style citation; 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 to be 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[preprint] Set up for a preprint. + +\item[rawcite] Specify default (unnumbered) citation; see + section~\ref{sec:biblio}. +\end{optlist} + +\subsection{Class options: the \clsname{ltugproc} class} +\label{sec:proc-opts} + +The \clsname{ltugproc} class accepts all of the options allowed with +\clsname{ltugboat}. In addition, it accepts an option that specifies +the year of the conference for which the paper is submitted. For +example, the conference for 2004 would be specified by option +% +%% % although this paper will be published in 1996, it may be reprinted +%% % again in the future, so let's calculate `this year' on the fly +%% \newcount\y +%% \y\year +%% \divide\y100 +%% \multiply\y100 +%% \advance\y-\year +%% \y-\y +% +% from 2000 on, the option is just the year +\optname{tug\number\year}. Such an option may be necessary if the +(detailed) type design of papers for the year's proceedings issue is +changed by the year's editor. Unless ``instructions to authors'' +say otherwise, authors should not specify such an option, and +\clsname{ltugproc} will choose an appropriate default. + +The class reads a configuration file +\path|ltugproc.cfg|, in which you may specify the year by a command of +the form: +\begin{verbatim}[\small] + \newcommand{\tugProcYear}{97} +\end{verbatim} + +The class deals with two-digit year selections for conferences up to +2069 (which date was chosen entirely at random, uninfluenced, of +course, by the Unix\texttrademark Epoch\dots); however, the user +should not feel constrained to write such confusing dates since +\clsname{ltugproc} will cope with the full year number (4 digits, for +quite a while yet). + +\section{Command syntax} +\label{sec:syntax} + +We would have liked to offer perfectly uniform syntax for people to +use when preparing their papers. Unfortunately, uniform syntax is not +available with any widely-available set of macros (though see, for +example, the discussions in \citeNP{Ogawa:TB15-3-325}, +\citeNP{Baxter:TB15-3-331}, and \citeNP{Swift:TB16-3-269}). In the +circumstances, we have sought simply to keep to the spirit of +Lamport's \citeyear{Lamport:1994}, as modified\footnote{The cited + edition of Lamport's book documents the modified version of \LaTeX{}, + but it's worth emphasising that we use the modified version as the + reference.} by the \LaTeXe{} work (see, for example, +\citeNP{Rowley:TB15-1-63}). + +In the few cases that it has proved possible to emulate (what seems to +a staid old \LaTeX{} programmer, such as the present author) the gay +abandon of the syntax of the `plain' \pkgname{tugboat} styles +\cite{Whitney:TB10-3-378}, we have done. Nevertheless, on the whole, +the new \clsname{ltugboat} macros simply 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. + +The `down' side of this decision is, of course, the `welter of +\LaTeX{} braces' that Barbara Beeton has been heard to complain of in +production team discussions. One has to hope that the (near) +uniformity of syntax offers those who think like Barbara some small +recompense! + +\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 should 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. As a result, the un-numbered `\verb|*|' forms of the +\cs{section}, etc., commands, are inappropriate. The +\clsname{ltugboat} class therefore warns the author who (possibly +inadvertently) uses one of these forms. (The author who wishes to use +un-numbered sections throughout her paper may use the +\optname{nonumber} class option (see~\ref{sec:boat-opts}). + +By contrast, whether or not sections are numbered in a conference +proceedings issues of \TUB{} is a matter of that year's editor's +choice (in collaboration with the \TUB{} team). If sections are not +to be numbered, the use of `\texttt{*}' forms is inappropriate, and the +class equally warns the author. Since the sections don't have +numbers, references to section numbers don't work; they therefore +(once they're resolved) warn the author of potential problems. + +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 classes make provision for abstracts, but the provision is +different for the two classes. + +The \clsname{ltugboat} class provides two environments, \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. + +The \clsname{ltugproc} class typesets abstracts as part of the title +of the paper, below the names and addresses of the authors, but before +the main body of the paper. Therefore, for proceedings articles, the +\envname{abstract} environment must appear in the source of the paper +\emph{before} the \cs{maketitle} command (it may even appear before +\verb"\begin{document}", if the author so chooses). + +\subsection{Appendices} + +A paper may have appendices, which are expressed in exactly the same +way as they would be in \LaTeX{} article class: + +\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: this +extension was originally developed for proceedings issues, but is also +available in normal issues: + +\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, and not at all in +proceedings classes). + +\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. + +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. Finally, each +author may advertise a `home' Web page, using a \cs{personalURL} command. + +For example, the present paper has at its start: + +\begin{verbatim}[\small] +\title{The New (\LaTeXe) \TUB{} Macros} +\author{Robin Fairbairns} +\address{University of Cambridge + Computer Laboratory\\ + Pembroke Street,\\ + Cambridge, CB2 3QG,\\ + UK} +\netaddress{rf@cl.cam.ac.uk} +\personalURL{http://www.cl.cam.ac.uk/...} +\maketitle +\end{verbatim} + +Since this paper is prepared for a normal issue of \TUB{} and +therefore uses the \clsname{ltugboat} class, the \cs{maketitle} merely +typesets the title of the paper and the author's name. The +address(es) are typeset at the end of the paper where the author gives +a \cs{makesignature} command. + +The \clsname{ltugproc} class typesets all the information about the +author at the head of the paper, when the \cs{maketitle} is given; +this class disallows the \cs{makesignature} command. + +Note that the author had a problem typesetting the above example +verbatim: the lines are too 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. This is visible in the case of my personal \acro{URL}, +in the signature block at the end of the present paper. + +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 (slightly edited): + +\begin{verbatim}[\small] +\author{Michel Goossens} +\address{CN Division, CERN\\ + ...} +\netaddress{...} + +\author{Sebastian Rahtz} +\address{Elsevier Science Ltd\\ + ...} +\netaddress{...} + +\author{Robin Fairbairns} +\address{University of Cambridge + Computer Laboratory\\ + ...} +\netaddress{...} +\personalURL{...} +\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} + +\begin{sloppypar} + Compilation articles are built from a set of contributed parts, and + are under the general (sub-)\penalty0\relax\hskip0pt plus0pt minus0pt\relax + editorship of the author\footnote{Or authors: there's no reason in + particular that compilation articles should not be put together + more than one person} of the article. The author of the article + is presented (using \cs{author} and suchlike commands) 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: +\end{sloppypar} +\begin{verbatim}[\small\makeescape\|\makebgroup\[\makeegroup\]] +\title{Example compilation article} +\author{Robin Fairbairns} +\address{University of Cambridge ...} +\netaddress{...} + ... + |emph[introductory text] + ... +\makesignature + +\contributor{Betsy the Dog} +\address{Romsey Town, Cambridge} + ... + |emph[Betsy's contribution] + ... +\makesignature + +... +\end{verbatim} + +\section{Verbatim text} +\label{sec:verbatim} + +The classes do not at present provide the same wide range of +facilities as the `plain' \pkgname{tugboat} style +\cite{Whitney:TB10-3-378}; the author had hoped to `borrow' facilities +from a package which is believed to be in development, but in the +event that package has not materialised. + +For in-line verbatim text, authors should ordinarily employ the +facilities of \LaTeX{} itself (the \cs{verb} macro). This macro, of +course, is highly restricted as to its usage (primarily, that it may +not appear in the argument of \emph{any} other macro, even +\cs{footnote}). + +For `display verbatim' (to employ the term used by +\citeANP{Whitney:TB10-3-378}), 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 commonly used: +\begin{itemize} +\itemsep=0.2\itemsep +\item Font size selection commands: for example, all the display + verbatim in the present paper starts with: + + {\small\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 +\item 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, but it can, for + example, be employed to provide interesting effects by knowledgeable + authors. +\end{itemize} +Two caveats about the use of this facility should be noted: +\begin{itemize} +\itemsep=0.2\itemsep +\item The search for the optional argument can be confused by the + appearance of a \verb|[| character as the first of the displayed + verbatim. An author who wishes to start verbatim text with a + \verb|[| character should provide an empty optional argument (i.e., + simply `\verb|[]|') to the \envname{verbatim} environment. +\item The facility is lost when certain packages are loaded. An + example is the \pkgname{verbatim} package + \cite{Schoepf:verbatim:1996}, which redefines the \envname{verbatim} + environment in its entirety. Of course, any package that loads + \pkgname{verbatim} (such as \pkgname{moreverb}, + \shortciteNP{Duggan:moreverb:1996}) will necessarily have the same + effect. (It should be noted that \pkgname{verbatim} and + \pkgname{moreverb} provide some of the facilities that are available + in the `plain' \pkgname{tugboat} styles, so that an author could + reasonably be tempted to use them. There is no objection in + principle to authors using these packages.) +\end{itemize} + +\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}. +\begin{figure}[htbp!] + \begin{center} + \begin{tabular}{@{}ll@{}} + \small\textsl{\textsf{Macro}}&\small\textsl{\textsf{Output}}\\ + \midrule + \verb|\CTAN| & \CTAN \\ + \verb|\eTex| & \eTeX \\ + \verb|\HTML| & \HTML \\ + \verb|\ISBN| & \ISBN \\ + \verb|\ISSN| & \ISSN \\ + \verb|\MF| & \MF \\ + \verb|\MP| & \MP \\ + \verb|\NTS| & \NTS \\ + \verb|\OMEGA| & \OMEGA \\ + \verb|\OTP| & \OTP \\ + \verb|\SGML| & \SGML \\ + \verb|\TUB| & \TUB \\ + \verb|\TUG| & \TUG \\ + \verb|\tug| & \tug \\ + \end{tabular} + \end{center} + \caption{Some of the classes' acronyms and logos} + \label{fig:acro-logo} +\end{figure} + +Authors are urged to note the \cs{acro} command, which is defined in +the classes. The visual appearance of (mostly) lower-case English +text, with interpolated acronyms in the same point size, is generally +unpleasing. Therefore, the \cs{acro} command typesets its argument +slightly smaller than it would otherwise appear: compare `\acro{URL}' +(\verb|\acro{URL}|, as used above) with `URL'\@. Many macros that +simply generate calls to \cs{acro} are defined by the classes; 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} +\item[\cs{cmd}] Typeset a control sequence name. (The command + \verb|\cs{fred}| is typeset as \cs{fred}.) +\item[\env{environment}] Typeset an environment name as if at the + start of the environment. (The command \verb|\env{fred}| is typeset + as \env{fred}.) +\item[\meta{arg}] Typeset a formal argument name. (The command + \verb|\meta{fred}| is typeset as \meta{fred}.) +\item[\Dash] Typeset an em-dash, surrounded by thin spa\-ces, only + breakable \emph{after} the dash; this is the preferred method of + specifying a dash in running text. +\item[\dash] Typeset an en-dash, in the same way as \cs{Dash} does. +\item[\nth{n}] Typeset an ordinal number. For example, \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, the \TUB{} team will be sympathetic to authors who wish to +use non-standard packages in their papers; indeed, in a journal +devoted to the usage of \TeX{}, the editor would be churlish indeed to +refuse such usage. However, the team does need to be able to process +the paper on the \TUB{} production computers, and the author who is +slapdash about the way she submits her paper will cause confusion and +delay. (Remember that the editorial team is a group of volunteers, +each working in his or her spare time.) + +In general, packages currently on \CTAN, and known to work with +\emph{current} \LaTeX{},\footnote{The team's version of \LaTeX{} is + regularly updated, though not during the course of a production + run.} 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{%\raggedfoot + Those in the \LaTeX{} base distribution, or one of those on the + \CTANref{packages} sub-tree on \CTAN.} subject to the two provisos: +\begin{itemize} +\itemsep=0.2\itemsep +\item Use of the \pkgname{verbatim} package has implications for the + \envname{verbatim} facilities provided by the classes\Dash see + section~\ref{sec:verbatim}. +\item Use of \pkgname{babel} almost inevitably implies use of + hyphenation patterns that the team may not have installed in their + \LaTeX{} format; it is therefore important that the author explains + her \pkgname{babel} configuration to the editorial team. The + minimum documentation required is a copy of the author's + \url{language.dat} file, and copies (or \CTAN{} pointers to) any + hyphenation files used. +\end{itemize} + +Usage of other packages should always be subject to negotiation with +the team. If the team does not have access to a copy of the package, +life is going to be very difficult; authors are urged to be sensible +in this regard. A sensible mechanism for submitting +out-of-the-ordinary packages (as for paper-specific bibliographies) is +by use of the \envname{filecontents} environment. + +\cbstart +\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. +\cbend + +Some facilities are considered inappropriate to delivery by the +\TUB{} classes, and as a result, the \TUB{} team recommend certain +packages to authors. + +At present, the list of 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). + +\section{Bibliography} +\label{sec:biblio} + +Bibliographic citations give much grief to the editorial team. Good +publishing practice requires that there be editorial control of the +way citations in a journal are presented yet, all too often, authors +submit articles whose bibliography is formatted according to their +preference. The important rules for authors, then, are that they +\emph{shouldn't} supply a \verb|.bbl| file (\BibTeX{} processed output), +and that they \emph{shouldn't} write out a \envname{thebibliography} +environment, but should rather submit a working \verb|.bib| file with their +paper.\footnote{The program \progname{bibextract}, available from + \CTAN{} in directory \CTANref{bibextract}, provides a convenient + mechanism for extracting just the relevant portions of your + bibliography database for submitting your paper; many of the common + \BibTeX{}-database management packages, such as \textsc{BibDB} or + \textsc{Bib}Tools offer similar facilities.} As with uncommon +packages, the \envname{filecontents} environment is a convenient way to +deliver the bibliography file. + +A special case is made of the accumulated bibliography of \TUB{} +itself;\footnote{\raggedfoot Available on \CTAN{} as + \CTANref{tub-biblio}} it is always available to the production team, +so that authors may make reference to items from that \verb|.bib| file +without further ado. + +Two citation styles are supported within \TUB{} articles, `\emph{raw}' +and `\emph{harvard}' (the present article is employing \emph{harvard} +citation). The raw citation style uses the `standard' +\BibTeX{} `\pkgname{plain}' (numeric) citation style; its modification +by use of Donald Arseneau's \pkgname{cite} +package\footnote{\raggedfoot Available on \CTAN{} as \CTANref{cite}} +is acceptable. Raw citation is selected by default (by execution of +class option \optname{rawcite}). + +Harvard citation may be selected by specifying \optname{harvardcite} as an +option of the \cs{documentclass} command. The macros used derive +pretty directly from the \textsl{\pkgname{harvard}} styles written by Glenn +Paulley and now maintained by Peter Williams; the \BibTeX{} style +derives from one developed by Patrick Daly. + +The basic citation format is `author-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. + +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 can often lead to pretty +unpleasant output in the narrow columns typical of \TUB{}. The author +may 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. + +\section{Equivalences between the `plain' and the \LaTeX{} 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{} 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} and \pkgname{moreverb} 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. + +%\EdNote[Should I mention the lack of \cs{every*} token registers (for +%all sorts of instances of \texttt{*}?)] + +\SetBibJustification{\raggedright} +\bibliography{tubguide} + +\makesignature + +\end{document} |