iuphd-doc.tex

\chapter{Documentation}

This pdf doubles as documentation for the iuphd.cls file, and as a sample for the output.
The iuphd class is based on the standard \LaTeX \ report class, and as such you may assume that it follows
the default formatting of the report class unless otherwise specified below.  The
changes to the report class include the following:

\begin{itemize}
 \item changes to the default settings for margins, font size (11pt), spacing (double), and pagination,
 \item the quote, quotation, and verse environments have been changed to switch temporarily to single spacing, and
       remove the extra space at the top and bottom,
 \item the enumerate and itemize environments have been changed to remove extra space between the items and at the
       top and bottom,
 \item both numbered and unnumbered chapter headings are now centered by default,
 \item heading names such as CHAPTER, and BIBLIOGRAPHY are now all caps by default regardless of how they are typed,
 \emph{(This is accomplished with the help of textcase.sty.  Not all latex distributions come with this by default.)}
 \item changes to the definitions of \textbackslash maketitle and the `abstract' environment,
 \item the addition of commands for creating the acceptance page and copyright page,
 \item the addition of the `acknowledgments', `preface', and `dedication' environments,
 \item the addition of macros for specifying the department or school name, the names of
 the committee members, the defense date, and the month and year degree will be granted,
 \item the addition of the \code{abstract*}, \code{preface*}, \code{acknowledgments*}, or \code{dedication*} environments having the same function as the non-star version, but show them in the table of contents.
\end{itemize}

The appropriate commands for using these features are already typed into the dissertation.tex sample file,
with the optional items (copyright, dedication, acknowledgments, and preface) commented out.  Simply remove the \% from the front
of these optional commands if you wish to use them.  The headings for the acknowledgments and preface have
been defined as unnumbered chapter headings, which means they will not show up in the table of contents by default.
See the instructions below for adding them to the table of contents if desired.

\section{Current Standards at IU}
The current version of iuphd.cls complies with the standards of formatting a dissertation at IU as of $2018$.  Below is a discussion of
some of the main points.

The current pagination standard is for the page number to appear centered at the top or bottom of the
page, and to use lowercase roman numerals for the material preceding the first chapter with the title page unnumbered but counting as
page one. The only part of this that is not standard in the \LaTeX \ report class is the use of roman numerals, which was accomplished
by changing the definitions to \code{\textbackslash maketitle} and \code{\textbackslash tableofcontents}.

The current standard for chapter headings seems to be that they are centered and in all caps.  The iuphd.cls enforces these
conventions automatically, however it is possible to override these changes with
titlesec and titletoc packages. Because the textcase package is used,
the capitalization is not affected in math mode, so for instance
\begin{verbatim}
\section{$p$-adic numbers}
\end{verbatim}
will give the output ``$p$-ADIC NUMBERS'' in both the section heading and in the table of contents
(unless the value of \code{\textbackslash tocdepth} is changed to prevent sections from being listed in the table of contents).
For LaTeX standard classes with \code{[11pt]}, \code{\textbackslash large} command produces
$12$ points text~\cite{wiki:LaTeXFonts}. Since font size should be either $11$
or $12$ point for the entire document, the size of any headings in the report class
which is larger than \code{\textbackslash large} is changed to \code{\textbackslash large}.

Most dissertations are one-sided, with an additional half inch added to the left hand margin on each page for the purpose of binding.
Although this is the standard, they do allow for the possibility of two-sided printing, which would cause the side with the extra margin
to alternate for binding.  This is automatically enforced simply by using the twoside option (a feature already built into the
standard report class). This is done as follows:
\begin{verbatim}
\documentclass[twoside]{iuphd}
\end{verbatim}
There does not seem to be a standard about whether the abstract, preface, acknowledgments, and dedication are listed in the table of
contents (TOC) or not.  As such, a stared version of these environments has been provided for including each one individually.
So for example, to include
both the abstract and the preface in the table of contents, but not the dedication or acknowledgments, you would use the code:
\begin{verbatim}
\begin{dedication} ... \end{dedication}
\begin{acknowledgments} ... \end{acknowledgments}
\begin{preface*} ... \end{preface*}
\begin{abstract*} ... \end{abstract*}
\end{verbatim}
To include a line for the bibliography in the table of contents, the command
\begin{verbatim}
\clearpageAddContents{chapter}{Bibliography}
\end{verbatim}
should be placed directly above the \code{\textbackslash bibliography} and \code{\textbackslash bibliographystyle} commands,
where a \code{\textbackslash clearpage} is placed before adding a new content line to get the page number displayed in the contents correctly.
If we want to put a bibliography for each section, the \code{chapter} should be replaced by \code{section}, and write like:
\begin{verbatim}
\clearpageAddContents{section}{Bibliography}
\end{verbatim}
and the precise code for adding a bibliography for each section can be seen in \url{https://git.io/fhj8U}, \url{https://git.io/fhj8I}, and \url{https://git.io/fhj8q} if you use \code{biblatex} package.
Since the curriculum vitae should not have a page number, the command including the curriculum vitae is different from the one including the bibliography
\begin{verbatim}
\addContentsChapterWithoutPagenumber{Curriculum Vitae}
\end{verbatim}
Similar commands will work for including any unnumbered heading in the table of contents with or without a page number.

Various commands have been defined for the data that will show up on the title page, acceptance page, and copyright page.  These include:
\begin{itemize}
 \item \code{\textbackslash title} - for the title of the dissertation
 \item \code{\textbackslash author} - for the name of the author of the dissertation
 \item \code{\textbackslash department} - for the name of the department(s) (or school(s)) you are in.  Notice that the university graduate school doesn't specify the format for writing departments for double-major students~\cite{DoctoralFormatting2018}.  Different students use different formats \cite{Hansen2015,Agmon2016,Bambach2016}, and we follow the majority of recently accepted format.
 \item \code{\textbackslash defensedate} - for the \emph{defense date} of the dissertation (which may not match the completion date).
 \item \code{\textbackslash committeeMember} - for the names of the dissertation committee members.
 \item \code{\textbackslash monthGranted} - for the month degree will be granted. 
 \item \code{\textbackslash yearGranted} - for the year degree will be granted.
\end{itemize}

In my dissertation.tex sample file, we use \code{datetime2} and \code{datetime2-calc} packages to get the current month and year for the month and year degree will be granted. These can be changed if the month you get your degree is different from the month this file been compiled.

Additionally the commands \code{\textbackslash acceptancepage} and \code{\textbackslash copyrightpage} have been defined to generate the acceptance page and copyright page
respectively.  The copyright page is not required, so it has been commented out of my dissertation.tex sample file.

Also, the command \code{\textbackslash acceptancepage} and the \code{abstract}
environment takes an optional argument to specify the space for committee
signatures. When the committee signatures are all in the same page, the default
values are \code{\textbackslash fill} looks good. However, \code{\textbackslash
fill} cannot distribute space evenly when they are in the different pages. In
this case, \code{\textbackslash bigskipamount} or \code{\textbackslash
lineskip} might be appropriate.

A CV is also required following the bibliography, however, to maintain maximum flexibility I have not provided any special tools for
formatting a CV.  Various packages are available that do this, although I prefer custom formatting. As such, I have provided only a
line for including the CV after the bibliography, which is currently commented out.



\section{Suggestions for Additional Formatting}

For longer documents, it is often easier to manage if it is broken into multiple files.  This can be done by using the
\textbackslash include\{filename\} or \textbackslash input\{filename\} commands.  You can think of
\textbackslash input\{filename\} as an alias for all of the text contained in filename.tex: the text contained in that file,
simply gets inserted at the exact spot where the command \textbackslash input is used.  This means that filename.tex should not have
\textbackslash begin\{document\}, \textbackslash end\{document\}, or a preamble, as illustrated by iuphd-doc.tex in this example.
On the other hand, \textbackslash include\{filename\} has the additional feature of adding \textbackslash clearpage both before and after
the text being inserted.  This has important consequences for formatting.  Say that you have a file for each chapter,
and your first chapter is the introduction.  If you do something like this:
\medskip

\textbackslash chapter\{Introduction\}

\textbackslash include\{chap1\}
\medskip

\noindent then the title is formatted on its own page, and the text in chap1.tex will start on a new page; it produces
the same result as
\medskip

\textbackslash chapter\{Introduction\}

\textbackslash clearpage

\textbackslash input\{chap1\}
\medskip

\noindent To avoid having the title put on a separate page there are two options: use input instead of include
(without \textbackslash clearpage), or use the command \textbackslash chapter\{INTRODUCTION\} inside the file chap1.tex.
I favor the second option as illustrated in this example with iuphd-doc.tex.

Many \LaTeX \ packages are already available for additional customization of the formatting which is otherwise built in.
Some of these are listed below.  To use them, simply declare them with \textbackslash usepackage in the preamble
and refer to the documentation files for them, which are easily available online.

\begin{itemize}
 \item titlesec - for custom formatting of part, chapter, and section headings.
 \item titletoc or tocloft - for custom formatting of the table of contents.
 \item nomencl - for lists of notation (a tweak of makeindex).
 \item prettyref - for custom formatting of references (e.g. referencing equations as (1), (2), etc., instead of the default
       1, 2, etc.).  The ams packages also have a similar feature but it is much more limited.
 \item natbib, custom-bib, or biblatex - offer additional flexibility for bibliography formatting beyond the standard used by
       the mathematics community.
 \item setspace - contains features for resetting the global line spacing, as well as environments that can be used to change
       spacing locally, which are compatible with the quote, quotation, and verse environments.
 \item quoting - provides a more flexible quotation environment, with options for adjusting the margins manually.  This package
     should be used with setspace, to ensure single spacing of the quotations.
 \item enumitem or paralist - provide several more flexible list environments.
 \item titling - for custom changes to maketitle.
 \item geometry - for customizing the page layout.
\end{itemize}

%add features for block quotes, underlined titles, and different departments.

The last two should not be necessary unless the standards at IU change.  However, if that happens, it would really be better to
rewrite the iuphd document class.  Additional packages and other useful information can be found in \cite{mittelbach2004latex}.

\section{Quote Samples}
The quote environment:
\begin{quote}
``God does not play dice with the universe.'' - Albert Einstein
\end{quote}
The quotation environment:
\begin{quotation}
 ``A GREAT discovery solves a great problem, but there is a grain of discovery in the solution of any problem.
 Your problem may be modest, but if it challenges your curiosity and brings into play your inventive faculties,
 and if you solve it by your own means, you may experience the tension and enjoy the triumph of discovery.''
 
 - George P\'olya
\end{quotation}
The verse environment:
\begin{verse}
Im September ist alles aus Gold:\\ 
die Sonne, die durch das Blau hinrollt,\\
das Stoppelfeld,\\
die Sonnenblume, schläfrig am Zaun,\\
das Kreuz auf der Kirche,\\
der Apfel im Baum.\\
Ob er h\"alt,\\
ob er f\"allt? \\
Da wirft ihn geschwind\\
der Wind\\
in die goldene Welt.

- Georg Britting
\end{verse}

\section{Troubleshooting}

If you are getting an error with the TOC, you may have at least one of the following two problems:
\begin{enumerate}
 \item you do not have textcase.sty in your latex distribution,
 \item you compiled a previous *.toc file with a different latex class (e.g. the amsbook class).
\end{enumerate}
Make sure you have textcase.sty, delete the *.toc file, and recompile.