path: root/macros/latex/contrib/ut-thesis/ut-thesis.dtx

% \iffalse
%<*driver>
\ProvidesFile{ut-thesis.dtx}
%</driver>
%<class>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<class>\ProvidesClass{ut-thesis}
%<*class>
[2021/05/04 v3.0.3 University of Toronto thesis class]
%</class>
%
%<*driver>
\documentclass[10pt]{ltxdoc}
\usepackage[osf]{mathpazo}
\usepackage[toc]{multitoc}
\renewcommand*{\multicolumntoc}{2}
\usepackage[margin=3cm,inner=5cm]{geometry}
\usepackage{xcolor}
\definecolor{code}{HTML}{990033}
\definecolor{link}{HTML}{000066}
\let\ottfamily\ttfamily
\renewcommand{\ttfamily}{\color{code}\ottfamily}
\renewcommand{\MacroFont}{\ttfamily\color{code}}
\usepackage[colorlinks,linkcolor=link]{hyperref}
\setlength{\skip\footins}{4ex}
\setlength{\parindent}{0pt}
\setlength{\parskip}{6pt}
\newcommand{\smacro}[2][0]{%
  \begin{macro}{#2}\end{macro}%
  \vspace{\dimexpr #1\baselineskip-3\baselineskip}}
\begin{document}
  \DocInput{ut-thesis.dtx}
\end{document}
%</driver>
% \fi
%
% \GetFileInfo{ut-thesis.dtx}
%
% \title{The \texttt{ut-thesis} class
%   \thanks{\fileversion~[\filedate] CTAN repository:
%   \href{https://ctan.org/pkg/ut-thesis}
%        {\texttt{https://ctan.org/pkg/ut-thesis}}}}
% \author{
%   Francois Pitt,
%   Jesse Knight
%     \thanks{maintainer, contact:
%     \href{mailto:jesse.knight@mail.utoronto.ca}
%          {\texttt{jesse.knight@mail.utoronto.ca}}}
% }
%
% \maketitle
%
% \begin{abstract}\noindent
%   The |ut-thesis| document class implements the formatting requirements of
%   the University of Toronto School of Graduate Studies (SGS),
%   as of Fall 2020.
% \end{abstract}
%
% {\footnotesize\setlength{\parskip}{3pt}\tableofcontents}
% \clearpage
%
% \section{Installation}\label{inst}
%
% To use the |ut-thesis| class,
% you must first make the file |ut-thesis.cls| visible to your current \LaTeX\ distribution.
% There are two ways to do this:
% \begin{itemize}
%   \item \textbf{local file}: Place the file |ut-thesis.cls| in your project directory.
%         This is usually easiest, and works if you don't have write access
%         in the \LaTeX\ distribution, such as if you use Overleaf.
%   \item \textbf{installing}: Installation steps will depend on your \LaTeX\ distribution.
%         Some helpful instructions can be found
%         \href{https://en.wikibooks.org/wiki/LaTeX/Installing_Extra_Packages}{here}.
% \end{itemize}
%
% \section{Usage}\label{use}
%
% |\documentclass{ut-thesis}|\\
% |\documentclass[ <options> ]{ut-thesis}|
%
% The default options produce a final copy, ready for submission to
% the University of Toronto School of Graduate Studies (SGS).
%
% \subsection{Options}\label{use:opt}
%
% The default class options are denoted like |option*|.
%
% \subsubsection{Paper Size}\label{use:opt:paper}
%
% The standard page sizes are supported, including:
% |[letterpaper*]|, and |[a4paper]|.
%
% \subsubsection{Font Size}\label{use:opt:fontsize}
%
% \smacro[ 1]{[10pt*]}
% \smacro[ 1]{[11pt]}
% \smacro[-2]{[12pt]}
% \begin{macro}{]}
%   The three standard font sizes are supported.
%   SGS requires at least 10\,pt font for the text,
%   but captions, footnotes, etc.\ can be smaller.
% \end{macro}
%
% \subsubsection{Line Spacing}\label{use:opt:spacing}
%
% \smacro[ 1]{[singlespacing]}
% \smacro[ 1]{[onehalfspacing*]}
% \smacro[-2]{[doublespacing]}
% \begin{macro}{]}
%   Three options are available for line spacing.
%   Note that |[singlespacing]| does not conform to the SGS guidelines,
%   but we provide it in case you ever prefer it while writing.
% \end{macro}
%
% \subsubsection{Margins}\label{use:opt:margins}
%
% \paragraph{Sides:}
% Three variants of margins are defined,
% reflecting preferences for printing and binding,
% the first two being the same as in the |book| class:
%
% \begin{macro}{[oneside]}
%   All pages behave as if they open to the right (wider left margin).
% \end{macro}
%
% \begin{macro}{[twoside*]}
%   Most pages will alternate opening to the right and left;
%   however, the commands: |\maketitle|, |\begin{abstract}| and |\mainmatter|,
%   which create new pages, will always open to the right,
%   sometimes requiring a blank page before to do so.
% \end{macro}
%
% \begin{macro}{[equalmargins]}
%   The left and right margins are equal (averaged);
%   all pages behave as if they open to the right.
% \end{macro}
%
% \paragraph{Opening:}
% Only if |[twoside]| is used, two additional options from the |book| class
% control how other new pages will open, including new pages created by:
% |\listoftables|, |\listoffigures|, and |\chapter{}|.
%
% \begin{macro}{[openright*]}
%   These pages will always open to the right (like |\maketitle|, etc.).
% \end{macro}
%
% \begin{macro}{[openany]}
%   These pages can open to the left or right.
% \end{macro}
% 
% \paragraph{Widths:}
% Four widths of margins are defined based on
% the inner (left) and outer (right/top/bottom) dimensions:
%
% \begin{macro}{[narrowmargins]}
%   Inner: 1.25 inch; outer: 0.75 inch
%   (minimum SGS requirements)
% \end{macro}
% \begin{macro}{[normalmargins*]}
%   Inner: 1.50 inch; outer: 1.00 inch
% \end{macro}
% \begin{macro}{[widemargins]}
%   Inner: 1.75 inch; outer: 1.25 inch
% \end{macro}
% \begin{macro}{[extrawidemargins]}
%   Inner: 2.00 inch; outer: 1.50 inch
% \end{macro}
%
% \subsubsection{Draft}\label{use:opt:draft}
%
% \begin{macro}{[draft]}
%   Adds ``DRAFT'' to all 4 corners, plus the date centered below the footer.
%   The default |draft| behaviour for the |book| class is also supported.
% \end{macro}
%
% \subsection{Commands}\label{use:cmd}
%
% \subsubsection{Author Information}\label{use:cmd:author}
%
% The following 5 commands should be used in the preamble
% to define the content of the titlepage (|\maketitle|) and abstract page (|abstract| environment).
%
% \begin{macro}{\author}
%   Your full name.
% \end{macro}
%
% \begin{macro}{\title}
%   The title of your thesis.
% \end{macro}
%
% \begin{macro}{\degree}
%   The title of your degree (spelled out, like ``Doctor of Philosophy'' not ``PhD'').
% \end{macro}
%
% \begin{macro}{\department}
%   The name of your department.
% \end{macro}
%
% \begin{macro}{\gradyear}
%   The year of your degree completion.
% \end{macro}
%
% If undefined, template values are used like ``(author)''.
%
% \subsubsection{Document Parts}\label{use:cmd:parts}
%
% From the |book| class, four commands can be used to divide the document into major parts.
% These should be used in the order they appear here, as needed.
% The first two commands are necessary for the required SGS page numbering style.
%
% \begin{macro}{\frontmatter}
%   Turns off chapter numbers, uses roman numerals for page numbers.\\
%   Suggested use: immediately after |\begin{document}|.
% \end{macro}
%
% \begin{macro}{\mainmatter}
%   Turns on chapter numbers, uses arabic numerals for page numbers.\\
%   Suggested use: immediately before the first main |\chapter{}| command.
% \end{macro}
%
% \begin{macro}{\appendix}
%   Uses letters for chapter numbers, no change to page numbers.\\
%   Suggested use: immediately before the first appendix |\chapter{}| command.
% \end{macro}
%
% \begin{macro}{\backmatter}
%   Turns off chapter numbers, no change to page numbers.\\
%   Suggested use: immediately before |\printbibliography| or |\bibliography{}|.
% \end{macro}
%
% \subsubsection{Front Matter}\label{use:cmd:front}
%
% From the |book| class, the following commands are available to generate the frontmatter.
% These should be used in the order they appear here, as needed.
% 
% \begin{macro}{\maketitle}
%   Creates the title page according to SGS requirements,
%   and adds a blank page following if using |[twoside]|.
% \end{macro}
%
% (The abstract page should appear here;
% see \S~\ref{use:env:abs}).
% 
% (The dedication and acknowledgements should appear here, as needed;
% see \S~\ref{use:env:ded-ackn}).
% 
% \begin{macro}{\tableofcontents}
%   Prints the table of contents, starting on a new page.
% \end{macro}
%
% \begin{macro}{\listoftables}
%   Prints the table of tables, starting on a new page.
% \end{macro}
%
% \begin{macro}{\listoffigures}
%   Prints a table of figures, starting on a new page.
% \end{macro}
% 
% \subsection{Environments}\label{use:env}
%
% \subsubsection{Abstract}\label{use:env:abs}
%
% \begin{macro}{abstract}
%   Creates the abstract page according to SGS requirements,
%   and adds a blank page if using |[twoside]|.
%   The abstract content should be added within the environment,
%   and should be no more than
%   350 words for a PhD thesis or
%   150 words for a Master's thesis.
%   We do not provide tools for counting words.
% \end{macro}
%
% \subsubsection{Dedication \& Acknowledgments}\label{use:env:ded-ackn}
%
% \begin{macro}{dedication}
%   The |dedication| environment formats text flush right and 2/3 down a new page.
%   Not necessary for SGS requirements, so you're welcome to redefine this environment.
% \end{macro}
%
% \begin{macro}{acknowledgements}
%   The |acknowledgments| environment creates a centered heading using |\section*{}|,
%   and a new page after the text.
%   Not necessary for SGS requirements, so you're welcome to redefine this environment.
% \end{macro}
%
% \subsubsection{Base Environments}\label{use:env:misc}
%
% As in the |book| class, the base environments
% like |figure|, |table|, and |equation| are sub-numbered
% within the current chapter like ``(2.1)'' for Equation~1 in Chapter~2.
% The behaviour is equivalent to: |\counterwithin{equation}{section}|,
% and can be undone with: |\counterwithout{equation}{section}|.
%
% For sub-figures, we recommend the |subcaption| package.
%
% The |quote| and |quotation| environments from the |book| class are also available.
%
% \clearpage
%
% \section{Implementation}\label{imp}
%
% \subsection{Option Declaration}\label{imp:opt}
%
% \subsubsection{Draft Mode}\label{imp:opt:draft}
% Specifying |draft| adds ``DRAFT'' to all 4 corners,
% plus the date centered below the footer.
% The default |draft| behaviour for the |book| class is also supported.
%    \begin{macrocode}
\newcommand{\draftmarkstyle}{\scriptsize\sffamily}
\DeclareOption{draft}{%
  \PassOptionsToClass{\CurrentOption}{book}
  \AtEndOfClass{
    \AtBeginShipout{\AtBeginShipoutUpperLeft{%
      \draftmarkstyle
      \put(+0.125in,            -0.125in-\f@size pt  ){\rlap{DRAFT}}
      \put(-0.125in+\paperwidth,-0.125in-\f@size pt  ){\llap{DRAFT}}
      \put(+0.125in,            +0.125in-\paperheight){\rlap{DRAFT}}
      \put(-0.125in+\paperwidth,+0.125in-\paperheight){\llap{DRAFT}}
      \put(+0.5\paperwidth,+0.125in-\paperheight)%
        {\makebox[0in][c]{\today}}
}}}}
%    \end{macrocode}
%
% \subsubsection{Margins}\label{imp:opt:margins}
% First, we define three lengths to help us compute the margins:
% |\margin@v| is the top and bottom margins;
% |\margin@xhi| is the inner margin offset;
% |\margin@xho| is the outer margin offset.
%    \begin{macrocode}
\newlength{\margin@v}
\newlength{\margin@xhi}\setlength{\margin@xhi}{0.5in}
\newlength{\margin@xho}\setlength{\margin@xho}{0.0in}
%    \end{macrocode}
%
% The options are based off |\margin@v|:
%    \begin{macrocode}
\DeclareOption{narrowmargins}   {\setlength{\margin@v}{0.75in}}
\DeclareOption{normalmargins}   {\setlength{\margin@v}{1.00in}}
\DeclareOption{widemargins}     {\setlength{\margin@v}{1.25in}}
\DeclareOption{extrawidemargins}{\setlength{\margin@v}{1.50in}}
%    \end{macrocode}
%
% For digital copies, |equalmargins| may be preferred.
% However, to keep the |\textwidth| consistent
% for any of the above margin options with and without |equalmargins|,
% we simply average the inner and outer offsets:
%    \begin{macrocode}
\DeclareOption{equalmargins}%
  {\setlength{\margin@xho}{0.5\margin@xhi}
   \setlength{\margin@xhi}{0.5\margin@xhi}}
%    \end{macrocode}
%
% Finally, we actually compute the margins using the above three lengths,
% and adjust the placement of the header, footer, and margin notes.
%    \begin{macrocode}
\AtEndOfClass{
  \setlength{\leftmargin}{\dimexpr\margin@v+\margin@xhi}
  \setlength{\rightmargin}{\dimexpr\margin@v+\margin@xho}
  \geometry{
    top      = \margin@v,
    bottom   = \margin@v,
    inner    = \leftmargin,
    outer    = \rightmargin,
    headsep  = \dimexpr 0.5\margin@v - \headheight,
    footskip = \dimexpr 0.5\margin@v,
    marginparwidth = \dimexpr \rightmargin - 0.25in,
    marginparsep   = 0.125in,
}}
%    \end{macrocode}
%
% \subsubsection{Line Spacing}\label{imp:opt:spacing}
% We're using the |setspace| package.
% We simply call one of the spacing commands after the class is loaded.
% So, be careful to place any line spacing commands within a group,
% or the global setting can be changed in the middle of the document.
% The default is |onehalfspacing|.
%
%    \begin{macrocode}
\DeclareOption{doublespacing}{%
  \AtEndOfClass{\doublespacing}
}
\DeclareOption{onehalfspacing}{%
  \AtEndOfClass{\onehalfspacing}
}
\DeclareOption{singlespacing}{%
  \AtEndOfClass{\singlespacing}
}
%    \end{macrocode}
%
% \subsubsection{Book Options}\label{imp:opt:misc}
%
% Finally, we try to process all remaining options using the |book| class,
% so the usual options and default values should be defined, like:
% \begin{itemize}
%   \item page size: e.g. |letterpaper|, |a4paper|, \dots
%   \item font size: e.g. |10pt|, |11pt|, |12pt|
%   \item open side for twoside: e.g. |openright|, |openany|
% \end{itemize}
%
%    \begin{macrocode}
\DeclareOption*{\PassOptionsToClass{\CurrentOption}{book}}
%    \end{macrocode}
%
% \subsubsection{Default Options \& Processing}\label{imp:opt:proc}
%
% Executing the default options and processing.
% Any remaining options should now raise an error like:
% |LaTeX Warning: Unused global option(s): ...|
%
%    \begin{macrocode}
\ExecuteOptions{letterpaper} % book
\ExecuteOptions{normalmargins,onehalfspacing,chapterhead} % ut-thesis
\ProcessOptions
%    \end{macrocode}
%
% \subsection{Initialization}\label{imp:init}
% We load the |book| class and the required packages.
%
%    \begin{macrocode}
\LoadClass{book}
\RequirePackage{picture}  % for draft mode
\RequirePackage{atbegshi} % for draft mode
\RequirePackage{geometry} % for margins etc.
\RequirePackage{setspace} % for line spacing
%    \end{macrocode}
%
% \subsection{Author Information}\label{imp:author}
%
% Getting the user inputs.
%
%    \begin{macrocode}
\renewcommand*{\author}  [1]{\gdef\@author{#1}}
\renewcommand*{\title}   [1]{\gdef\@title{#1}}
\newcommand*{\degree}    [1]{\gdef\@degree{#1}}
\newcommand*{\department}[1]{\gdef\@department{#1}}
\newcommand*{\gradyear}  [1]{\gdef\@gradyear{#1}}
%    \end{macrocode}
%
% Setting default values that will hopefully be overwritten.
%
%    \begin{macrocode}
\author    {(author)}
\title     {(title)}
\degree    {(degree)}
\department{(department)}
\gradyear  {(gradyear)}
%    \end{macrocode}
%
% \subsection{Front Matter}\label{imp:front}
%
% \subsubsection{Matter Commands}\label{imp:front:pp}
% We enforce that the |\frontmatter| and |\mainmatter| use the right
% page numbering and styles.
% Also, if we are using |[twoside]|,
% then we need to reduce all page numbers in the front matter by 1,
% so that the |abstract| is page ``ii'',
% because adjusting the |page| counter directly causes typesetting problems,
% such as incorrect alternating margins.
%    \begin{macrocode}
\newcommand{\@romanskip}[1]{\@roman{\if@twoside\numexpr#1-1\else#1\fi}}
\g@addto@macro\frontmatter{\pagenumbering{romanskip}\pagestyle{plain}}
\g@addto@macro\mainmatter {\pagenumbering{arabic}\pagestyle{headings}}
%    \end{macrocode}
%
% \subsubsection{Title Page}\label{imp:front:title}
%
% We don't enforce firm distances between lines,
% but use |\vfill| to stretch and fill the space evenly,
% except for a double-sized gap after the author name.
% There is one part of space above the title,
% while the copyright is pushed all the way to the bottom.
%
%    \begin{macrocode}
\renewcommand*{\maketitle}%
  {\thispagestyle{empty}
   \begin{center}
      \large
      \singlespacing
      \null
      \vfill
      \textsc{\@title}
      \vfill
      by
      \vfill
      {\@author}
      \vfill
      \vfill
      A thesis submitted in conformity with the requirements\\
      for the degree of {\@degree}\\[1ex]
      Graduate Department of {\@department}\\
      University of Toronto\\
      \vfill
      {\copyright} Copyright {\@gradyear} by {\@author}
   \end{center}
   {{\pagestyle{empty}\ocleardoublepage}}
  }
%    \end{macrocode}
%
% \subsubsection{Abstract Page}\label{imp:front:abs}
%
% The abstract is an environment, but it creates its own page
% (and possibly an extra empty page if using |twoside|).
% The author and title info is centered and singlespaced.
% The word ``Abstract'' uses the |\section*| style, without any numbering.
% The abstract content is doublespaced.
%
%    \begin{macrocode}
\newenvironment*{abstract}%
  {\thispagestyle{plain}
   \begin{center}
     \singlespacing
      {\@title}\\[2ex]
      {\@author}\\
      {\@degree}\\[1ex]
      Graduate Department of {\@department}\\
      University of Toronto\\
      {\@gradyear}\\
      \section*{Abstract}
   \end{center}
   \begingroup
   \doublespacing}%
  {\par\endgroup\cleardoublepage}
%    \end{macrocode}
%
% \subsubsection{Dedication}\label{imp:front:ded}
%
% As described above.
%
%    \begin{macrocode}
\newenvironment*{dedication}%
  {\thispagestyle{plain}
   \null
   \vfill
   \begin{flushright}}%
  {\end{flushright}
   \vfill
   \vfill
   \clearpage}
%    \end{macrocode}
%
% \subsubsection{Acknowledgments}\label{imp:front:ackn}
%
% As described above.
%
%    \begin{macrocode}
\newenvironment*{acknowledgements}%
  {\thispagestyle{plain}
   \begin{center}
   \section*{Acknowledgments}
   \end{center}
   \begingroup}%
  {\endgroup\clearpage}
%    \end{macrocode}
%
% \subsection{Page Styles}\label{imp:hf}
%
% \subsubsection{Blank Pages}\label{imp:hf:blank}
% By default, all blank pages will have page style |plain|,
% but the original definition is stored in |\ocleardoublepage|.
%    \begin{macrocode}
\let\ocleardoublepage\cleardoublepage
\def\cleardoublepage{{\newpage\pagestyle{plain}\ocleardoublepage}}
%    \end{macrocode}
%
% \subsubsection{Headers \& Footers}\label{imp:hf:hf}
% We redefine the |headings| page style
% with a new formatting hook |\headerstyle{}|,
% but is otherwise similar to the original |headings|.
%    \begin{macrocode}
\newcommand{\headerstyle}[1]{\footnotesize\MakeUppercase{#1}}
\if@twoside
\renewcommand*{\ps@headings}%
  {\let\@mkboth\markboth
   \let\@oddfoot\@empty
   \let\@evenfoot\@empty
   \def\@oddhead{\headerstyle{\rightmark\hfil\thepage}}%
   \def\@evenhead{\headerstyle{\thepage\hfil\leftmark}}%
   \def\chaptermark##1{\markboth{%
     \if@mainmatter\headerstyle{\@chapapp\ \thechapter.\ ##1}\fi}{}}
   \def\sectionmark##1{\markright{%
     \if@mainmatter\headerstyle{\thesection.\ ##1}\fi}}}
\else
\renewcommand*{\ps@headings}%
  {\let\@mkboth\markboth
   \let\@oddfoot\@empty
   \let\@evenfoot\@empty
   \def\@oddhead{\headerstyle{\rightmark\hfil\thepage}}%
   \def\chaptermark##1{\markright{%
     \if@mainmatter\headerstyle{\@chapapp\ \thechapter.\ ##1}\fi}}}
\fi
%    \end{macrocode}
%
% Default page style.
%    \begin{macrocode}
\pagestyle{headings}
%    \end{macrocode}
%
% \subsection{Spacing Adjustments}\label{imp:adj}
% The default spacing below captions is too small
% for captions on top of floats (e.g.\ for tables),
% so we make it consistent above and below.
%
%    \begin{macrocode}
\setlength\abovecaptionskip{1ex}
\setlength\belowcaptionskip{1ex}
%    \end{macrocode}
%
\endinput