diff options
author | Karl Berry <karl@freefriends.org> | 2017-11-07 21:33:59 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2017-11-07 21:33:59 +0000 |
commit | 828da7b5f86a43b1ab9f31afeab0a23bd8e84fe9 (patch) | |
tree | e2dc35dc57256820635dfd1bc3a7d4ab946e6317 /Master/texmf-dist/doc/latex/tugboat/ltubguid.ltx | |
parent | 5ef92e83f1c7acdb441690476936a4cafc67dcc6 (diff) |
tugboat (7nov17)
git-svn-id: svn://tug.org/texlive/trunk@45713 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/tugboat/ltubguid.ltx')
-rw-r--r-- | Master/texmf-dist/doc/latex/tugboat/ltubguid.ltx | 305 |
1 files changed, 131 insertions, 174 deletions
diff --git a/Master/texmf-dist/doc/latex/tugboat/ltubguid.ltx b/Master/texmf-dist/doc/latex/tugboat/ltubguid.ltx index b9f9851ce0b..32b680931f9 100644 --- a/Master/texmf-dist/doc/latex/tugboat/ltubguid.ltx +++ b/Master/texmf-dist/doc/latex/tugboat/ltubguid.ltx @@ -1,7 +1,7 @@ -% $Id: ltubguid.ltx 135 2014-11-13 18:21:03Z karl $ +% $Id: ltubguid.ltx 187 2017-11-06 20:29:32Z karl $ % ltubguid.ltx - documentation for ltugboat classes. % -% Copyright 1994,1995,1996,2001,2005,2006,2010,2013,2014 TeX Users Group. +% Copyright 1994,1995,1996,2001,2005,2006,2010,2013,2014,2017 TeX Users Group. % % This file is part of the tugboat package. % @@ -16,7 +16,7 @@ % This work has the LPPL maintenance status "maintained". % % The Current Maintainer of this work is the TeX Users Group -% (http://tug.org/TUGboat). +% (https://tug.org/TUGboat). % % The list of all files belonging to the distribution is % given in the file `manifest.txt'. @@ -35,37 +35,32 @@ \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}}} +@Misc{pkg:fancyvrb, + author = {Timothy Van Zandt and others}, + title = {The {\textsf{fancyvrb}} package}, + year = {2015}, + howpublished = {\url{https://ctan.org/pkg/fancyvrb}}, } -@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{pkg:listings, + author = {Carsten Heinz and others}, + title = {The {\textsf{listings}} package}, + year = {2015}, + howpublished = {\url{https://ctan.org/pkg/listings}}, } -@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{Arseneau:url:1996, + author = {Donald Arseneau}, + title = {The {\textsf{url}} package}, + year = {2013}, + howpublished = {\url{https://ctan.org/pkg/url}}, } @Misc{Rahtz:hyperref:1997, - author = {Sebastian Rahtz and Heiko Oberdiek}, - title = {The {\textsf{hyperref}} system}, - year = 1997, - howpublished = {Available from {\CTAN}, {\CTANref{hyperref}}} + author = {Sebastian Rahtz and Heiko Oberdiek and others}, + title = {The {\textsf{hyperref}} package}, + year = 2017, + howpublished = {\url{https://ctan.org/pkg/hyperref}}, } @Book{Lamport:1994, @@ -73,29 +68,7 @@ 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} + publisher = {Addison-Wesley}, } @Misc{Schoepf:verbatim:1996, @@ -103,25 +76,14 @@ 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} + howpublished = {\url{https://ctan.org/pkg/mflogo}}, } @Misc{Vieth:mflogo:1995, author = {Ulrik Vieth}, title = {The {\textsf{mflogo}} package}, - year = {1995}, - howpublished = {Available from {\CTAN}, {\CTANref{mflogo}}} + year = {1999}, + howpublished = {\url{https://ctan.org/pkg/mflogo}}, } @Article{Whitney:TB10-3-378, @@ -132,7 +94,8 @@ month = {November}, volume = {10}, number = {3}, - pages = {378--385} + pages = {378--385}, + note = {\url{https://ctan.org/pkg/tugboat-plain}}, } \end{filecontents} @@ -173,20 +136,19 @@ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % -\documentclass[harvardcite,final]{ltugboat} +\documentclass[final]{ltugboat} \usepackage{microtype} \usepackage{ctandir} \IfFileExists{booktabs.sty}% {\usepackage{booktabs}}% {\let\midrule\hline} % -% imperfectly broken pages are ok. -\vbadness=10000 +\vbadness=10000 % imperfectly broken pages are ok +\overfullrule=4pt % want to see % % 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} @@ -249,11 +211,11 @@ \begin{document} %%%%%%%%%%%%%%%% % -\title{The \LaTeXe\ \TUB{} Macros} +\title{The \LaTeXe\ \TUB{} macros} \author{Robin Fairbairns \& TUGboat editors} \EDITORnoaddress \netaddress{tugboat@tug.org} -\personalURL{http://tug.org/TUGboat} +\personalURL{https://tug.org/TUGboat} \maketitle \section{Introduction} @@ -268,7 +230,7 @@ Mimi Burbank, and the \LaTeX3 team. \section{Availability} -\TUB's web pages are at:\\\centerline{\url{http://tug.org/TUGboat}} They +The \TUB\ web pages are at:\\\centerline{\url{https://tug.org/TUGboat}} They include an article template, information for authors and reviewers, all the back issues, and more. @@ -342,23 +304,14 @@ They are listed here for completeness. \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{\tubraggedfoot 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 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 present author) the gay +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. Nevertheless, on the whole, -the new \clsname{ltugboat} macros simply define \LaTeX{} commands and +\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. @@ -470,7 +423,7 @@ For example, the present paper has at its start: \author{TUGboat editors} \EDITORnoaddress \netaddress{tugboat@tug.org} -\personalURL{http://tug.org/TUGboat} +\personalURL{https://tug.org/TUGboat} \maketitle \end{verbatim} @@ -539,19 +492,14 @@ between the \cs{maketitle} and (possibly) \cs{makesignature} commands. \author{Robin Fairbairns} \address{University of Cambridge ...} \netaddress{...} - ... - |emph[introductory text] - ... + ... |textsl[introductory text] ... \makesignature \contributor{Betsy the Dog} \address{Romsey Town, Cambridge} - ... - |emph[Betsy's contribution] - ... -\makesignature - + ... |textsl[Betsy's contribution] ... ... +\makesignature ... \end{verbatim} \section{Verbatim text} @@ -569,51 +517,73 @@ 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 +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 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]|} + 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 -\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 + 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} + +\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, but it can, for - example, be employed to provide interesting effects by knowledgeable - authors. + that should only be used with the utmost caution. + \end{itemize} -Two caveats about the use of this facility should be noted: +Two caveats about these optional arguments: \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 + 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., - 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.) + `\verb|[]|') to the \envname{verbatim} environment. +\item The \TUB\ facility is lost when anything 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 @@ -649,7 +619,7 @@ set of the macros. 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{http://tug.org/TUGboat/location.html} have a more complete list, +\url{https://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} @@ -663,12 +633,12 @@ and of course the class sources are the ultimate reference. \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|\NTS| & \NTS \\ \verb|\OMEGA| & \OMEGA \\ \verb|\PDF| & \PDF \\ \verb|\SGML| & \SGML \\ @@ -678,18 +648,18 @@ and of course the class sources are the ultimate reference. \verb|\XML| & \XML \\ \end{tabular} \end{center} - \caption{A few of the classes' acronyms and logos} + \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 (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 +generally unpleasing in Computer Modern. Therefore, the \cs{acro} +command typesets its argument slightly smaller than it would otherwise +appear: 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} @@ -697,22 +667,22 @@ figure~\ref{fig:acro-logo} have already been used in the present paper. 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 +\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}\,. +%\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} @@ -729,23 +699,16 @@ In general, packages currently on \CTAN, and known to work with 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 two provisos: + \CTANref{packages} sub-tree on \CTAN.} subject to the warning: \begin{itemize} \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 +life is going to be very difficult; authors need 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. @@ -787,11 +750,11 @@ particular packages for the subject at hand. \section{Bibliography} \label{sec:biblio} -In short: our recommendation for handling bibliographies is to use +In short: our basic recommendation for handling bibliographies is to use \BibTeX\ and the \pkgname{plain} bibliography style. No document options are needed or recommended. All that is required in the article -source (as shown in the sample available from -\url{http://tug.org/TUGboat}) is the following: +source (as shown in the template available from +\url{https://tug.org/TUGboat}) is the following: \begin{verbatim}[\small] \bibliographystyle{plain} @@ -821,19 +784,15 @@ deliver the bibliography file. A special case is the accumulated bibliography of \TUB{} itself;\footnote{\tubraggedfoot Available on \CTAN{} as \CTANref{tub-biblio}} it is always available to the production team, -so that authors may make reference to items from the \verb|tugboat.bib| +so authors may reference items from the \verb|tugboat.bib| file without further ado. Notwithstanding the general recommendation for the \pkgname{plain} \BibTeX\ style, two citation styles are supported within \TUB{} articles, `\texttt{raw}' -and `\texttt{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{\tubraggedfoot Available on \CTAN{} as \CTANref{cite}} -is acceptable. Raw citation is selected by default (by execution of -class option \optname{rawcite}). +and `\texttt{harvard}'. The raw citation style uses the `standard' +\BibTeX{} `\pkgname{plain}' (numeric) citation style. 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 @@ -892,7 +851,7 @@ may control the typesetting using the command \end{verbatim} as the present article does, to achieve somewhat better results. -\section{Equivalences between the `plain' and the \LaTeX{} packages} +\section{Equivalences between the `plain' and \LaTeX{} \TUB\ packages} \label{sec:equiv} A good proportion of the commands in the `plain' packages also appear @@ -915,7 +874,7 @@ differ significantly. \cs{figure} & \envname{figure} or \envname{figure*} environments \\ \end{tabular} \end{center} - \caption{Equivalences between \pkgname{plain} and \LaTeX{} macros} + \caption{Equivalences between \pkgname{plain} and \LaTeX{} \TUB\ macros} \label{fig:plain-equiv} \end{figure} @@ -925,9 +884,9 @@ 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 +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 @@ -938,10 +897,8 @@ argument provision promulgated by the `plain' macros \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} +\bibliographystyle{plain} \bibliography{tubguide} \makesignature |