path: root/macros/latex/contrib/ucbthesis/ucbthesis.tex

\documentclass[11pt]{article}
\usepackage[sf]{titlesec}
\usepackage[colorlinks=true]{hyperref}
\usepackage{breakurl}
\usepackage{listings}
\usepackage{booktabs}
\usepackage{tabularx}

\title{The UCB Thesis Class}
\author{Paul Vojta\\Mathematics Department\\
  \texttt{\href{mailto:vojta@math.berkeley.edu}{vojta@math.berkeley.edu}}}
\date{Version 3.6\\July 19, 2019}

\lstset{%  settings taken from msu-thesis documentation
    basicstyle=\ttfamily\small,
    commentstyle=\itshape\ttfamily\small,
    showspaces=false,
    showstringspaces=false,
    breaklines=true,
    breakautoindent=true,
    frame=single,
    captionpos=t,
    language=TeX
}

\newcommand*{\pkg}[1]{\texttt{#1}}

\begin{document}
\maketitle
\thispagestyle{empty}
\renewcommand{\abstractname}{\sffamily Abstract}

\abstract{\noindent\begin{quote} This is a class file for theses and
dissertations at the University of California, Berkeley.  It is based on
the \pkg{memoir} class, and therefore supports all of the functionality
of that class.  It should generate a document that meets all of the basic
formatting requirements given in the \emph{Dissertation Filing Guide}
or the \emph{Thesis Filing Guide} (as appropriate) produced by the
UC Berkeley Graduate Division and available on the web at
\url{https://grad.berkeley.edu/academic-progress/}.
This version of the class is based on the dissertation and thesis guides,
accessed in July 2019.\end{quote}}

\section{Introduction}

The \pkg{ucbthesis} class is a modified
version of the standard \LaTeX\ \pkg{memoir} class that is accepted for use
with University of California, Berkeley, Ph.D.~dissertations and Master's
theses.  The available commands are almost identical to those of the
\pkg{memoir} class, so the recommended starting point for documentation
is general documentation for \LaTeX.

This document class requires a reasonably recent version of the \pkg{memoir}
class.  It is known to work with \pkg{memoir} version ``2010/09/19 v3.6g,'' but
not with \pkg{memoir} version ``2005/09/25 v1.618.''
% v1.618 gives \undefinedpagestyle

\emph{Note:}  The documentation for the \pkg{memoir} class is long (currently
583 pages), and the vast majority of it is completely irrelevant to the process
of writing a thesis using \pkg{ucbthesis}.  \textbf{Do not print out the
documentation for the \pkg{memoir} class!}  Doing so would be a huge waste
of paper and money.  Look to general \LaTeX\ documentation instead.

\smallbreak
The key features of the class are:
\begin{enumerate}
\item The primary modification to the \pkg{memoir} class is the setting of the
  margins and (for Master's theses prior to 2011) use of pseudo-double-spacing,
  since Berkeley's rules for Master's theses were still designed
  for typewriters.  The latter is achieved by increasing the
  \verb|\baselinestretch| parameter to 1.37.  The \verb|\baselinestretch|
  is returned to a single-spaced value of 1.00 for elements like tables,
  captions, and footnotes and for all displayed text (quote, quotation,
  and verse environments).
\item Margins are 1 inch on all sides.
\item Uses 12 point by default; you can use the 10pt or 11pt options for
  those sizes (but note that only 12pt should be used for the final
  submitted copy).
\item Page numbers are in the top right corner for all pages.
\item Complete, correct front matter for Berkeley dissertations can be
  generated.  If you are not a Berkeley student, you should make sure
  that the front matter is OK with your school.
\end{enumerate}

The \pkg{ucbthesis} class is derived from the \pkg{ucthesis} class---the
name has been changed to reflect the fact that it is (probably) only
valid for Berkeley theses.
The \pkg{ucbthesis} class should be used for new theses (at Berkeley);
\pkg{ucthesis} may still be used for older theses submitted prior to the
change to electronic submission in Fall 2009, and will still be maintained
for this purpose.

A (partial) list of thesis classes at other University of California
campuses is available on the web at
\url{https://math.berkeley.edu/~vojta/ucthesis.html}.

\section{Using the \pkg{ucbthesis} Class}

\subsection{Sample Dissertation}

There is a sample dissertation in the \texttt{example} subdirectory
of the documentation directory.  All of the files in that subdirectory
form part of the sample dissertation.  To produce a \texttt{pdf} or
\texttt{dvi} file of the thesis, copy the files to some other directory
and type the commands
\begin{lstlisting}
pdflatex thesis
biber thesis
pdflatex thesis
\end{lstlisting}
(Use \texttt{latex} instead of \texttt{pdflatex} if you want a \texttt{dvi}
file instead of a \texttt{pdf} file as output.  You may need to replace
\texttt{biber} with \texttt{bibtex}, depending on your \TeX\ setup---look
at the output from the first run of \pkg{pdflatex} or \pkg{latex}.)

The file \texttt{references.bib} is its bibliography database (though
the contents of the database are not important).  Mostly this example
document is useful as an example of how to produce the front matter.

If you don't understand \LaTeX\ at all, this file might help you get
started, but, since you're going to be writing a quite lengthy document,
you should look into more comprehensive information on \LaTeX.
A list of \TeX\ and \LaTeX\ documentation is maintained at the web page
\url{http://www.tug.org/interest.html#doc}.

\subsection{Selecting the \pkg{ucbthesis} Class}

To use the \pkg{ucbthesis} class, make sure that the \texttt{ucbthesis.cls}
file is on your TEXINPUTS search path and use the following command at
the start of your input file:

\begin{lstlisting}
\documentclass{ucbthesis}
\end{lstlisting}

\subsection{Class Options}

The options for the \pkg{ucbthesis} class are given in Table~\ref{opts}.
They should be selected on the \verb|\documentclass| line, e.g.:
\begin{lstlisting}
\documentclass[10pt,draft]{ucbthesis}
\end{lstlisting}

\begin{table}[htbp]
\centering
\begin{tabularx}{.8\textwidth}{>{\ttfamily}lX}
\toprule
\multicolumn{1}{c}{Option} & \multicolumn{1}{l}{Description}\\
\midrule
{phd} & Selects formatting for doctoral dissertation (default) \\
{masters} & Selects formatting for Master's thesis submitted in 2012 or later:
  changes the word ``dissertation'' on the title page to ``thesis.'' \\
{oldmasters} & Selects formatting for Master's thesis submitted in 2011 or
  earlier:  selects double spacing and changes the word ``dissertation''
  on the title page to ``thesis.'' \\
{final} & Uses pseudo-double-spacing for Master's theses submitted in 2011 or
  earlier (default) \\
{draft} & Uses single-spacing throughout the document \\
{12pt} & Sets the default font size to 12 points (default) \\
{11pt} & Sets the default font size to 11 points.  \emph{Note:}  This option
  should be used only for draft copies (e.g., to save paper).  The final
  submitted copy must use 12-point fonts or larger \\
{10pt} & Sets the default font size to 10 points.  \emph{Note:}  This option
  should be used only for draft copies (e.g., to save paper).  The final
  submitted copy must use 12-point fonts or larger \\
\bottomrule
\end{tabularx}
\caption{Document class options}\label{opts}
\end{table}

All options supported by the \pkg{memoir} class are also supported
(although some of them would not be very useful for a thesis).

\subsection{Page Headers}

If you want to use page headers or footers other than the default ones,
you should try using \texttt{headerfooter.sty} or \texttt{fancyheadings.sty}.
The \texttt{myheadings} pagestyle doesn't work well and there is no workaround.
The \pkg{headerfooter} and \pkg{fancyheadings} styles are widely distributed,
well documented, and easy to use.

\subsection{Overall Document Structure}

The overall structure of a \verb|.tex| file for a thesis is the same as
most other \LaTeX\ files:  a \verb|\documentclass| line, followed by
declarations (e.g., \verb|\usepackage| lines and macro definitions),
and then one (or, rarely, more) instances of a \verb|document| environment.

Your best guide for what goes inside the \verb|document| environment is
to follow the practice in the sample file \verb|thesis.tex|.  In a nutshell,
though, this consists of declarations and environments for the front matter,
followed by the main content of the thesis, and then the bibliography
and any appendices.  The structure of the part of the file
corresponding to the front matter is described in the next section.

\section{Front Matter}

In addition to setting the page layout and line spacing, the other key
service provided by the \pkg{ucbthesis} class is that it generates
correct front matter (title page, approval page, abstract, etc.)\ with
a fairly simple set of commands.  This facility could be a little
easier, but compared to an earlier state of affairs, it's pretty
slick.  The format of the front matter is specified quite explicitly
in the documents ``Dissertation Filing Guide'' and ``Thesis Filing Guide''
produced by the UC Berkeley Graduate Division and available on the web at
\url{https://grad.berkeley.edu/academic-progress/}.
The current version of the class is based on the dissertation and thesis
guides, accessed in July 2019.

A complete example of the use of the front matter commands can be
found in the sample dissertation distributed with the class.
Generally, the part of the \LaTeX\ file that generates the front matter
consists of the following portions:
\begin{itemize}
\item Declarations of text strings
\item Macros to generate the title, approval, and copyright pages
\item \verb|abstract| environment
\item \verb|frontmatter| environment
\end{itemize}
These portions are described in the following subsections.

\subsection{Declarations of Text Strings}

To use the front matter macros and environments, you must first
declare the text strings listed in Table~\ref{decls}.  This is done
by invoking the relevant macro with the string as its argument;
for example, \lstinline|\title{Snakes in Ireland}|.

\begin{table}
\centering
\lstset{basicstyle=\ttfamily}
\begin{tabularx}{.9\textwidth}{lX}
\toprule
\multicolumn{1}{c}{Macro} & \multicolumn{1}{l}{Description} \\
\midrule
\lstinline|\\title| & Dissertation title \\
\lstinline|\\author| & Your name as registered with UC (usually with full
  middle name) \\
\lstinline|\\degreeyear| & Year your dissertation will be granted \\
\lstinline|\\degreesemester| & Semester (or term) your degree will be granted \\
\lstinline|\\degree| & The title of your degree (e.g.~Doctor of Philosophy) \\
\lstinline|\\jointinstitution| & For joint degrees, the other institution \\
\lstinline|\\chair| & Title and name of your committee chair
  (e.g.~``Professor Michael A. Harrison'') \\
\lstinline|\\cochair| & Title and name of your committee co-chair
  (use with \lstinline|\\chair|, if you have a co-chair). \\
\lstinline|\\cochairs| & Titles and names of your (co-equal) committee
  co-chairs (replaces \lstinline|\\chair| and \lstinline|\\cochair|). \\
\lstinline|\\othermembers| & The names of the other members of your committee
  separated by linebreaks
  (e.g.~\lstinline!Professor Susan L. Graham\\\\Professor Jim Pitman!) \\
\lstinline|\\numberofmembers| & The number of members on your committee.
  This defaults to 3 (and thus is optional) and can be any value from
  3 to 6.  It affects the number of lines on the approval
  page and the space between them. \\
\lstinline|\\field| & The official title of your field.  This is usually
  your department's name, but at Berkeley, most
  Engineering degrees have a more complex name.
  Be sure to check the guidelines for any special
  twists on the name of your field. \\
\lstinline|\\emphasis| & The ``designated emphasis'' of your degree (if any) \\
\lstinline|\\campus| & The name of your UC campus.  This should be capitalized
  (e.g.~Berkeley).  This is optional, and defaults to Berkeley. \\
\bottomrule
\end{tabularx}
\caption{Declarations for Front Matter}\label{decls}
\end{table}

\subsection{Title, Approval, and Copyright Pages}

The title, approval, and copyright pages have extremely rigid formats
that allow them to be generated automatically once the above
declarations have been made.  To generate them, invoke the macros
\begin{lstlisting}
\maketitle
\approvalpage
\copyrightpage
\end{lstlisting}

You should probably invoke them in that order, because that's the
order required by the guidelines.  The approval page should not be part
of the submitted thesis, but the \verb|\approvalpage| macro may be used to
generate the required approval page to be printed and submitted with the
thesis.

\subsection{Abstract Environment}

Because you have to provide the text of the abstract, only the title
can be generated automatically.  So, there is an abstract environment.
It generates the title and numbers the abstract in arabic numerals and
makes sure that it starts on new page.

The advisor's signature no longer is required (or allowed) for the
abstract.

\subsection{Other Front Matter}

The remaining front matter (dedication, table of contents, lists of
figures and tables, acknowledgements) \emph{must} be put inside the
\verb|frontmatter| environment, which ensures that page numbering is
handled properly.  Within this \verb|frontmatter| environment, you put the
environments and commands for the rest of the front matter.  There are
environments for \texttt{dedication} and \texttt{acknowledgements},
and the standard \LaTeX\ commands for producing \verb|\tableofcontents|,
\verb|\listoffigures|, and \verb|\listoftables| should also go inside
the \verb|frontmatter| environment.

The standard \LaTeX\ commands are well documented in the \LaTeX\ manual.
You may have to hand edit the \texttt{.lof} (list of figures) and
\texttt{.lot} (list of tables) files to make verbose captions more suitable for
this front matter.  Once you do this, remember to use the \verb|\nofiles|
macro to keep them from getting overwritten.

The \pkg{ucbthesis} class provides \texttt{acknowledgements} and
\texttt{dedication} environments, which produce corresponding sections in
the front matter and make them start on a new page.  The
\texttt{acknowledgements}
environment also puts the word ``Acknowledgements'' in large, bold,
centered text at the top of the page.  For formatting the dedication page,
you're on your own.  After all, the dedication is a kind of poetry and
there's no predicting the right way to format poetry.

\section{Obsolete Environments and Commands}

Previous (unreleased) versions of the \pkg{ucbthesis} (and \pkg{ucthesis})
classes defined environments for producing small tables with single spacing.
These environments are no longer necessary, since standard \LaTeX\ now
handles the situation properly.  Replace the \verb!\begin{...}!
commands as indicated in Table \ref{obsolenv}, and change the
corresponding \verb!\end! commands accordingly.

\begin{table}[htbp]
\centering
\begin{tabular}{l l}
  \toprule
  \multicolumn{1}{c}{Environment} & \multicolumn{1}{c}{Use Instead}\\
  \midrule
  \lstinline!smalltabular! & \lstinline!\small\begin{tabular}! \\
  \lstinline!smalltabular*! & \lstinline!\small\begin{tabular*}! \\
  \lstinline!scriptsizetabular! & \lstinline!\scriptsize\begin{tabular}! \\
  \lstinline!scriptsizetabular*! & \lstinline!\scriptsize\begin{tabular*}! \\
  \bottomrule
\end{tabular}
\caption{Obsolete environments}\label{obsolenv}
\end{table}

The \pkg{ucthesis} class also provided commands \verb!\smallssp! and\break
\verb!\scriptsizessp!; these should now be changed to
\verb!\small\SingleSpacing! and \verb!\scriptsize\SingleSpacing!,
respectively.

\section{Installing the \pkg{ucbthesis} Class}

To install the \pkg{ucbthesis} class, you need to install the file
\texttt{ucbthesis.cls} in your \LaTeX\ class file repository.  This
generally should go in a directory \lstinline!TEXMF/tex/latex/ucbthesis!
(where \lstinline!TEXMF!  is the base of the \texttt{texmf} tree).
Or, it can also be placed in the directory that you use when running
\LaTeX\ on your thesis.

You should also install the documentation files
\begin{verbatim}
   README
   ucbthesis.tex
   ucbthesis.pdf
   thesis.tex
   abstract.tex
   chap1.tex
   chap2.tex
   references.bib
\end{verbatim}
in a similar directory under the documentation directory, generally
\lstinline!TEXMF/doc/latex/ucbthesis! for the first three files, and
\lstinline!TEXMF/doc/latex/ucbthesis/example! for the last five.

These files should already be placed in subdirectories reflecting the above
guidelines, so that one might extract the \texttt{tar} file in the main
\lstinline!TEXMF! directory to get the right results.

\section{Modification History}

Version 3.3 was the initial release of \pkg{ucbthesis} (it was forked from
\pkg{ucthesis}, hence the unusual version number).  The package \pkg{ucthesis}
was created for non-electronic submissions, and should no longer be used,
except for printing out older theses.  Version 3.3 was distributed only within
Berkeley.

Version 3.4 switched to using the \pkg{memoir} class, eliminated the
\texttt{smalltabular}, \texttt{smalltabular*}, \texttt{scriptsizetabular},
and\break
\texttt{scriptsizetabular*} environments, and the \lstinline!\smallssp!
and\break
\lstinline!\scriptsizessp! commands.  It also added support for co-chairs
on the dissertation/thesis committee, joint degrees, and degrees with a
Designated Emphasis.  In addition, it was modified for release on \textsc{ctan}.

Version 3.5 added support for printing the Designated Emphasis on the abstract
page (a Graduate Division requirement).

Version 3.6 changed the font in the title from bold to regular and adjusted the
spacing in the abstract page.  It added \lstinline!\cochairs! to the
documentation.  In the example, it added a sideways table, added sample uses
of \lstinline!\cochair! and \lstinline!\cochairs!, and moved the (commented-out)
appendix to after the bibliography (as per requirements).

\end{document}