%% %% This is file `aguplus.tex', generated %% on <1994/5/27> with the docstrip utility (2.2e). %% %% The original source files were: %% %% aguplus.dtx (with options: `manual') %% %% --------------------------------- %% AGUPLUS.TEX %% --------------------------------- %% This is the user's manual for %% AGU++ %% an extension to the AGU %% LaTeX package AGUTeX %% %%============================AGUPLUS.DTX=========================== \ifx\documentclass\undefined \documentstyle[twoside,agupp,aguplus]{article} \else \documentclass[twoside]{article} \usepackage{agupp,aguplus} \fi \def\filename{aguplus} \def\fileversion{1.0} \def\filedate{1994/05/26} %% Copyright (C) 1994 Patrick W. Daly \expandafter\ifx\csname if@compatibility\endcsname\iffalse\else \def\LaTeXe{\protect\pLaTeXe} \def\pLaTeXe{\mbox{% \LaTeX\kern.15em$2_{\textstyle\varepsilon}$}} \fi \expandafter\ifx\csname if@compatibility\endcsname\relax \makeatletter \def\p@LaTeX{\@tempcnta=\the\fam \leavevmode L\raise.42ex \hbox{$\fam\@tempcnta\scriptstyle\kern-.3em A$}\kern-.15em% T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX} \makeatother \let\bfseries=\bf \let\mdseries=\rm \let\upshape=\rm \let\itshape=\it \let\slshape=\sl \let\scshape=\sc \let\sffamily=\sf \let\rmfamily=\rm \let\ttfamily=\tt \let\normalfont=\rm \fi \expandafter\ifx\csname emph\endcsname\relax \newcommand{\emph}[1]{{\em #1\/}} \newcommand{\textbf}[1]{{\bf #1}} \newcommand{\textit}[1]{{\it #1}\/} \newcommand{\texttt}[1]{{\tt #1}} \newcommand{\textsf}[1]{{\sf #1}} \newcommand{\textrm}[1]{{\rm #1}} \newcommand{\textsc}[1]{{\sc #1}} \newcommand{\textsl}[1]{{\sl #1\/}} \fi \newcommand{\btx}{\textsc{Bib}\TeX} \newcommand{\theoption}{\texttt{\filename}} \newcommand{\app}{{\small\optionlogo}} \newcommand{\bsl}{\char`\\} \lefthead{P. W. Daly} \righthead{\protect\optionlogo: an Extension to AGU\TeX} \cpright{PD}{1993} \afour \sloppy \begin{document} \title{The \LaTeX{} Extension Package \optionlogo\\ for Use with AGU\TeX} \author{Patrick W. Daly} \affil{Max-Planck-Institut f\"ur Aeronomie, Lindau, Germany} \authoraddr{P. W. Daly, Max-Planck-Institut f\"ur Aeronomie, D--37189 Katlenburg-Lindau, Germany} \begin{abstract} This paper describes how to use the AGU package (AGU\TeX) for producing manuscripts, preprints, and camera-ready copy, together with an unofficial extension package called \app{}. This extension adds extra features such as author-year citations with \btx{} and true figures in the preprint version. Other extra features include corrected coding to avoid having to give certain numbers explicitly, sublabelling of equations, figures, etc., and balancing two columns of text on the last page. These features were all part of my older unofficial AGU package and are thus well-known among its users. \end{abstract} \section{Introduction} The American Geophysical Union (AGU) has finally come out with its own official \LaTeX\ package for producing manuscripts and camera-ready copy for its journals. At the same time the format of the journals has been dramatically altered. Thus my unofficial \LaTeX\ package for AGU (\texttt{art-jgr} and \texttt{art-grl}) becomes not only superfluous but obsolete. However, in looking over the instructions and coding of the official package, I realize that not only are some imperfections present, but many useful features of my styles are missing. The most noticeable of these is the means of using author-year citations with \btx{} in an automated manner. The coding imperfections are related to the way in which figure captions and tables are treated: they must be placed at the end of the document, and if an appendix is present, then the automatic numbering system will consider them as appendix figures and tables (numbered A1, A2, \dots). To avoid this, explicit numbers must be given, something that violates the essential principles of a formatting program like \LaTeX. A second implication of this treatment is that preprints will be missing the figures and tables in the text. In my older system, neither of these problems occurred. {\em By popular demand}, I have undertaken to write an extension to the official AGU package, called \app (for AGU doubly-ionized or super-charged, as you please). It includes my extra features without changing any of the formats of the original package. The user should prepare his documents in the manner described by the AGU, except that figures, tables, and plates are to be included {\em in the text\/} as described below. A number of extra commands are available to control and/or enable the extra features. This manual explains the official package with my extensions. This is to enable the user to obtain all the necessary information in one article rather than to have to search among several. It is not meant to serve as instructions for the standard AGU package alone, although differences will be indicated; neither is it intended to be a manual for \LaTeX, since it assumes that the user already understands the workings of that text formatting scheme. The classic textbook on \LaTeX{} is \cite{la}; a more recent and more extensive work is by \cite{koda}. \section{The Official Package} The official AGU package is called AGU\TeX. It consists of an instruction manual (\texttt{aguguide.tex}), a sample article (\texttt{sample.tex}), and, of course, a number of {\em style options\/} that are to be used with the standard main style \texttt{article}. These are \begin{description} \item[\ttfamily agums] to produce a manuscript for submission; \item[\ttfamily agupp] to produce a preprint in two-column format (like this paper) for distribution to colleagues; \item[\ttfamily jgrga] to produce camera-ready copy (or {\em galley proofs\/}) for the {\em Journal of Geophysical Research\/} (JGR), the {\em Global Biogeochemical Cycles}, and {\em Pale\-ocean\-o\-graphy}; \item[\ttfamily grlga] to produce camera-ready copy for {\em Geophysical Research Letters\/} (GRL); \item[\ttfamily tecga] to produce camera-ready copy for {\em Tectonics}; \item[\ttfamily radga] to produce camera-ready copy for {\em Radio Science}. \end{description} For example, the first line of the document should be something like \begin{quote} \verb!\documentstyle[jgrga]{article}! \\ \makebox[0pt][r]{or\hspace{1ex}}\verb!\documentstyle[agums]{article}! \end{quote} for JGR camera-ready copy or a manuscript, respectively. Note that the term {\em galley proofs\/} is more accurate than {\em camera-ready copy\/}, since the latter implies finished pages in 1-to-1 relation with the final journal article. In fact, the papers are still cut and pasted together, with figures and tables inserted by hand. However, I will continue to refer to the galley proofs as camera-ready copy since this is the terminology that most of us are used to. \subsection{The Extension Package} The \app{} extension package is now included by adding the option \theoption{} {\em after\/} the above options, as e.g. \begin{quote} \verb!\documentstyle[jgrga,!\theoption\verb!]{article}! \end{quote} It makes sense to include the \texttt{twoside} option with the preprint \texttt{agupp} choice; there is no point in selecting \texttt{titlepage}. The manuscript produced with \texttt{agums} is double spaced. In order to generate a single space manuscript, add the option \texttt{tighten}, or include the command \verb!\tighten! in the preample. (Reminder: the {\em preamble\/} is everything that comes between \verb!\documentstyle! and \verb!\begin{document}!.) To alternate between single and double spaced text, use the commands \verb!\singlespace! and \verb!\doublespace! anywhere in the text. \subsection{The New \LaTeX{} Standard} The package \app{} works under the new standard \LaTeXe; however, there are some problems with AGU\TeX, which are fixed up by calling the special package \texttt{agu2e} \emph{before} any of the AGU\TeX{} files. For example, \begin{quote} \verb!\documentclass{article}!\\ \verb! \usepackage{agu2e,jgrga,aguplus}! \end{quote} \section{Organization of the Paper} \subsection{Front Material} Before the main body of the text, some information about the manuscript and paper must be given. This information may actually be printed at the end of the article, depending on which option has been selected, but it is always entered at the start, before \verb!\begin{document}!. \begin{quote} \verb!\received{!{\em date\_received\/}\verb!}!\\ \verb!\revised{!{\em date\_revised\/}\verb!}!\\ \verb!\accepted{!{\em date\_accepted\/}\verb!}! \end{quote} These commands enter the relevant dates, which are only meaningful for the camera-ready copy. They will be communicated to the author by the editor. \begin{quote} \verb!\journalid{!{\em vol\/}\verb!}{!{\em journal\_date\/}\verb!}!\\ \verb!\articleid{!{\em start\_page\/}\verb!}{!{\em end\_page\/}\verb!}!\\ \verb!\paperid{!{\em manuscript\_id\/}\verb!}! \end{quote} Again, this information will be communicated to the author by the editor. (It seems that at the moment the first two do not really do anything at all, but may be provided for the future when AGU dispenses with cutting and pasting and goes to true camera-ready production.) \begin{quote} \verb!\cpright{!{\em type\/}\verb!}{!{\em year\/}\verb!}!\\ \verb!\ccc{!{\em code\/}\verb!}! \end{quote} These enter copyright information, for which {\em code\/} will be communicated to the author. The {\em type\/} is one of \begin{description} \item[\ttfamily AGU] for AGU copyright \item[\ttfamily Crown] for (Commonwealth) government copyright \item[\ttfamily PD] for public domain (no copyright) \end{description} \begin{quote} \verb!\lefthead{!{\em authors\/}\verb!}!\\ \verb!\righthead{!{\em short\_title\/}\verb!}! \end{quote} These commands permit text for the running heads to be included. For the camera-ready copy, they are (currently) printed out so many times at the end (later cutting and pasting!) but with \theoption, they will be added at the top of each page of the preprint. \begin{quote} \verb!\slugcomment{!{\em text\/}\verb!}! \end{quote} With this command, the author may include his own text to be printed at the top of the preprint title page, such as ``This article is to appear in \dots.'' The information that is printed at the end of the camera-ready copy comes after the list of references, and the output is part of that command. If there are no references, then the information must be forced out with the command \begin{quote} \verb!\forcesluginfo! \end{quote} following the main text. \subsection[]{Declarations for \app} A number of additional \app{} declarations are available to enable or modify some of the features. These may all be given in the preamble too, although some may actually be permitted anywhere in the document. They are all described later, but are listed here for completeness. \begin{description} \item[\ttfamily \bsl sectionnumbers] turns on section numbering; default is no numbering, as preferred by AGU; must be given before the first \verb!\section! command. \item[\ttfamily \bsl extraabstract] prints a supplemental abstract at the end of the camera-ready version, as required by JGR; this may be invoked anywhere in the paper, for it only enables the output which always comes at the end. \item[\ttfamily \bsl printfigures] causes the figures and plates to be output at the end of the manuscript and camera-ready copy; this is in addition to the figure captions that are always output and is only meaningful if the \texttt{figure} and \texttt{plate} environments really contain something to print. \item[\ttfamily \bsl figmarkoff] suppresses the printing of marginal notes next to the location where \texttt{figure}, \texttt{plate}, and \texttt{table} environments occur; by default such mar\-gin\-al notes are enabled. \item[\ttfamily \bsl figmarkon] re-enables the marginal notes; these two declarations may be given as often and wherever one feels they are needed. \item[\ttfamily \bsl doublecaption\char`\{35pc\char`\}] enables the printing of all figure and plate captions in two widths: once in the single column width and again in the width specified, here 35~pc; JGR still requires (for now anyway) that all captions be provided in two sizes. \item[\ttfamily \bsl afour] changes the page layout to be more appropriate to European A4 paper; for camera-ready this means only that the page is slightly longer but the column width remains the same. \end{description} \subsection{Title and Authors} The preamble is ended with \verb!\begin{document}!, and the title and author information are given. \begin{quote}\slshape Contrary to standard \LaTeX, the title and authors are printed by the commands that enter the information. This means these commands {\bfseries may not be given in the preamble!} For many authors, this means changing long-standing habits. \end{quote} The coding in \app{} corrects this, so that the traditional \LaTeX{} behaviour is re-established. \begin{quote} \verb!\title{!{\em full\_title\/}\verb!}!\\ \verb!\author{!{\em names\/}\verb!}!\\ \verb!\affil{!{\em organization\/}\verb!}!\\ \verb!\authoraddr{!{\em full\_address\/}\verb!}! \end{quote} The order of these commands is important. First comes the \verb!\title!, the argument of which may be broken up into lines with \verb!\\! commands (not absolutely necessary). Next come sets of \verb!\author! and \verb!\affil! commands, one set per author organization. {\slshape(This again is different from standard \LaTeX{} where \verb!\author! is given only once.)} Finally, the \verb!\authoraddr! command is given (anywhere) once for each author, with the name and full postal address as argument. An alternative method of presenting the authors is with footnotes for the affiliations. This is done with the commands \begin{quote} \verb!\altaffilmark{!{\em numbers\/}\verb!}!\\ \verb!\altaffiltext{!{\em number\/}\verb!}{!{\em text\/}\verb!}! \end{quote} The first command is included in the text of the \verb!\author! command; the second is given once per footnote afterwards. For example, \begin{quote} \begin{verbatim} \author{J. P. Smith\altaffilmark{1,2} and C. J. Jones\altaffilmark{2}} \altaffiltext{1}{On leave} \altaffiltext{2}{Research Institute X} \end{verbatim} \end{quote} The two methods (\verb!\affil! or footnotes) may be combined. The \verb!\authoraddr! commands should rightly come in the preamble after the copyright information. Their arguments are printed out only for the camera-ready copy, at the end. \subsection{The Abstract} Following the title comes the abstract. This is given as in standard \LaTeX{} within an \texttt{abstract} environment, as \begin{quote}\begin{verbatim} \begin{abstract} This is the text of the abstract. . . \end{abstract} \end{verbatim} \end{quote} \subsection{The Text Body} The rest of the body of the article is organized into {\em sections\/}, {\em subsections}, and {\em sub-subsections}, with commands \verb!\section{!{\em heading\/}\verb!}!, \verb!\subsection{!{\em heading\/}\verb!}!, and \verb!\subsubsection{!{\em heading\/}\verb!}!, whereby the third-level {\em heading\/} should capitalize only the first word and end with a period. \subsubsection{This is a third-level heading.} It has been entered with: \verb!\subsubsection{!\texttt{This is a third-level heading.}\verb!}! with the final period included. (In the camera-ready copy, the third-level heading is run into the following text on the same line.) \begin{quote} Sections are normally not numbered, unless the \app{} declaration \verb!\sectionnumbers! has been issued. The AGU manual states that section numbering should be carried out {\em by explicitly including the numbers in the heading text.} This would violate a fundamental principle of a formatting language like \LaTeX, and will lead to much annoyance when sections are referred to or are changed. The AGU's argument is that \LaTeX{} will not format the numbered sections in the way that it wants them. \app{} has corrected so that the automatic numbering may be used. \end{quote} \subsection{Appendices} As in normal \LaTeX, the declaration \verb!\appendix! is issued at that point where the appendices are to start. This command redefines a number of things so that the sectioning commands now function as appendix headers. The numbering of equations and tables is also changed. \begin{quote} With \app, the numbering of figures and plates is also changed. I think it was an oversight on the part of AGU not to do this too, for it seems strange to have such inconsistent behavior. Besides, there are enough examples in previous AGU publications where figures too are numbered within appendices. \end{quote} If there is only one appendix, it should be introduced with the command \verb!\section*! rather than \verb!\section!. Recall that the starred versions suppress section numbering, or in the case of appendices, lettering. \begin{quote} The standard AGU package requires that the appendix letter be included in the heading text. This is the same repugnant notion as putting section numbers in explicitly. In \app, this is not necessary. Thus where AGU says to give \verb!\section{Appendix A: Title}!, it is sufficient to type only \verb!\section{Title}! (or \verb!\section*{Title}! if there is only one appendix). \end{quote} \subsection{The Acknowledgments} Acknowledgments come after the main text, including appendices, but before the list of references. They are introduced with the command \begin{quote} \verb!\acknowledgments!\\ \makebox[0pt][r]{or }\verb!\acknowledgements! \end{quote} Both print the same word, with the American spelling. (This command is part of AGU\TeX, and is not an \app{} extra.) \section{Floats} The major difference between the official AGU package and \app{} is the treatment of figures, plates, and tables, objects that are referred to as `floats' in \LaTeX{} terminology because they do not appear where they are typed in in the text, but move around to an appropriate location. The AGU standard package wants {\em all\/} floats to appear at the end of the manuscript and camera-ready copy (fair enough), and the figures and plates to be printed {\em only as captions}. This means that the preprints will also only exhibit the captions, and that all floats come at the end and will not be integrated in the text. Another major, ridiculous problem, is that if there is an appendix in the work, then all floats entered at the end must be given explicit numbers, for otherwise \LaTeX{} automatic numbering will treat them as appendix items with corresponding numbering. I have already expressed my sentiment about explicit numbering. With \app, these problems are solved. Floats are entered in the text {\em where they are first referred to}. For preprints, they are then printed in the text as in a normal \LaTeX{} article; for manuscripts and camera-ready copy, only a marginal note is printed with the number, something AGU insists on anyway. (This may be suppressed with \verb!\figmarkfalse! and reinstated with \verb!\figmarktrue!.) The figure and plate captions are then automatically listed at the end, followed by the tables, followed optionally by the figures and plates themselves. \subsection{Figures and Plates} \begin{figure} \figbox{\hsize}{6cm}{Paste Figure Here} \caption[]{A demonstration paste-in figure. The width was given as {\tt\protect\bsl hsize} (the column width), the height as 6~cm.\label{fig:demo}} \end{figure} \noindent The following instructions are for \app{} only. Figures are entered in the \texttt{figure} or \texttt{figure*} environments, the latter being intended for double-column figures in two-column (preprint) format. Both environments produce identical results for manuscripts and camera-ready. The AGU provides a command \verb!\figurewidth! to specify the {\em width of the camera-ready caption\/}; if it is omitted, the caption width is the normal column width. There is a limited number of allowed values as arguments: 20~pc (the default single-column width), 35~pc, and 41~pc. (For {\em Radio Science\/} with \texttt{radga}, the values are 19, 33, and 38~pc.) JGR is still demanding that all figure captions be printed twice, once in width 20 and again in 35~pc. To enable this, give \verb!\doublecaption{35pc}! somewhere in the document, preferrably in the preamble so you notice it. The standard AGU package says that a \texttt{figure} environment should contain only an optional \verb!\figurewidth! command and a compulsory \verb!\caption! command, and nothing else. \app{} allows real figure contents to be included, but packed in a special \verb!\figbox!. This command takes three arguments: the width and height of the box, and the figure contents. The contents may be merely a note about what figure is to be pasted here, or a diagram made with \texttt{picture} or \textsc{Pic}\TeX, or an imported figure from other software, such as an encapsulated PostScript\footnote{PostScript is registered trademark of Adobe-Systems Incorporated.} file. An example of the input text for a figure is: \begin{verbatim} \begin{figure*} \figurewidth{35pc} \figbox{35pc}{12cm}{\epsfysize=10cm \epsfbox{myfig.eps}} \caption{A plot of Y versus X for various times\label{fig:my}} \end{figure*} \end{verbatim} (The commands \verb!\epsf...! require the style option \texttt{epsf} and the PostScript driver \texttt{dvips} of Tomas Rokicki.) A sample result is shown in Figure~\ref{fig:demo}. The \verb!\figbox! command reserves a framed box of the specified size and centers the contents both horizontally and vertically. It makes use of the standard \LaTeX{} \verb!\framebox! command, which can be customized with the parameters \verb!\fboxrule! and \verb!\fboxsep!. The rule may be suppressed by setting the former to {\tt0pt}. Plates are made up in exactly the same way as figures but with the \texttt{plate} and \texttt{plate*} environments. These are not part of standard \LaTeX, but have been added for AGU publications. In place of \verb!\figurewidth!, one must use \verb!\platewidth!; however, \verb!\figbox! works for plates as well. \subsection{Tables} \noindent The following instructions are for \app{} only. Tables function somewhat differently from figures and plates because their contents will always be printed. Thus there is no equivalent of \verb!\figbox! for tables. Tables are constructed with the \LaTeX{} \texttt{tabular} or \texttt{tabbing} environments, as described in the manuals. To make them into floats, they must be included in a \texttt{table} or \texttt{table*} environment. For \app, they are to be placed in the text where appropriate, and not at the end as in standard AGU\TeX. There is an AGU command \verb!\tablewidth! to set the width of the table caption. Allowed values are 20, 30, 41, 48--57~pc, except for {\em Radio Science\/} which has 19, 20, 37, 43--51~pc. The AGU package contains some additions to standard \LaTeX{} to put footnotes and comments in a table. These are \begin{quote} \verb!\tablenotemark{!{\em letter\/}\verb!}!\\ \verb!\tablenotetext{!{\em letter\/}\verb!}{!{\em text\/}\verb!}!\\ \verb!\tablecomments{!{\em cmnt\_text\/}\verb!}! \end{quote} The footnotes are numbered with lowercase letters which the author must enter explicitly. The {\em cmnt\_text\/} is explanatory material that is printed below the table. These will all work with \app{} as well. AGU\TeX{} also provides an additional table-making environment, called \texttt{planotable}, for tables that may be continued over several pages. This too works with \app. \begin{planotable}{lcc} \tablewidth{20pc} \tablecaption{Coordinates of stations \label{tab:coords}} \tablehead{\colhead{Station} & \colhead{$\theta$\tablenotemark{\it a}} & \colhead{$\phi$\tablenotemark{\it b}}} \tablenotetext{\it a}{Latitute, north $>0$} \tablenotetext{\it b}{Longitude, east $>0$} \tablecomments{Taken from Broodey [1976]} \startdata Brixstone & $45^\circ$ & $90^\circ$ \nl Wilstone &$-45^\circ$ &$-50^\circ$ \nl Tipstone & $56^\circ$ &$124^\circ$ \end{planotable} The \texttt{planotable} environment is encouraged by AGU, because it automatically formats the tables with the three horizontal rules that they want: after the title, after the column headings, and after the table data. A typical example would look like \begin{verbatim} \begin{planotable}{lcc} \tablewidth{20pc} \tablecaption{Coordinates of stations \label{tab:coords}} \tablehead{\colhead{Station} & \colhead{$\theta$\tablenotemark{\it a}} & \colhead{$\phi$\tablenotemark{\it b}}} \tablenotetext{\it a}{Latitute, north $>0$} \tablenotetext{\it b}{Longitude, east $>0$} \tablecomments{Taken from Broodey [1976]} \startdata Brixstone & $45^\circ$ & $90^\circ$ \nl Wilstone &$-45^\circ$ &$-50^\circ$ \nl Tipstone & $56^\circ$ &$124^\circ$ \end{planotable} \end{verbatim} The result is shown in Table~\ref{tab:coords} Additional commands possible are \begin{description} \item[\ttfamily\bsl tablebreak] to force a page break in the middle of table; \item[\ttfamily\bsl nodata] for table elements that are empty; \item[\ttfamily\bsl cutinhead] to add new heading centered across whole table. \end{description} \section{Citations and List of References} The great disappointment in AGU\TeX{} is the lack of a decent author-year citation scheme and \btx{} style file. This is corrected with \app, which also provides the bibliography style file \texttt{agu.bst} along with the interfacing to use it correctly. Even if one does not make use of \btx{} to generate the list of references, one may type it in oneself as a \texttt{thebibliography} environment. The form of the entries must be observed, however. \begin{verbatim} \begin{thebibliography}{} %<-- Note {} \bibitem[Smith {\it et al.}(1992)]{smi92} Smith, J. G., P. G. Jones, and F. H. Weston, Some results, {\it J. Strange Results}, {\it 32}, 345--350, 1992 \bibitem . . . \end{thebibliography} \end{verbatim} Each \verb!\bibitem! entry contains in square brackets the text that should appear in the citation, {\em but with the year in round parentheses}. Following that is the {\em key\/} to refer to the citation, here \texttt{smi92}. This is also the key that is used to identify a reference in a \btx{} database. Of course, it is much easier to make up such a database and let \btx{} generate the \texttt{thebibliography} environment. This is done with commands \begin{quote} \verb!\bibliographystyle{agu}!\\ \verb!\bibliography{!{\em database\/}\verb!}! \end{quote} where {\em database\/} is the name of the bibliographic database file(s) that are to be searched by \btx. (The \btx{} program must also be run after at least one \LaTeX{} processing, and then \LaTeX{} must be run at least two times more.) In the main text, the \verb!\cite! command is used almost as in standard \LaTeX{} to print the citation, but with the following variations: \\[1ex] \begin{tabular}{l@{~$\Rightarrow$~}l} \verb!\cite{smi92}! & Smith {\it et al.} [1992] \\ \verb!\cite[]{smi92}! & [Smith {\it et al.}, 1992] \\ \verb!\cite[p.~3]{smi92}! & [Smith {\it et al.}, 1992, p.~3]\\ \verb!\cite[see][]{smi92}! & [see Smith {\it et al.}, 1992] \end{tabular}\\[1ex] Note that the use of optional arguments is somewhat different from that of normal \LaTeX{} where only a single argument in square brackets is allowed to place a note \emph{after} the citation. Here one optional argument behaves that way, but if there are two, then the first goes before, the second after the citation. This is because in author-year citations one often wants to say [see Smith {\it et al.}, 1992, and references therein]. Multiple citations may be made with one \verb!\cite! command:\\[1ex] \begin{tabular}{l@{~$\Rightarrow$~}l} \verb!\cite[]{smi92,jam89}! & [Smith {\it et al.}, 1992; \\ \multicolumn{1}{c}{} & \quad James, 1989]\\ \verb!\cite[]{smi89,smi92}! & [Smith {\it et al.}, 1989, 1992] \end{tabular} \section{Other Features} These are the major features of \app, but there are a few more nice frills that are provided at no extra charge. \subsection{Improved Preprint Title} The AGU\TeX{} style \texttt{agupp} puts the title, authors, and abstract on a titlepage and starts the two-column mode with the first \verb!\section! command on the next page. Frankly, this looks cheap. By selecting the option \texttt{twocolumn} explicitly, the title and authors are put on the same page as the opening text, but the abstract goes into a narrow column. (This is actually standard \LaTeX, so one should not complain.) \app, on the other hand, puts the title, author, and abstract all across the two columns of the starting text. This is illustrated on the first page of this paper. Furthermore, the information in \verb!\lefthead! and \verb!\righthead! are added in the running heads; the option \texttt{twoside} may be used to effect here. This looks far more professional, more like a reprint than a preprint. \subsection{Supplemental Abstract} JGR requires an additional abstract with the paper number for printing in the JGR-Space Physics Subsets. By including the declaration \begin{quote} \verb!\extraabstract! \end{quote} anywhere in the paper (preferrably in the preamble), this will be printed automatically as the very last page of the camera-ready copy. For other versions, it does nothing, so that it may be left in all the time. \subsection{Sublabelling} Sometimes it is required to label some equations, figures, or tables as 4a, 4b, 4c, \dots, that is, to sublabel them. This can be done with the pair of commands \begin{quote} \verb!\sublabon{!{\em counter\/}\verb!}!\\ \verb!\sublaboff{!{\em counter\/}\verb!}! \end{quote} where {\em counter\/} is one of \texttt{equation}, \texttt{figure}, \texttt{plate}, or \texttt{table}. For example, \begin{verbatim} \sublabon{figure} \begin{figure} \caption{Caption of fig. 4a} \end{figure} \begin{figure} \caption{Caption of fig. 4b} \end{figure} \sublaboff{figure} \begin{figure} \caption{Caption of fig. 5} \end{figure} \end{verbatim} The \verb!\sublabon! contains an implicit \verb!\sublaboff! so it is not necessary to turn the sublabelling first off then on again in order to step the main counter: a single \verb!\sublabon! will do the job. AGU\TeX{} provides a \texttt{mathletters} environment that is equivalent to \verb!\sublabon{equation}!. There is no reason not to use this with \app{} too. \subsection{Balancing Two Columns} An annoying thing about the \LaTeX{} two-column mode is that the two columns on the last page are of different lengths. The \app{} package contains the command \verb!\balance! that activates the equalizing of columns of text on one page. Since this sometimes causes problems with floats and footnotes, it is better to issue it only on the last page. More precisely, it should appear somewhere in the text of the (unbalanced) left-hand column of the last page. Obviously, it only makes sense for preprints; in other modes, it has no effect, and may safely be left in the text. The counter command \verb!\nobalance! undoes the equalizing if this should be necessary. \subsection{Alternative Text for One and Two Columns} Often one needs to format text differently for the narrow columns of the preprint and camera-ready copy than for the wider columns of the manuscript. This is especially so for mathematical formulas. Since it is frustrating to have to alter the text every time one changes between manuscript and other output, \app{} provides the command \begin{quote} \verb!\iftwocol{!{\em two\_col\_text\/}\verb!}{!{\em one\_col\_text\/}\verb!}! \end{quote} to be able to keep the alternative versions always present. The {\em two\_col\_text\/} will be printed for preprints or camera-ready copy (which ultimately appears as double columns) and {\em one\_col\_text\/} for manuscripts. \section{Conclusions} The extension package \app{} adds features to AGU\TeX{} that have been gained over many years of practical experience of providing camera-ready copy to JGR and GRL. It has not been thought up out of the blue, but derives from feedback between the author, his colleagues, other users, and their interactions with the AGU copy editors, who often have been quite frustrating in their demands. The extension package is a distillation from the full-fledged \LaTeX{} styles \texttt{art-jgr} and \texttt{art-grl}. However, since \app{} is an extension to AGU\TeX, it simply assumes the layout specifications given to it, and so should be able to survive any future format alterations. It is the offspring of a battle-tested warrior and as such should be able to provide much more sturdy service. Its major advantages over standard AGU\TeX{} are \begin{enumerate} \item explicit numbering of many items can be avoided, \item figures, plates, and tables may be put into the text so that decent preprints are made with a minimum of changes (simply by changing an option in \verb!\documentstyle!), \item and yet figure captions and tables appear at the end as required for manuscripts and camera-ready copy, \item author-year citations may be done comfortably with \btx, \item appendices do not require explicit lettering, nor do they imply that tables must be explicitly numbered afterwards, \item sublabelling of counters other than \texttt{equation} is possible, \item alternative text may be inserted for narrow and wide columns so that, for example, math formulas always fit properly, \item the appearance of the first preprint page is improved, with title, authors, and abstract across the two columns of text, \item the two columns on the last page of a preprint may be nicely balanced. \end{enumerate} The main emphasis of \app{} is that explicit numbering should be avoided at all costs, and that the text should be able to output manuscripts, camera-ready copy, and preprints, with only a simple change to the \verb!\documentstyle! command. \appendix \section{Encapsulated PostScript} As mentioned here, it is possible to include encapsulated PostScript files in a figure or plate, but within a \verb!\figbox! frame. What makes a PostScript file `encapsulated' is the addition of certain standardized comments, the most important of which, for our purposes, is the {\em bounding box specifications}. This tells \LaTeX{} (more properly the \texttt{dvips} driver) how to scale and shift the diagram to make it fit into the reserved space. However, many application programs cheat on the bounding box. It is not trivial to calculate (I know, for I have written a program to do it), so many programs just give the size of the full page. In this case, the figure will not fit so well into \verb!\figbox!, which places the center of the specified bounding box in the center of the \verb!\figbox!. If your figures come out displaced, or too small, then this may be the problem. A bounding box adjustment is necessary. \balance \section{A Template for an \app{} Article} I present here the outline of a source file with the essential AGU\TeX{} and \app{} shown. \begin{small} \begin{verbatim} \documentstyle[twoside,agupp,aguplus]{article} % ALTERNATIVELY: %\documentstyle[agums,aguplus]{article} %\documentstyle[jgrga,aguplus]{article} % FOR LATEX2E: %\documentclass{article} % \usepackage{agu2e,agums,aguplus} % AGU++ OPTIONS %\printfigures % ADDS FIGURES AT END %\doublecaption{35pc} % CAPTIONS PRINTED TWICE %\sectionnumbers % TURNS ON SECTION NUMBERS %\extraabstract % ADDS SUPPLEMENTAL ABSTRACT %\afour % EUROPEAN A4 PAPER SIZE %\figmarkoff % SUPPRESS MARGINAL MARKINGS % AGUTeX OPTIONS AND ENTRIES %\tighten % TURNS OFF DOUBLE SPACING \lefthead{authors} \righthead{short title} \received{date1} \revised{date2} \accepted{date3} \journalid{JGRA}{Journal date} \articleid{page1}{page2} \paperid{94JZ12345} \ccc{0000-0000/00/94JZ-12345\$05.00} % \cpright{PD}{1994} % \cpright{Crown}{1994} % (No \ccc{} for Crown copyrights.) \cpright{AGU}{1994} \authoraddr{author1, full address} \authoraddr{author2, full address} \slugcomment{To appear ...} % END OF PREAMBLE \begin{document} \title{Full Title} % % TWO METHODS FOR GIVING THE AUTHORS % \author{author set 1} \affil{Institute 1} \author{author set 2\altaffilmark{1}} \affil{Institute 2} \altaffiltext{1}{Other institute} % ALTERNATIVELY: %\author{author1\altaffilmark{1} and % author2\altaffilmark{2,3}} %\altaffiltext{1}{Institute 1} %\altaffiltext{2}{Institute 2} %\altaffiltext{3}{Other institute} % % THE ABSTRACT % \begin{abstract} Text of abstract. \end{abstract} % % THE MAIN BODY OF TEXT % \section{Introduction}\label{sec:lab} \subsection{..} \subsubsection{..} % % FLOAT EXAMPLES % \begin{figure} \figbox{\hsize}{10cm}{Paste Fig Here} \caption{Caption text.\label{fig:lab}} \end{figure} \begin{plate*} \platewidth{35pc} \figbox{35pc}{12cm}{Paste Plate Here} \caption{Caption text.\label{pla:lab}} \end{plate*} \begin{table} \caption{Caption of table.\label{tab:lab}} \begin{tabular}{...} ..... \end{tabular} \end{table} % % CITATION EXAMPLES % As shown by \cite{smi92}, one may ... It has been shown \cite[]{smi92} that one may ... % % APPENDIX % \appendix \section{Some More Stuff} % % ACKNOWLEDGMENTS % \acknowledgments We wish to thank... % % BALANCING PREPRINT COLUMNS % \balance % % LIST OF REFERENCES (BIBTEX) % \bibliographystyle{agu} \bibliography{...} % % WITHOUT BIBTEX % %\begin{thebibliography}{} % \bibitem[author {\it et al.}(year)]{key} % reference text % % \bibitem[author1 and author2(year)]{key} % reference text % %\end{thebibliography} \end{document} \end{verbatim} \end{small} \begin{thebibliography}{} \bibitem[Kopka and Daly(1993)]{koda} Helmut Kopka and Patrick~W. Daly. \newblock {\em A Guide to \LaTeX, Document Preparation for Beginners and Advanced Users}. \newblock Addison-Wesley, Reading, MA, 1993. \bibitem[Lamport(1986)]{la} Leslie Lamport. \newblock {\em \LaTeX, a Documentation Preparation System}. \newblock Addison-Wesley, Reading, MA, 1986. \end{thebibliography} \end{document} %% %% End of file aguplus.tex.