%   *******************************
%   *     JGRMAN.TEX              *
%   *******************************
%  A manual for describing how to use 
%    styles art-jgr and art-grl
%
%  Patrick W. Daly
%  Max-Planck-Institut f\"ur Aeronomie
%  Postfach 20
%  D-37189 Katlenburg-Lindau
%  Germany
%
%  1993 July 23
%  Including the supplemental abstract for JGR as of January 1993
%  Revision of sublabelling with \sublabon{counter}
%
\documentstyle[a4,twocolumn]{art-jgr}
\def\BibTeX{{\rm B\kern-.05em{\sc i\kern-.025em b}\kern-.08em
    T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}}
\sloppy
\begin{document}
\markright{P. W. Daly: The \protect\LaTeX\ Document Styles 
{\protect\tt art-jgr} and {\protect\tt art-grl}}
\title{The L\kern-.36em\raise.3ex\hbox{\large\bf A}\kern-.15em\TeX\ 
Document Styles {\tt art-jgr} and {\tt art-grl}}
\author{P. W. Daly\\
Max-Planck-Institut f\"ur Aeronomie, D--37191 Katlenburg-Lindau, Germany}
\date{1993 July 23}

\maketitle

\begin{abstract}
Two \LaTeX{} document styles have been written for making camera-ready copy for
GRL and JGR publications.  These styles may also be used to produce
manuscripts for submission as well as two-column preprints that look just like
reprints.  A bibliography style has been designed for use with \BibTeX\ so
that the references may be called from a data base and formatted as the
journals desire. This work describes how the styles are to be called, how they
differ from the normal article style, and what additions they present.
\end{abstract}

\section{Introduction}

The normal \LaTeX\ article style produces results that do not conform to the
standards of JGR. Since it is possible to produce camera-ready copy to be
sent to JGR and GRL, at prices substantially reduced over those for text set
by the publisher himself, it is worthwhile having the requirements for the
publisher's style pre-programmed in the computer. This has been accomplished. 

The names of the styles are {\tt art-jgr} and {\tt art-grl} which function
almost identically except that the outputs differ according to the font and
size specifications of the two journals.  They can be used in three
variations, in draft mode for double-spaced manuscripts, in one-column
camera-ready copy, and in two-column mode for preprints.

\section{Changes from Earlier Versions}

The differences between these styles and the {\tt agujgr} and {\tt agugrl}
options of Stephen Gildea are
\begin{itemize}
\item in addition to camera-ready mode, there are also manuscript and preprint
modes available;
\item camera-ready copy may be blown up by 25\% to improve resolution;
\item the \verb!\cite! command has been modified to allow citations to be
either Daly {\it et~al.} [1989] or [Daly {\it et~al.}, 1989];
\item a {\tt plate} environment exists analog to {\tt figure};
\item figures, plates, tables are put in the text where they should appear,
but the captions and tables are moved automatically to the end;
\item the captions are printed twice, once for single and again for two
columns (new JGR requirement);
\item figures, plates, tables, and equations may take on sub-numbers (4a, 4b);
\item more up-to-date specifications from AGU are included.
\end{itemize}

Differences between these styles and my own earlier {\tt jgr} and {\tt grl}
options are:
\begin{itemize}
\item the abstract entered in an environment as is \LaTeX{} standard;
\item the {\tt figurecaptions} environment has been removed, for the captions
are now {\em automatically\/} brought to the last pages;
\item which means that figures, plates, and tables do not have to be moved
around between reprint and camera-ready modes.
\end{itemize}
I have kept the {\tt references} environment, although I feel it should be
removed since the (revised) \LaTeX{} {\tt thebibliography} environment will do.
Let's keep it for consistency, since it does not hurt to have it.

As of January 1993, JGR requires a supplemental abstract on a separate page,
with the paper number as heading. This is now done automatically (for {\tt
art-jgr}) but the problem is to duplicate the paper number. Until now, this
has been typed in explicitly in the \verb!\copyright! notice. Now a new
command \verb!\paperno{!{\em agu\_no\/}\verb!}! allows this number to be
entered. In the \verb!\copyright! notice, one may use \verb!\thepaperno! to
print \mbox{`Paper number xxxxxxxx'}.

\section{Calling the Document Styles}

To invoke either of the styles, the first line of the text file must be
\begin{verbatim}
\documentstyle[draft]{art-jgr}
\end{verbatim}
for the draft manuscript form, or
\begin{verbatim}
\documentstyle{art-jgr}
\end{verbatim}
for the camera-ready mode, or
\begin{verbatim}\documentstyle[twocolumn]{art-jgr}
\end{verbatim}
for the two-column preprint mode.

For the GRL versions, substitute {\tt art-grl} for {\tt art-jgr}.

Additional font size specifications {\tt11pt}, {\tt12pt}, may be included but
they have abnormal effects on the camera-ready versions: for {\tt art-jgr}, the
entire output is increased by 25\% in size, for further reduction by the
publisher; for {\tt art-grl} they have no effect at all. 

For the {\tt draft} mode, the output truly is 10, 11, or 12~pt according to
the type size option specified.

\subsection{Further Options}

A number of other options are available that are not normal to \LaTeX:
\begin{description}
\item[\tt a4] changes the length of the text to fit better on European A4
paper, otherwise the American letter size is standard;
\item[\tt secnum] normally JGR prefers the sections {\em not\/} to be numbered
and this is the standard for the styles; but with this option, section
numbering will be turned on (as is the \LaTeX{} norm).
\end{description}

\subsection{Page Styles}
If \verb!twoside! is given, then even and odd pages (or left and right pages, 
if you will) have different margins and different running heads. These are 
given by:
\begin{verbatim}
\markboth{Left page heading}{Right page heading}
\end{verbatim}
The standard page style is {\tt myheadings} and not the {\tt plain} of normal
\LaTeX.

The margins are so set that when the pages are photocopied two-sided, the text
on both sides of the sheet should match up. This works for European paper 
only if the {\tt a4} option has been given.

\section{The Title}
The title of the article is prepared a little differently from the normal 
article mode. Two items {\em must} be declared before \verb!\maketitle! is 
given, and two others {\em may} be given. The compulsory items are:
\begin{verbatim}
\title{Title of the Article}
\author{Author list 1 \\ Institute 1 \and
        Author list 2 \\ Institute 2 \and ...}
\end{verbatim}
There are two methods of listing the authors and their institutes. In one case, 
as shown above, all those authors belonging to one institute are listed in one 
line, the name of the institute goes on the next line. Then the authors from 
the next institute are listed, followed by their institute name, and so on. 
The \verb!\\! is used to separate the lines (and to switch the typeface 
between {\sc small caps} and {\it italics\/}.

The second method is to put all authors in one list and use footnotes to show 
the institute names. This is carried out as follows:
\begin{verbatim}
\author{P. W. Daly\titlemark{1} and A. N. 
        Other\titlemark{2}}
\titlenote{\titlemark{1}Max-Planck-Institut 
           f\"ur Aeronomie\\
           \titlemark{2}Some Other Institute}
\end{verbatim}
Footnotes may be included in the first method by using the same procedure. 
This is necessary if one author has a second address, of if some other note 
must be added to his name.

The optional declarations are:
\begin{verbatim}
\date{Additional Note about Submission 
      or Date of Production}
\paperno{XXXXXXXXX}
\copyright{Copyright 1992 by the 
   American Geophysical Union. \\[1ex]
 \thepaperno.\\
 XXXX-XXXX/XX/XXXX-XXXX\$XX.XX}
\end{verbatim}

The \verb!\paperno! command allows the AGU paper number to be inserted for
inclusion in the supplemental abstract ({\tt art-jgr} only). This number may
then be referred to once again with the command \verb!\thepaperno!, say in
the copyright text, thus avoiding typing the number twice.
The copyright is most useful only for camera-ready copy for the journals.

The title is generated with the \verb!\maketitle! command. The {\tt titlepage}
option and environment are not effective, since an extra page is automatically 
used for title and abstract only in the {\tt draft} mode.

\section{Abstract} 
The abstract is typed in in an environment named {\tt abstract} that comes
immediately after the \verb!\maketitle! command. (This is different from the
practice in my previous {\tt jgr} option, but conforms more to standard
\LaTeX.) 

Some peculiar things may happen if an abstract is missing. However, it is safe
to say that everything will function properly if \verb!\maketitle! is followed
either by \verb!\begin{abstract}! or by \verb!\section!.

\section{Sectioning}

After the title has been done, then the main body of the text can be written 
as usual. There are 4 levels of sectioning allowed. These can be called 
using \verb!\section{Heading}!, as in the present section.

\subsection{The Subsection}

The next level is called up with \verb!\subsection{Heading}! In most cases
these two levels are perfectly sufficient. Incidently, section numbers will not
be printed unless the option {\tt secnum} has been chosen. In that case, they
may be suppressed with \verb!\section*! and \verb!\subsection*!.

\subsubsection{The Subsubsection.}

The third and fourth levels are not used very often, but
they do exist if they are needed.
The third level is called with \verb!\subsubsection{Heading.}!,
including the final period in \verb!{Heading.}!

\paragraph{The Paragraph:}

Should the fourth level be needed, it is called with 
\verb!\paragraph{Heading:}!, including the colon in \verb!{Heading:}!

\section{Additional Features}

Some additional features have been added to help finish off the paper. These 
are necessary for the special formats needed for the Figure Captions,
Acknowledgements, References, the Author Address List, the Received, Accepted
dates, and to tidy up the two columns on the last page.

\subsection{Figures}
Figures should be put in a {\tt figure} environment at that
point in the text where they are first referred to. Each {\tt figure} or {\tt
plate} environment must contain {\em one and only one\/} \verb!\caption!
command!
\begin{verbatim}
\begin{figure}
  \vspace{6cm}
  \caption{\label{fig:samp1}
    Text of the Figure caption...}
\end{figure}
\end{verbatim}
In this case, the size of the figure is 6~cm. One can also give 
\verb!\begin{figure*}! and \verb!\end{figure*}! for figures that are the width 
of two columns. In the text, one refers to the Figure using the label, e.g.
\begin{verbatim}
...In Figure~\ref{fig:sample} the ...
\end{verbatim}
In {\tt twocolumn} mode, space will be left for the diagram to be pasted in,
and the caption is printed below it.

In camera-ready and {\tt draft} modes, a marginal note appears at that point
in the text with the figure number printed in it. The captions themselves
are printed on a separate page at the end of the paper. For camera-ready mode,
the captions are printed twice, once each for single and double column widths
so that the JGR cutters and pasters can decide which they prefer. Here the
\verb!\vspace! commands are ignored.

Alternatively, one may use {\tt picture} environment to generate a figure, or
a skeleton figure, or even import a plot file if the drive supports
importation. In these cases, only the caption is printed on the caption page,
but the figures may optionally be outputted at the very end if the command
\verb!\printfigures! is given in the preamble. These extra pages are not
numbered, contain one figure or plate per page, and have a width of 15~cm.
(For {\tt twocolumn}, this command has no effect, since the figures will be
outputted in the text.)

Experience reveals that the AGU copy-editor asks that the marginal notes be
placed beside the actual first reference to the figure. However, it is normal
practice to put the {\tt figure} environment nearby between paragraphs, for
readability. That is where the marginal note then appears. I recommend
ignoring the copy-editor's remarks, since he is probably not aware of the
reason for the displacement. And it is not all that important.

However, if this displacement does disturb you, you must put the environment
in the middle of a paragraph right beside the first reference, or you may turn
off the marginal notes with \verb!\figmarkoff! and write them in by hand. The
corresponding command \verb!\figmarkon! turns them back on again.

A further useful command for sizing the figures is \verb!\iftwocol{!{\em
yes\/\verb!}{!no\/}\verb!}!, which executes the text {\em yes\/} in {\tt
twocolumn} mode, otherwise the text {\em no}. This is needed, since in {\tt
twocolumn} the figures are to fit inside a column width of 8.4~cm while the
extra pages at the end have a width of 15~cm. For example:
\begin{verbatim}
\printfigures
\begin{document}
. . . . . . .
\begin{figure}
  \setlength{\fboxsep}{0pt}
  \iftwocol{\unitlength=1cm}{\unitlength=1.8cm}
  \fbox{\begin{picture}(8,6)
    \put(4,3){\makebox(0,0){Paste Here}}
  \end{picture}}
  \caption{\label{fig:samp1}
    Text of the Figure caption...}
\end{figure}
\end{verbatim}
will make a framed box of $8\times6$~cm in {\tt twocolumn}, but in the other
modes, it makes the box 1.8 times as large ($14.4\times10.8$~cm), which will
then fit in the 15~cm of the special figure pages.

\subsection{Tables}
Tables are treated in exactly the same way as figures: they are typed in in
environments at that point in the text where they should appear, but in
camera-ready and {\tt draft} modes, only a marginal note is printed and they
actually come at the very end, after the figure captions.

\subsection{Plates}
In addition to the \verb!figure! and \verb!table! environments, there is also 
a \verb!plate! environment available. In JGR, coloured plates are numbered 
independently from the figures, and are labelled ``Plates''. The \verb!plate! 
environment is used exactly as the \verb!figure! environment. 
The plate captions are printed at the end along with the figure captions.

\subsection{The Acknowledgements}
This environment is entered with
\begin{verbatim}
\begin{acknowledgements} The author thanks 
  all his friends for their help.
\end{acknowledgements}
\end{verbatim}
For JGR, this types the text in a smaller typeface, and adds the word 
``{\sl Acknowledgments\/}'' at the beginning. Notice the variations on 
spelling. Both British and American versions are accepted as the name of this
command but only the American form is outputted.

\subsection{The References}
If \BibTeX\ is {\em not} used (see below), then the references may be typed in
with the \verb!references! 
environment: \verb!\begin{references}...\end{references}!
 Each Reference is followed by a blank line, or
 \verb!\par!, or by \verb!\\!.

The standard \LaTeX{} environment {\tt thebibliography} may also be used, with
each reference preceded by \verb!\bibitem{!{\em key\/}\verb!}! as in
\begin{verbatim}
\begin{thebibliography}{} %<-- Note extra {}
  \bibitem{key1} ...
  \bibitem{key2} ...
\end{thebibliography}
\end{verbatim}
The keys here are simply dummies. They may be blanks if one wishes, but then
there will always be a warning message that some labels have changed.

Even if \BibTeX{} is not used, one may still use the 
the \verb!\cite! command for citations in the text.
However, because 
the natural science journals use a different form of referencing than the 
\LaTeX\ designers, it was necessary to change the use of \verb!\cite! 
slightly. The citation may be printed differently depending on how
\verb!\cite! is given:
%
\begin{center}
\begin{tabular}{ll}
\multicolumn{1}{c}{in text} & \multicolumn{1}{c}{printed}\\[1ex]
\verb!\cite{daly89}! & Daly {\it et al.} [1989]\\
\verb!\cite[]{daly89}! & [Daly {\it et al.}, 1989]\\
\verb!\cite[e.g. ]{daly89}! & [e.g.~Daly {\it et al.}, 1989]\\
\end{tabular} \end{center}
%
In order for this to work, {\tt thebibliography} must be entered as:
\begin{verbatim}
\begin{thebibliography}{} 
  \bibitem[Daly {\it et~al.}(1989)]{daly89}
%         |--------citation-------||-key--|
    Daly, P.~W., E. Kirsch, ... %<-Reference text
  \bibitem[..]{..}
  . . . . .
\end{thebibliography}
\end{verbatim}
In the square braces the form of the citation in the text is given, whereby
the year is given {\em in paratheses ()\/}! This is vital if \verb!\cite! is
to operate as described above. In the curly brackets the same key appears as
is used with \verb!\cite!.

A very convenient way to generate {\tt thebibliography} is with the \BibTeX{}
program. This is not necessary, but it saves doing all the fiddly work of
typing the references just right. At that location in the text where {\tt
thebibliography} is to appear, simply give
\begin{verbatim}
\bibliographystyle{agu}
\bibliography{filename1,filename2,...}
\end{verbatim}
where the file names are those of the bibliographies (extension {\tt.bib}).
How these files are to be structured is described in the \LaTeX{} and \BibTeX\
manuals.


\subsection{Sublabels}
In order to number equations, figures, plates, and tables automatically with 
sub-numbers (e.g.\ 4a, 4b, 4c) use the commands \verb!\sublabon! and 
\verb!\sublaboff!. These commands take as argument the name of the counter
that is to be subnumbered, i.e. {\tt equation}, {\tt figure}, {\tt plate}, or
{\tt table}. The on and off versions bracket the objects that are to be 
labelled with the same number but different letters. For example,
\begin{verbatim}
\sublabon{figure}
\begin{figure}
  \caption{Text of Fig. 4a}
\end{figure}
\begin{figure}
  \caption{Text of Fig. 4b}
\end{figure}
\sublaboff{figure}
\end{verbatim}

These commands also work for the \verb!equation! environment in the same way. 
For the \verb!eqnarray! environment, some care must be taken. The 
\verb!\sublabon! command is to be given {\em in} the first equation to be 
bracketted, before the \verb!\label! and \verb!\\! commands, while the 
\verb!\sublaboff! command is given after the \verb!\\! of the last equation 
in the group. If necessary, it must come after \verb!\end{eqnarray}!.
\begin{verbatim}
\begin{eqnarray}
  x & = & a \label{eq:x}\\%--> 1
  \sublabon{equation}
  y & = & b \label{eq:y}\\%--> 2a
  z & = & c \label{eq:z}\\%--> 2b
  \sublaboff{equation}
  w & = & d \label{eq:w}  %--> 3
\end{eqnarray}
\end{verbatim}

If two groups appear adjacently, it is only necessary to give 
\verb!\sublabon! between them.

(Note: in older versions the commands \verb!\sublabelon! and
\verb!\sublabeloff! were used instead. They took no arguments, and activated
all four counters simultaneously. They have been retained for consistency but
should not be used any more.)

\subsection{Balancing Columns}
In {\tt twocolumn} mode, the two columns on the last page can be balanced,
that is, made to be of equal length, by giving \verb!\balance! somewhere on
the last page within the first column. It could also be given earlier, but
sometimes the balancing routine produces strange effects, such as putting an
extra line of text underneath a figure caption at the bottom of a column. 

\balance

\section{Special JGR and GRL Commands}

The following environments and commands were designed to meet the specific
demands of JGR and GRL.

\subsection{The Author Address List}

Following the references, JGR wants a list of the authors' names and full 
addresses. This is done with 
\begin{verbatim}
\begin{authorlist} 
... 
\end{authorlist}
\end{verbatim}
Each entry in this list is terminated with a blank line, \verb!\par!, or 
\verb!\\!. 

\subsection{Dates Received and Accepted}

To give the dates of reception, revision, and acception, use the command
\begin{verbatim}
\received{Date received}{Date revised}{Date 
          accepted}
\end{verbatim}
If \verb!{Date revised}! is left blank (\verb!{}!), then it is not printed.

\subsection{Running Head}

JGR requires a short title to be printed for each page that will appear in the 
journal. This is given after the Dates Received, as follows:
\begin{verbatim}
\runninghead{Daly et al.: A JGR Option}{5}
\end{verbatim}
The first argument is the running title, the second is the number of times it 
will be printed. This only functions in one-column mode. For two columns, this 
command is simply ignored. 

Do not confuse this heading with those given earlier with 
\verb!\markboth!. Those are the ones actually printed at the top of your page. 
The running heads that are given here are printed in the text for JGR to cut 
out and paste at the top of {\em their} page.

\section{What Is Missing}

Certain standard features of \LaTeX{} {\tt article} have been removed, most
notably:
\begin{verbatim}
   titlepage
   \tableofcontents
   \listoffigures
   \listoftables
   \part
\end{verbatim}


\section{Examples}

Included in this package is a single sample article 
that may be outputted in a variety of ways simply by changing the
\verb!\documentstyle! command. It also illustrates the two different ways of
entering the authors' names in the title, one of which must be commented out.
Similarly, the references are included with and without \BibTeX, with the
`other' method rendered ineffective. A bibliography file {\tt sample.bib} 
and the bibliography style file {\tt agu.bst} are
also included in the package so that one may experiment with it.

In addition to this manual, there is also a guide where the major points about
the application are listed in a more compact form.

\begin{acknowledgements} I am indebted for several ideas from the {\tt
agujgr} option of Stephen Gildea, especially for re-defining {\tt
thebibliography} to deal with the natural sciences referencing system. The
bibliography style {\tt agu.bst} is also a modification of his {\tt
natsci.bst}. 
I also thank all the people in my Institute who have been testing the earlier
style options. It was only through their relaying complaints from the AGU to
me that I was able to discover many style details that are not in their public
description.
\end{acknowledgements}

\end{document}
