diff options
Diffstat (limited to 'Master/texmf-dist/doc/plain/tugboat-plain/tubguide.tex')
| -rw-r--r-- | Master/texmf-dist/doc/plain/tugboat-plain/tubguide.tex | 178 |
1 files changed, 66 insertions, 112 deletions
diff --git a/Master/texmf-dist/doc/plain/tugboat-plain/tubguide.tex b/Master/texmf-dist/doc/plain/tugboat-plain/tubguide.tex index a51b5ab3b9b..4c2ec29c44f 100644 --- a/Master/texmf-dist/doc/plain/tugboat-plain/tubguide.tex +++ b/Master/texmf-dist/doc/plain/tugboat-plain/tubguide.tex @@ -1,9 +1,9 @@ %% @texfile{ %% filename = "tubguide.tex", -%% version = "1.04", -%% date = "2012/05/22", +%% version = "1.22", +%% date = "2016/09/26", %% filetype = "TUGboat Authors' Guide", -%% copyright = "Copyright 1989, 1992, 2006, 2012 TeX Users Group. +%% copyright = "Copyright 1989, 1992, 2006, 2012-2016 TeX Users Group. %% Unlimited copying and redistribution of this file %% are permitted as long as this file is not %% modified. Modifications (and redistribution of @@ -17,7 +17,7 @@ %% that produced the original Authors' Guide in %% TUGboat 10, no. 3, November 1989.", %% } -%% $Id: tubguide.tex 100 2012-05-22 18:09:46Z bnb $ +%% $Id: tubguide.tex 157 2016-09-26 23:34:10Z karl $ %% ********************************************************* %% %% TeXing this file requires the following files: @@ -48,8 +48,8 @@ \author * Barbara Beeton * \address * American Mathematical Society\\ - 201 Charles Street\\ - Providence, RI 02904-2294 * + 201 Charles Street\\ + Providence, RI 02904-2294 * \netaddress * TUGboat@tug.org * \author * Ron Whitney * @@ -57,12 +57,13 @@ %\netaddress * TUGboat@Math.AMS.com * -\vfootnote{}{Revised March 1992, May 2006, May 2012; the original appeared in +\vfootnote{}{Revised March 1992, May 2006, May 2012, September 2016; the +original appeared in \tubissue 10(3), November 1989.} \article -With this article we hope to fill a lacuna (some might say ``void'') +With this report we hope to fill a lacuna (some might say ``void'') whose existence we have been attributing to the usual factors: tight schedules, alternative priorities and warty \TeX\ code. We now feel the macros in use for \TUB\/ have stabilized to the extent that @@ -74,38 +75,40 @@ for the style files). Suggestions and comments are quite welcome at the addresses listed below. \TUB\/ was originally typeset with a package based only on \plain. -Later, as demand for style files follows wherever -\LaTeX-devotees wander, a \TUB\/ variant of the \LaTeX\ {\tt article} -style was also created. The two macro sets yield -much the same output, differing in certain ways for input. Below we -make comment on various aspects of the \TUB\/ package, first for the -\plain-based macros, then for \LaTeX. The macro sets share -the file |tugboat.cmn|,\footnote{$^1$}{This file used to be named -{\tt tugboat.com}, but that notation was in conflict with conventions -of \acro{MS-DOS} and other operating systems; no conflicts are known to -exist for the new name.} and users of either style should read the -section entitled ``Common Abbreviations and Utilities''. We conclude -with some general suggestions to help make the lives of those on the -receiving end of (any kind of) electronic copy a little easier. +Later, as demand for style files follows wherever \LaTeX-devotees +wander, a \TUB\/ variant of the \LaTeX\ {\tt article} class was also +created\Dash see |ltugboat.cls| and its documentation in the separate +package |tugboat| (|http://ctan.org/pkg/tugboat|) . The two macro sets +yield much the same output, and many input conventions are identical, +with differences where they seemed natural. + +Below we describe various aspects of the \TUB\/ package for the +\plain-based macros. We conclude with some general suggestions to help +make the lives of those on the receiving end of (any kind of) electronic +copy a little easier. \head * The \plain-based macros: {\tt tugboat.sty} * -The macros are contained in two files, |tugboat.sty| and |tugboat.cmn|.$^1$ - -\subhead * General description of tags * -We attempt wherever possible to tag the various elements of \TUB\/ -articles in a ``generic'' way, modified in some respects by -convenience. Authors and editors, of course, need tools to shape -their articles to the form they desire, but we also wish to encourage -a tagging style which is appropriate for electronic interchange. It -seems unfair to expect much thought from authors concerning the -markup of their information if we only provide a bag of widgets and -do-hickies to hack and pound an article together. The tags whose use -we encourage are the higher-level tags that mark the logical -document structure. Below these are formatting macros that we -recognize may be essential for certain applications. Both sorts of -tags are described in the following article. +The macros are contained in two files, |tugboat.sty| and +|tugboat.cmn|.\footnote{$^1$}{1) A file |tugproc.sty| is also +distributed, but no longer used. 2) |tugboat.cmn| used to be named {\tt +tugboat.com}, but that notation was in conflict with conventions of +\acro{MS-DOS} and other operating systems; no conflicts are known to +exist for the new name.} + +\subhead * General description of tags * We attempt wherever possible to +tag the various elements of \TUB\/ articles in a ``generic'' way, +modified in some respects by convenience. Authors and editors need +tools to shape their articles to the form they desire, but we also wish +to encourage a tagging style which is appropriate for electronic +interchange. It seems unfair to expect much thought from authors +concerning the markup of their information if we only provide a bag of +widgets and do-hickies to hack and pound an article together. The tags +whose use we encourage are the higher-level tags that mark the logical +document structure. Below these are formatting macros that we recognize +may be essential for certain applications. Both sorts of tags are +described in the following article. Generally, to ``mark up'' the data <foo>, a tag |\xxx| will precede <foo> and |\endxxx| will follow (thus: |\xxx <foo>\endxxx|). We use @@ -216,7 +219,7 @@ of \thenetaddress {<author number>} || to get the desired result. For example, for an article with% -\footnote{$^2$}{\xEdNote The \TUB{} address shown in examples +\footnote{$^2$}{\xEdNote The \TUB{} email address shown in examples was current when this article first appeared, but is now obsolete; it has been left intact to avoid other problems. The correct address is now {\tt TUGboat@tug.org}.} @@ -294,7 +297,7 @@ which {\it appear\/} innocuous, may not be so. \subhead * Lists * -Lists are everywhere, of course, and a simple list hierarchy can +Lists are everywhere, and a simple list hierarchy can transform a one-dimensional typesetting problem into something nasty. All of which is to say, we are certainly not done with this area of tagging, but here are the available macros. @@ -660,56 +663,7 @@ listed under tags. \caption{...} \twocolfigure || -and, of course, \verbinline|\endverbatim and \verbinline||\endverbatim. - -\head * The \LaTeX\ macros: {\tt ltugboat.sty}% -\footnote{$^3$}{This discussion of {\tt ltugboat.sty} is now of -historical interest only; it has been superseded by a \LaTeXe{} -documentclass, {\tt ltugboat.cls}, available from \CTAN.} * - -|ltugboat.sty| is the primary macro file, and is based on the \LaTeX{} -|article.sty|. |tugboat.cmn|, a collection of items common to both -\LaTeX\ and \plain\ input, is also required. Articles will have -the form:\footnote{$^4$}{{\tt ltugboat} used to be a substyle; it now -stands on its own, by automatically inputting {\tt article.sty}.} -\verbatim[\makeescape\|] -\documentstyle{ltugboat} -|halfline -<perhaps additional macros for article> -|halfline -\title {<title>} -\author{<author>} -\address{<address>} -\netaddress{<netaddress>} - -\begin{document} -\maketitle -|vellipsis -<body of article> -|vellipsis -\makesignature -\end{document} -\endverbatim -This is the usual form for \LaTeX\ documents, of course, except -that now each author will have his/her own -\verbatim -\author{...} -\address{...} -\netaddress{...} -\endverbatim -block. As with the \plain{} style, the author and address -macros will store their information for later display. -See the discussion of |\address|, |\netaddress| and |\makesignature| -on the second page of this article to understand more. Linebreaks -within |\title|, |\author|, and |\...address| are specified with |\\|. - -We refer the user to the \LaTeX\ manual for description of section -heads, verbatim mode, insertions, and movement between one- and -two-column format. The style of printed output has, of course, been -somewhat modified to fit \TUB\/ style. |ltugboat.sty| might be of some -use to others wishing to modify the |article| option in this -direction. - +and \verbinline|\endverbatim and \verbinline||\endverbatim input syntax. \head * Common abbreviations and utilities * @@ -722,14 +676,18 @@ necessary. A nicety for the sake of appearance is the command |\acro|, which sets an acronym in caps one size smaller than the surrounding text. Compare CTAN (full size), \CTAN{} (|\acro{CTAN}|) and {\smc ctan} -(small caps). Acronyms in |tugboat.cmn| use |\acro| consistently. +(small caps). Acronyms in |tugboat.cmn| use |\acro| consistently, +except in (some) bibliographies. Several other constructions that we have found useful for both \plain- and \LaTeX-style input have been incorporated in |tugboat.cmn|. Various |\*lap|\,s (|\ulap|, |\dlap|, |\xlap|, |\ylap|, |\zlap|) and |\*smash|\,es provide means of setting type -which ``laps'' into neighboring regions. |\dash| and |\Dash| are en- -and em-dashes that break properly. |\slash| is a breakable slash. +which ``laps'' into neighboring regions. +|\Dash| is an em-dash with surrounding thinspaces, our preferred style. +|\slash| is a breakable slash. +|\cs{foo}| typesets |\foo|, just like \verbinline|\foo|\endverbatim (but +since |\cs| is the usual \TUB\ \LaTeX\ convention, we support it here too). The macro \verbatim \makestrut [<ascender dimen>; @@ -760,7 +718,7 @@ Constructing an entire issue of \TUB\/ requires use of a few features that authors may notice when articles are returned for proofing. |\xrefto| allows for symbolic cross-referencing, but is enabled only late in the production process. The distribution version of -|tugboat.cmn| defines |\xrefto| so that ``???'' is typeset whenever it +|tugboat.cmn| defines |\xrefto| so that ``???''\ is typeset whenever it is called. Not to worry. We also put notes into the file since there are many things to @@ -804,21 +762,19 @@ narrowly specific) result. When authors proof their articles in formats other than that of \TUB\/ (for example), they should expect that \TUB's changes in pagewidth and pagedepth may drastically alter text layout. Paragraphs are rebroken -automatically when |\hsize| and |\vsize| change, but |\centerline| -does not break, and we often see tables and math displays which are -rigidly laid out. When possible, authors might use paragraphing -techniques instead of calls to, say, |\centerline| (Beeton will be -writing up her lectures on paragraphing techniques for a future issue -of \TUB\/), and they should try to code tables in such a way that -widths of columns can be changed easily. Generally, authors should -attempt to anticipate the work that might be necessary if requests for -other reasonable formats of their texts are made. In the case of -\TUB, we make a strong effort to stuff macro listings and tables into -the two-column format. Since these types of items are not generally -susceptible to automatic line-breaking, we give thanks to stuffings -made by authors ahead of time. In this context, we recommend the use -of |\verbfile{...}| (see the section `{Verbatim modes}') to maintain -consistency between documentation and reality. +automatically when |\hsize| and |\vsize| change, but |\centerline| does +not break, and we often see tables and math displays which are rigidly +laid out. When possible, authors might use paragraphing techniques +instead of calls to, say, |\centerline|, and they should try to code +tables in such a way that widths of columns can be changed easily. +Generally, authors should attempt to anticipate the work that might be +necessary if requests for other reasonable formats of their texts are +made. In the case of \TUB, we make a strong effort to stuff macro +listings and tables into the two-column format. Since these types of +items are not generally susceptible to automatic line-breaking, we give +thanks to stuffings made by authors ahead of time. In this context, we +recommend the use of |\verbfile{...}| (see the section `{Verbatim +modes}') to maintain consistency between documentation and reality. Specifically in the domain of \TeX\ macros, we find that many authors throw in unnecessary |%| characters to end code lines. Except in @@ -842,14 +798,12 @@ little extra effort in making these macros consistent with the macros in wide distribution and in making them robust will be much appreciated. -\TBremark{Anything about formatting macros?} - \head * Electronic documentation and submissions * -In addition to |tugboat.sty|, |ltugboat.sty|, and |tugboat.cmn|, -a copy of this article, |tubguide.tex|, will be available in -most \TeX{} distributions and on \CTAN: +The TUGboat styles for both \LaTeX\ and plain \TeX\ are available on +\CTAN\ and already included in most \TeX\ distributions: + ||http://ctan.org/pkg/tugboat http://ctan.org/pkg/tugboat-plain|| |