path: root/Master/texmf-dist/doc/latex/ascelike/ascexmpl.tex

%
\documentclass[Proceedings]{ascelike}
%
% Feb. 14, 2013
%
% Some useful packages...
%
%\usepackage{graphicx}
%\usepackage{subfigure}
%\usepackage{amsmath}
%\usepackage{amsfonts}
%\usepackage{amssymb}
%\usepackage{amsbsy}
%\usepackage{times}
%
%
% Place hyperlinks within the pdf file (works only with pdflatex, not latex)
% \usepackage[colorlinks=true,citecolor=red,linkcolor=black]{hyperref}
%
%
% NOTE: Don't include the \NameTag{<your name>} if you have selected 
%       the NoPageNumbers option: this leads to an inconsistency and
%       a warning, and the NameTag is ignored.
\NameTag{Kuhn, Feb. 14, 2013}
%
%
\begin{document}
%
% You will need to make the title all-caps
\title{STYLE FILES FOR ASCE-LIKE DOCUMENTS}
%
\author{
Matthew R. Kuhn%
%
% ---- The first of two styles for addresses: using footnotes and \thanks ----
\thanks{
Dept.\ of Civil Engrg.,
Donald P.\ Shiley School of Engrg., Univ.\ of Portland, 
5000 N.\ Willamette Blvd.,
Portland, OR  97203. E-mail: kuhn@up.edu.},
\ Member, ASCE
%
% Adding a second author with the same affiliation (still using \thanks):
%  \\
%  Ima Colleague,\footnotemark[1] Member, ASCE%
%
% Adding another author with a different affiliation.  I have found that 
% the \and command doesn't quite work, so just use "and", as in the following 
% \\
% and
% Younyee Kuhn%
% \thanks{Flourishing wife of same.},%
% \ Not a Member, ASCE
%
% ---- The second of two styles for addresses: below names, no footnotes ----
%
% For this style, don't use \thanks.  Instead, use superscripts and carriage
% returns ("\\").  It's not pretty, but neither is the new ASCE proceedings
% style.  Something like the following:
%
% Matthew R. Kuhn$^1$, Member, ASCE\\[1ex]%
%
% $^1$\parbox[t]{5.75in}{Dept.\ of Civil Engrg.,
% Donald P.\ Shiley School of Engrg., Univ.\ of Portland, 
% 5000 N.\ Willamette Blvd., Portland, OR  97203. kuhn@up.edu.}
}
%
\maketitle
%
\begin{abstract}
This document was produced with the \LaTeX\ typesetting program
using the document class ``\texttt{ascelike.cls}'' and the
example file ``\texttt{ascexmpl.tex}''.
The reference section on page~\pageref{section:references}
was produced with the \textsc{Bib}\TeX\ style ``\texttt{ascelike.bst}''
and the database ``\texttt{ascelike.bib}''.
The objective of these files is manuscripts that roughly comply with the
guidelines of the American Society of Civil Engineers.
The document class
produces either double-spaced manuscripts for journal submissions or
manuscripts for conference proceedings, either in ASCE's older or newer
styles.
This document serves as a brief guide to \texttt{ascelike.cls},
as well as a test of the output that is produced
by the input file \texttt{ascexmpl.tex}.
The package is freely available under the LaTeX 
Project Public License, version 1.1
\end{abstract}
%
% Some keywords, using a new command: \KeyWords{}
%
\KeyWords{\LaTeX, ASCE, document class, 
          ascelike.cls~(version 2.3),
          ascelike.bst~(version 2.2).}
%
\section{Introduction}
The class file ``\texttt{ascelike.cls}''
produces manuscripts that roughly comply with the
guidelines of the American Society of Civil Engineers (ASCE).
The \texttt{ascelike.cls} document class, the 
bibliographic style \texttt{ascelike.bst}, and
example files are available on the \texttt{ctan}
web-site \cite{Kuhn:2011a}.
Although the files are \emph{not} produced by ASCE, its agents,
or employees, \texttt{ascelike.cls} is now referenced on
the ASCE web-site.
\par
This document was created from the file
``\texttt{ascexmpl.tex}'', which also serves to test the 
\texttt{ascelike.cls} and \texttt{ascelike.bst} system.
\par
The program \texttt{ascelike.cls} is distributed under the
terms of the LaTeX Project Public License Distributed,
available from the CTAN archives;
either version 1.1 of the License, or any later version.
If you modify
\texttt{ascelike.cls}, you should rename it so that ``altered''
copies are not later proliferated.
\par
The document class ``\texttt{ascelike.cls}'' requires the following
supplementary files:
\begin{itemize}
\item
\texttt{ifthen.sty}, 
\item
\texttt{setspace.sty}, 
\item
\texttt{endfloat.sty}, and 
\item
\texttt{lineno.sty}.
\end{itemize}
\emph{Without these files,} \texttt{ascelike.cls} \emph{won't work}.
These files are typically included in \LaTeX\ distributions, such as the
\textsf{TexLive}, \textsf{MikTex}, and \textsf{MacTex} distributions.
All of these files are freely available
from the Comprehensive \TeX\ Archive Network (CTAN) archive,
through \verb+http://www.ctan.org+ or
\verb+http://www.tug.org+, although they may need to be unbundled from
a \verb+*.dtx+ file.
If one of these files is not installed as part of your \TeX\ system,
then download the file from the CTAN archive and place it in the same folder
as your manuscript files.
On Debian GNU/Linux systems, the \texttt{setspace.sty}
file is part of the \texttt{texlive-latex-re\-com\-mended} package;
the \texttt{endfloat.sty} 
file is part of the \texttt{texlive-latex-extra} package;
and the \texttt{lineno.sty} 
file is part of the \texttt{texlive-humanities} package.
\par
In addition to \texttt{ascelike.cls}, 
the file \texttt{ascelike.bst} can be used with
the bibliographic tool \textsc{Bib}\TeX\ to produce ASCE-like 
reference citations and entries (with the weird use of
quotation marks around titles, etc.) \cite{Kuhn:2011a}.
An example bibliographic data base is given in the
supplementary file \texttt{ascexmpl.bib}.
\par
In addition to these essential files,
we have found the following packages very useful:
%
\begin{itemize}
\item
\texttt{graphicx.sty} and its companion files for incorporating
encapsulated post\-script (figure) files into the document
\item
\texttt{times.sty} for typesetting with Times fonts.
\item
\texttt{subfigure.sty} for arranging and numbering sub-figures
\item
\texttt{amsmath.sty} and its companion files for the AMS extensions
to mathematical formatting (\texttt{amsfonts.sty}, \texttt{amssymb.sty},
and \texttt{amsbsy.sty}).
\item
\texttt{url.sty} can be used to embed the underscore ``\_'' and
ampersand ``\&'' symbols with web addresses.
\end{itemize}
%
All of these packages are freely 
available from the CTAN archive, 
and they are included in most \LaTeX\ distributions.
%
\section{Input and Options}
You should
prepare your \verb+*.tex+ input file as a regular
\LaTeX\ file using the standard \texttt{article.cls} constructs,
but, of course, substituting \texttt{ascelike} for \texttt{article}
in the opening \verb+\documentclass+ command.
You will likely need to specify a number of options as described below.
In addition, \texttt{ascelike} provides two new commands: \verb+KeyWords+ and
\verb+NameTag+, both of which are described further below.
\par
The document class \texttt{ascelike.cls} provides several options given
below.
The \verb+Proceedings|+\-\verb+Journal|+\-\verb+NewProceedings+ 
option is the most important;
the other options are largely incidental.
%
\begin{enumerate}
\item
Options
\verb+Journal|+\verb+Proceedings|+\verb+NewProceedings+ specify the overall 
format of the output man\-u\-script.  
\par
\texttt{Journal} produces double-spaced manuscripts for ASCE journals.
As default settings, it places tables and figures at the end of the manuscript 
and produces lists of tables and figures.  
It places line numbers within the left margin.
All of these default settings can altered with the options that are 
described below.
It also numbers the appendices with Roman numerals and produces 
proper headings for
sections, subsections, subsubsections, appendices, and abstract.
It produces the proper page margins and numbers the pages.
%
\par
\texttt{Proceedings} produces older-style camera-ready single-spaced 
manu\-scripts for ASCE conference proceedings.  
The newer ASCE style is enacted with the \verb+NewProceedings+ option.
As default settings, 
\verb+Proceedings|+ places figures and tables within the text.  
It does not place line numbers within the left margin.
Pages are numbered, and the bottom left corner can be ``tagged'' with
the author's name (this can be done by inserting the command
\verb+\NameTag{<+\emph{your name}\verb+>}+ within the preamble of your
document).
All of these default settings can be altered with the options that are
described below.
\verb+Proceedings|+ also produces the proper page margins as
given on the old shiny, 
camera-ready paper (with the light blue lines) 
supplied by ASCE. 
It produces proper headings for
sections, subsections, subsubsections, appendices, and the abstract.
%
\par
\texttt{NewProceedings} produces newer-style single-spaced 
manu\-scripts for ASCE conference proceedings, as shown on the 
ASCE website (\emph{ca.} 2013).  
The older ASCE style is enacted with the \verb+Proceedings+ option.
As default settings,
\verb+NewProceedings+ places figures and tables within the text.
It does not place line numbers within the left margin.
Pages are not numbered.  
If desired, the bottom left corner can be ``tagged'' with
the author's name (this can be done by inserting the command
\verb+\NameTag{<+\emph{your name}\verb+>}+ within the preamble of your
document).
All of the default settings can be altered with the options that are
described below.
\verb+NewProceedings+ also produces the proper page margins as
specified by ASCE.
It produces proper headings for
sections, subsections, subsubsections, appendices, and the abstract.
To create author addresses that do \emph{not} appear as footnotes,
use the kluge that is described on page~\pageref{address.kluge}
and in this \texttt{ascexmpl.tex} example.
%
\item
Options \verb+BackFigs|InsideFigs+ can be used to override 
the default placement of tables
and figures in the \texttt{Journal}, \texttt{Proceedings}, and
\texttt{NewProceed\-ings} formats.
\item
Options \verb+SingleSpace|DoubleSpace+ can be used to override 
the default text spacing in the 
\texttt{Journal}, \texttt{Proceedings}, and
\texttt{NewProceedings} formats.
\item
Options \verb+10pt|11pt|12pt+ can be used to override the 
default text size (12pt).
\item
The option \texttt{NoLists} suppresses inclusion of lists of tables
and figures that would normally be included in the \texttt{Journal}
format.
\item
The option \texttt{NoPageNumbers} suppresses the printing of page numbers.
\item
The option \texttt{SectionNumbers} produces an automatic numbering of sections.
Without the \texttt{SectionNumbers} option, sections will \emph{not} be
numbered, as this seems to be the usual formatting in ASCE journals 
(note that the appendices will, however, be automatically
``numbered'' with Roman numerals).  
With the \texttt{SectionNumbers} option, sections and
subsections are numbered with Arabic numerals (e.g. 2, 2.1, etc.), but
subsubsection headings will not be numbered.  To change this default
depth of numbering when
the option \texttt{SectionNumbers} is invoked, insert the following commands
in the preamble of your document:\\[2mm]
\begin{tabular}{ll}
\verb!  \setcounter{secnumdepth}{1}! & Number sections only\\
\verb!  \setcounter{secnumdepth}{3}! & Number sections, subsections, \\
                                   & and subsubsections
\end{tabular}\\[2mm]
Even with the \texttt{SectionNumbers} option, you can use the ``starred''
form, \verb!\section*{ }!, to create a section heading without numbers.
This might be desirable for an Acknowledgements section at the end of
a paper.  Note, however, that the starred form will not suppress
the numbering of subsections or subsubsections.
\item
The options \verb+NoLineNumbers|LineNumbers+ can be used to override
the default use (or absence) of line numbers in the \texttt{Journal},
\texttt{Proceedings}, and
\texttt{NewProceedings} formats.
\end{enumerate}
%
\section{Sections, subsections, equations, etc.}
This section is included to explain and to 
test the formating of sections, subsections,
subsubsections, equations, tables, and figures.
Section heading are automatically made uppercase, which is great unless
your section heading contains mathematics, \verb+$<math stuff>$+.
If a heading does contain mathematics, you will need to modify
\texttt{ascelike.cls}, in particular the line containing the
\verb+\uppercase+ command.  
To force mathematics symbols to become 
bold within a section heading, try using
the \verb!\boldmath! command before the in-line math:
for example,
\verb!\boldmath$a_{i}=\sqrt{\beta}$!.
%
\subsection{An Example Subsection with math, \boldmath$a_{i}=\sqrt{\beta}$}
No automatic capitalization occurs with subsection headings; 
you will need to capitalize the first letter of each word,
as in ``An Example Subsection.''
%
\subsubsection{An example subsubsection}
No automatic capitalization occurs with subsubsections; 
you will need to capitalize only the first letter of subsubsection 
headings.
\par
And now we include an example of a displayed equation (Eq.~\ref{eq:Einstein})
%
\begin{equation} \label{eq:Einstein}
E = m c^{2} \;,
\end{equation}
%
a figure (Fig.~\ref{fig:box_fig}),%
%
\begin{figure}
\centering
\framebox[3.00in]{\rule[0in]{0in}{1.00in}}
\caption{An example figure (just a box).  
This particular figure has a caption with more information 
than the figure itself, a very poor practice indeed.
A reference here \protect\cite{Stahl:2004a}.}
\label{fig:box_fig}
\end{figure}
%
and a table (Table~\ref{table:assembly}).%
%
\begin{table}
\caption{An example table}
\label{table:assembly}
\centering
\small
\renewcommand{\arraystretch}{1.25}
\begin{tabular}{l l}
\hline\hline
\multicolumn{1}{c}{Assembly Attribute} &
\multicolumn{1}{c}{Values} \\
\multicolumn{1}{c}{(1)} &
\multicolumn{1}{c}{(2)} \\
\hline
Number of particles & 4008 \\
Particle sizes & Multiple  \\
Particle size range & $0.45D_{50}^{\:\ast}$ to $1.40D_{50}$ \\
Initial void ratio, $e_{\mathrm{init}}$ & $0.179$ \\
Assembly size & $54D_{50} \times 54D_{50} \times 54D_{50}$ \\
\hline
\multicolumn{2}{l}{$\ast$ $D_{50}$ represents the median particle diameter} \\
\hline\hline
\end{tabular}
\normalsize
\end{table}
%
Notice that the caption of Fig.~\ref{fig:box_fig} contains
a citation of a bibliographic item \cite{Stahl:2004a}.
This can lead to the following error message:
\begin{verbatim}
   ! Illegal parameter number in definition of \reserved@a.
   ! Missing control sequence inserted
\end{verbatim}
These errors are avoided by protecting citations within captions,
with the command \verb|\protect\cite{...}|.
%
\par
The command \verb+\KeyWords{<your key words>}+ can be used to produce
a labeled list of key words.  
It can be placed anywhere in the document and produces an unindented
paragraph of keywords at that location.
\par
The command \verb+\NameTag{<+\emph{your name}\verb+>}+ can be placed
within the preamble of your document, which will produce a name
and date tag in bottom left corner of the page.
Do not use \verb+\NameTag+ in combination with the \verb+NoPageNumbers+
option, as the former will be ignored.
%
\section{Citations and bibliographic entries}
When used together, \texttt{ascelike.cls} and \texttt{ascelike.bst}
produce APA~/ \emph{Chica\-go Manual of Style} citations in
name-date format.
The code in \texttt{ascelike.bst}
is a modification of the \texttt{chicago.sty} and
\texttt{chicago.bst} packages.
The following citation options are available:
\begin{itemize}
\item
\verb+\cite{key}+ produces citations with full author 
list and year \cite{Ireland:1954a}.
\item
\verb+\citeNP{key}+ produces citations with full author list and year, 
but without enclosing parentheses: e.g. \citeNP{Ireland:1954a}.
\item
\verb+\citeA{key}+ produces citations with only the full 
author list: e.g. \citeA{Ireland:1954a}
\item
\verb+\citeN{key}+ produces citations with the full author list and year, but
which can be used as nouns in a sentence; no parentheses appear around
the author names, but only around the year: e.g. \citeN{Ireland:1954a}
states that \ldots
\item
\verb+\citeyear{key}+ produces the year information only, within parentheses,
as in \citeyear{Ireland:1954a}.
\item
\verb+\citeyearNP{key}+ produces the year information only,
as in \citeyearNP{Ireland:1954a}.
\end{itemize}
%
\par
The bibliographic data base \texttt{ascexmpl.bib}
gives examples of bibliographic entries for different document types.
These entries are from the canonical set in the
ASCE web document ``Instructions For Preparation Of Electronic Manuscripts''
and from the ASCE web-site.
The References section of this document has been automatically created with
the \texttt{ascelike.bst} style for the following entries:
\begin{itemize}
\item a book \cite{Goossens:1994a},
\item an anonymous book \cite{Moody:1988a}, 
\item an anonymous report using \texttt{@MANUAL} \cite{FHWA:1991a}, 
%\item an anonymous newspaper story ("Educators" 1993), 
\item a journal article \cite{Stahl:2004a,Pennoni:1992a}, 
\item a journal article in press \cite{Dasgupta:2008a},
\item an article in an edited book using \texttt{@INCOLLECTION} \cite{Zadeh:1981a}, 
\item a building code using \texttt{@MANUAL} \cite{ICBO:1988a}, 
\item a discussion of an \texttt{@ARTICLE} \cite{Vesilind:1992a}, 
\item a masters thesis using \texttt{@MASTERSTHESIS} \cite{Sotiropulos:1991a},
\item a doctoral thesis using \texttt{@PHDTHESIS} \cite{Chang:1987a}, 
\item a paper in a foreign journal \cite{Ireland:1954a}, 
\item a paper in a proceedings using \texttt{@INPROCEEDINGS} 
      \cite{Eshenaur:1991a,Garrett:2003a}, 
\item a standard using \texttt{@INCOLLECTION} \cite{ASTM:1991a}, 
\item a translated book \cite{Melan:1913a}, 
\item a two-part paper \cite{Frater:1992a,Frater:1992b}, 
\item a university report using \texttt{@TECHREPORT} \cite{Duan:1990a}, 
\item an untitled item in the Federal Register using 
      \texttt{@MANUAL} \cite{FR:1968a}, 
\item works in a foreign language \cite{Duvant:1972a,Reiffenstuhl:1982a},
\item software using \texttt{@MANUAL} \cite{Lotus:1985a},
\item two works by the same author in the same year
      \cite{Gaspar:2001b,Gaspar:2001a}, and
\item two works by three authors in the same year that only share
      the first two authors \cite{Huang2009a,Huang2009b}.
\end{itemize}
%
\par
ASCE has added two types of bibliographic entries:
web-pages and CD-ROMs.  A web-page can be formated using the
\texttt{@MISC} entry category, as with the item \cite{Burka:1993a} produced
with the following \texttt{*.bib} entry:
\begin{verbatim}
    @MISC{Burka:1993a,
      author = {Burka, L. P.},
      title = {A hypertext history of multi-user dimensions},
      journal = {MUD history},
      year = {1993},
      month = {Dec. 5, 1994},
      url = {http://www.ccs.neu.edu}
    }
\end{verbatim}
Notice the use of the ``\texttt{month}'' field to give the date that material
was downloaded and the use of a new ``\texttt{url}'' field.
The ``\texttt{url}'' and \texttt{month}'' 
fields can also be used with other entry types
(i.e., \texttt{@BOOK}, \texttt{@INPROCEEDINGS}, \texttt{@MANUAL},
\texttt{@MASTERSTHESIS}, \texttt{@PHDTHESIS}, and \texttt{@TECHREPORT}):
for example, in the entry type \texttt{@PHDTHESIS} for \cite{Wichtmann:2005a}.
%
\par
A CD-ROM can be referenced when using the \texttt{@BOOK}, \texttt{@INBOOK},
\texttt{@INCOLLECTION}, or \texttt{@INPROCEEDINGS} categories, 
as in the entry \cite{Liggett:1998a}.
The field ``\texttt{howpublished}'' is used to designate the medium
in the \texttt{.bib} file:
\begin{verbatim}
    howpublished = {CD-ROM},
\end{verbatim}
%
\section{Miscellany}
Most ASCE conference proceedings are now published on CD ROM media.
I have noticed that instructions on paper formats issued by
conference organizers often differ from the
standard ASCE instructions.  
Fortunately most of the differences can be easily accommodated, such as
changes in the margins and placement of the authors' addresses.
As for margins, these can, of course, be altered by using
\verb+\setlength{<length>}+ commands within the preamble to a document without
making any changes to \texttt{ascelike.cls}.  
(See the \LaTeX\ book
\cite{Lamport:1994a}, its companion \cite{Goossens:1994a}, or
online web documentation.)
%
\par
Multiple authors from the same institution can be handled within
the \verb|\author| \verb|{...}| command by using the \verb|\footnotemark| command:
\begin{verbatim}
    \\
    Ima Colleague,\footnotemark[1] Member, ASCE%
\end{verbatim}
%
\par\label{address.kluge}
Authors' addresses can be placed below the title (instead of
in a footnote) by \emph{not} using the \verb+\thanks+ command,
replacing it with superscripts \verb+$^1$+, carriage returns
``\verb+\\+'', and \verb+\parbox+'s.
An example is shown in the \texttt{ascexmpl.tex} file.
%
\section{Wish List}
I would like to enable the \texttt{a4paper} option and could use some
advice about passing this option to \texttt{article} so that the
\texttt{article.cls} commands for \verb+\paperheight+ and \verb+\paperwidth+
are executed.  I am also uncertain about using \texttt{a4paper} as
a Boolean to set page margins.
%
\pagebreak
%
%
% Now we start the appendices, with the new section name, "Appendix", and a 
%  new counter, "I", "II", etc.
%
\appendix\label{section:references}
%
% Here's the first appendix, the list of references:
%
\bibliography{ascexmpl}
%
% And now for some pretty impressive notation.  In this example, I have used
%   the tabular environment to line up the columns in ASCE style.
%   Note that this and all appendices (except the references) start with 
%   the \section command
%
\section{Notation}
\emph{The following symbols are used in this paper:}%\par\vspace{0.10in}
\nopagebreak
\par
\begin{tabular}{r  @{\hspace{1em}=\hspace{1em}}  l}
$D$                    & pile diameter (m); \\
$R$                    & distance (m);      and\\
$C_{\mathrm{Oh\;no!}}$ & fudge factor.
\end{tabular}
%
\end{document}