\documentclass{ltxguidex}
\usepackage{textcomp} % needed for listings
\usepackage{hologo} % xetex, etc. logos
\usepackage{changelog}
\newcommand{\bps}{\ltxclass{brandeis-problemset}}
\newcommand{\fontspecok}{\hologo{XeLaTeX} or \hologo{LuaTeX}}
\newcommand{\cosi}[1]{\textsc{cosi}~#1}
\newnotice{todo}{To-do}

\usepackage{fontspec}
\setmainfont{Tiempos Text}
\usepackage{FiraSans}
\usepackage{FiraMono}

\lstnewenvironment{latexfile}[1]
	{\lstset{
		language=[LaTeX]TeX,
		numbers=none,
	}}
	{}

\author{Rebecca Turner\thanks{Brandeis University; \email{rebeccaturner@brandeis.edu}}}
\title{The \bps\ Document Class}
\date{2019/02/14 0.4.4}
\begin{document}
\maketitle
\begin{abstract}

	Brandeis University's computer science (``\textsc{cosi}'') courses
	often assign ``problem sets'' which require fairly rigorous
	formatting. The \ctan{brandeis-problemset} document class, which
	extends \ltxclass{article}, provides a simple way to typeset these
	problem sets in \LaTeX.

	Although \bps\ is compatible with all \LaTeX\ flavors, \fontspecok\
	is recommended for \ctan{fontspec} support.

\end{abstract}

\begin{note}
	The \bps\ document class should be considered experimental; the only
	stable \textsc{api} is that of the |problem| environment.
\end{note}

\begin{note}
	Browse the sources, contribute, or complain at \\
	\https{github.com/9999years/brandeis-problemset}
\end{note}

\tableofcontents
\vfill
\pagebreak

\section{Default behavior}

\bps\ provides packages and well-formatted constructs (notably the
|problem| environment) for problem-set writers. \bps\ will always render
its body copy as a Times variant (\ctan{stix} for plain \LaTeX\ or
\ctan{xits} with \fontspecok) and always contains a useful header (which
contains the page number, author's name, course, instructor, and assignment
due date).

\subsection{Default packages loaded}

\begin{enumerate}
\item \ctan{hyperref}, for a nicely-linked table of contents;
	|\href||{url}{label}|.
\item \ctan{listings}, for verbatim code listings (including the
	|assembly|, |java|, and |pseudocode| environments).
\item \ctan{xcolor}, for gray line numbers in code listings (and perhaps
	colored listings in the future); e.g.\ |\color||{gray}|.
\item \ctan{enumitem} for better control over the margins and spacing of
	the |enumerate|, |itemize|, and |description|
	environments.
\item Math packages: \begin{enumerate}
	\item \ctan{amsmath} for tons of useful math commands, including
		|\text|, |\intertext|, and |\boxed| as well as the |bmatrix|,
		|multiline|, |gather|, |align|, and
		|alignat| environments. See
		\href{http://texdoc.net/texmf-dist/doc/latex/amsmath/amsldoc.pdf}{``User's
		Guide for the \package{amsmath} Package''} for a more
		complete listing.
	\item \ctan{mathtools} for other useful/utilitarian commands.
\end{enumerate}
\item Table packages: \begin{enumerate}
	\item \ctan{multirow} for cells spanning multiple rows.
	\item \ctan{booktabs} for good-by-default tables and the |\cline|
		macro.
	\item \ctan{tabu}, the best table package with dynamically resizable
		columns, easy creation of new column types, and more.
\end{enumerate}
\end{enumerate}

\section{Class configuration}

\subsection{Class options}

Class options are limited to configuration options which require the loading
of fonts or other packages; ``string'' settings like the assignment's due
date are configured either with the |\problemsetsetup| command or the
commands described in section~\ref{sss:configcommands}.

\begin{keys}
	\key{gantt} Load packages for the |ganttschedule| environment.
	\key{scheme} Define the |scheme| language for the \ctan{listings}
		package as well as the |scheme| shorthand environment.
	\key{antonella} Use Dr.\ Antonella DiLillio's preferred styles (Courier
		for code)
	\key{solutions} Include |solution| environments in compiled
		document.
\end{keys}

\subsection{Setting options after loading \bps}

\begin{desc}
|\problemsetsetup{<options>}|
\end{desc}
Sets global \bps\ options.

\begin{keys}
\key{course}[\m{course name}]
	Course name in full.
\key{coursenumber}[\m{course number}]
	Course name shorthand; use \texttt{21a} for ``\cosi{21a}''.
\key{assignment}[\m{assignment name}]
	Assignment name in full.
\key{number}[\m{problem set number}]
	Assignment name shorthand; use \texttt{3} for ``Problem Set 3''.
\key{duedate}[\m{due date}]
	Due date, e.g.\ \texttt{2018-10-18}; not parsed at all, but
	\href{https://en.wikipedia.org/wiki/ISO_8601}{\textsc{iso} 8601
	dates} are highly recommended.
\key{instructor}[\m{course instructor}]
	Course instructor.
\key{author}[\m{your name}]
	Alternate interface for the |\author| command.
\key{date}[\m{document date}]
	Alternate interface for the |\date| command.
\key{codefont}[\m{fontspec font name}]
	With \fontspecok, pass the given font to |\setmonofont| and enable
	Unicode shortcuts for the |pseudocode| environment. (If you need to
	specify options to |\setmonofont|, use |\setcodefont|.)
\key{gantt}[\bool][false]
	Load packages for the |ganttschedule| environment.
\key{antonella}[\bool][false]
	Use Dr.\ Antonella DiLillio's preferred styles (Courier for code)
\key{solutions}[\bool][false]
	Include |solution| environments in compiled document.
\end{keys}

\subsubsection{Configuration commands}%
\label{sss:configcommands}

\bps\ additionally provides a number of configuration commands for setting a
single opption with similar interfaces as the \TeX\ macros |\author|,
|\title|, and |\date|.

\begin{desc}|\duedate{<date>}|\end{desc} Sets the due date in full.
\begin{desc}|\instructor{<name>}|\end{desc} Sets the instructor name.
\begin{desc}|\course{<name>}|\end{desc} Sets the course name in full.
\begin{desc}|\coursenumber{<number>}|\end{desc} Sets the course name by
	number; e.g. |\coursenumber{21a}| gives a course of ``\cosi{21a}''.
\begin{desc}|\assignment{<name>}|\end{desc} Sets the assignment name in
	full.
\begin{desc}|\problemsetnumber{<number>}|\end{desc} Sets the assignment name
	by number; e.g. |\problemsetnumber{3}| gives an assignment of
	``Problem Set 3''.

\begin{desc}
|\setcodefont[<fontspec options>]{<fontspec font name>}|
\end{desc}
Sets the monospaced font to \meta{font name} and uses it for shortcuts in
the |pseudocode| environment.

\subsection{Practical usage}

You may find it useful to define a customized document class for each
course. There's no reason to install these to some system-wide directory; it
makes sense for them to live in the same directory as the problem set source
files. For instance, \filename{cosi21a.cls} might read:

\begin{latexfile}{cosi21a.cls}
\LoadClass[antonella]{brandeis-problemset}

% set course/author data
\problemsetsetup{
	instructor=Dr.\ Antonella DiLillio,
	coursenumber=21a,
}
\author{Rebecca Turner}

% get a prettier code font -- these can be pretty big so they're not
% loaded by default
\setcodefont[
  Extension = .otf,
  UprightFont = *-Regular,
  BoldFont = *-Bold,
]{FiraMono}
\end{latexfile}

and then \filename{ps1.tex} might read:

\begin{latexfile}{ps1.tex}
\documentclass{cosi21a}
% stuff specific to this assignment
\problemsetnumber{1}
\duedate{2018-10-29}
\begin{document}
% etc.
\end{document}
\end{latexfile}

See section~\ref{sec:example} for a more complete example.

\section{User commands and environments}

\bps\ provides a number of commands for typesetting problems.

\begin{desc}
|\begin{problem}[<options>]...\end{problem}|
\end{desc}
Defines a problem. A problem is set 1~inch from the left margin (although
this amount may be customized by modifying the |\problemindent| length) and
begins a new page. |<options>| may include:
\begin{keys}
\key{title}[\m{problem title}]
	Displayed after ``Problem'' and the problem's number.
\key{number}[\m{problem number}]
	If given, the problem-number counter will not advance. The number
	must be robust, because it goes inside a |\section|.
\key{pagebreak}[\bool][true]
	Add a pagebreak before the problem?
\key{label}[\m{problem label}]
	Adds a custom label to the problem with |\label| that can be used
	with |\ref|. I recommend prefixing your problem labels with |p:| as
	in |p:big-o-proofs|.
\key{part}[\m{part name}]
	Indicates that this problem starts a new ``part'' of the assignment;
	actually calls |\part| under the hood.
\key{partlabel}[\m{part label}]
	Adds a custom label to this part in the same fashion as the
	\option{label} key.
\end{keys}

Vertical material is allowed in a~|problem|.

\begin{desc}
|\begin{solution}...\end{solution}|
\end{desc}

Defines a solution for a problem; a solution prints in blue and is excluded
from the compiled document entirely unless the \option{solutions} package
option is given.

In this way, the same \extension{tex} file can serve as both a postable
assignment prompt and an answer key.

\begin{note}
	The style of solutions is customizable by redefining
	|\solutionstyle|; it's defined to |\color{blue}| by default.
\end{note}

\begin{desc}
|\subproblem[<problem description>]|
\end{desc}
Prints a sub-problem, i.e.\ a |\subsection|. It doesn't do very much at the
moment.

\begin{desc}
|\Th[<column spec>]{<header text>}|
\end{desc}

Typesets a table header in bold-face. |<column spec>| defaults to |l|.
Useful for when a column is wrapped in a math environment.

\begin{desc}
|\begin{pseudocode}[<keywords>]...\end{pseudocode}|
\end{desc}
Prints pseudocode.\footnote{Designed for \cosi{21a} as taught by Dr.\
Antonella DiLillo}

Several ``shortcuts,'' which replace a source-code sequence like
\texttt{->} with a symbol like $\rightarrow$, are shown in
table~\ref{tab:pseudocode}.

These shortcuts display in |\pseudocodesymbolfont| (default:
|\ttfamily|), which may be redefined if you prefer something else. The
easiest way to change |\pseudocodesymbolfont| is with |\setcodefont|. If
you use the \option{antonella} option with \fontspecok, \bps\ will load
\ctan{lm-math} and display the symbols seen in table~\ref{tab:pseudocode},
which look significantly better with Courier than \ctan{stix}' symbols.

\begin{table}[h]
	\centering
	\caption{Shortcuts provided by the \texttt{pseudocode}
	environment}%
	\label{tab:pseudocode}
	\begin{tabular}{lll}
	\Th{Input}    & \Th{Display}  & \Th{Codepoint} \\
	\ttfamily <-  & $\leftarrow$  & U+2190 \\
	\ttfamily ->  & $\rightarrow$ & U+2192 \\
	\ttfamily (/) & $\emptyset$   & U+2205 \\
	\ttfamily inf & $\infty$      & U+221E \\
	\ttfamily !=  & $\ne$         & U+2260 \\
	\ttfamily >=  & $\ge$         & U+2265 \\
	\ttfamily <=  & $\le$         & U+2264 \\
	\end{tabular}
\end{table}

\begin{todo}
	Improve the font selection mechanism; maybe provide a command for
	each symbol?
\end{todo}

\begin{todo}
	If your \TeX\ engine doesn't support \textsc{utf}-8 input, the
	shortcuts might appear totally blank or garbled. Good luck! It will
	surely work with \fontspecok.
\end{todo}

\begin{latexcode}
% the optional [Bar] makes [Bar] bold like the other keywords
\begin{pseudocode}[Bar]
Bar(a, n)
    Input:  two integers, a and n
    Output: a^n
    k <- n # k is a counter
    b <- 1
    c <- a
    while k > 0 do
        if k mod 2 = 0 then
            k <- k/2
            c <- c * c
        else
            k <- k - 1
            b <- b * c
    return b
\end{pseudocode}
\end{latexcode}

\begin{desc}
|\begin{assembly}[<listings options>]...\end{assembly}|
\end{desc}
Typesets assembly code.\footnote{Designed for \cosi{131a} as taught by Dr.\
Liuba Shrira} Several considerations are taken into account; most notably,
line numbers are printed as \texttt{x + n}, where $n$ starts at 0 and counts
by 4; the line number actually indicates the instruction's location in
memory as an offset from the program start. Additionally, all valid
instructions are treated as keywords and styled appropriately.

|<listings options>| is passed directly to the \ctan{listings} package.

\begin{latexcode}
\begin{assembly}
        LOAD  R4, $200       ; sum addr
        LOAD  R1, =0         ; sum
        LOAD  R2, =0         ; i
        LOAD  R3, =0         ; j
        BR    OUTER          ; we know i < 10
INNER:  ADD   R1, R3         ; sum += j
        INC   R3             ; j++
OUTER:  BLT   R3, R2, INNER  ; while j < i goto inner
        INC   R2             ; i++
        LOAD  R3, =0         ; j = 0
        BLT   R2, =10, OUTER ; while i < 10
        STORE R1, @R4        ; store sum into sum address
        HALT
\end{assembly}
\end{latexcode}

\begin{desc}
|\begin{java}[<listings options>]...\end{java}|
\end{desc}
Tragically-common shorthand environment for a listing of Java code.

|<listings options>| is passed directly to the \ctan{listings} package.

\begin{desc}
|\begin{scheme}[<listings options>]...\end{scheme}|
\end{desc}
Shorthand environment for a listing of Scheme code, useful for \cosi{121b}.
Requires the \option{scheme} package option to be loaded.

|<listings options>| is passed directly to the \ctan{listings} package.

\begin{desc}
|\begin{ganttschedule}[<total cell count>]...\end{ganttschedule}|
\end{desc}
An environment for drawing Gantt charts indicating process scheduling. The
mandatory argument indicates how small the grid should be; \texttt{19}
subdivides the line into 19 cells.

To use the |ganttschedule| environment, make sure to use the
\option{gantt} package option.

Within a |ganttschedule|, use the |\burst| command to indicate an
active process (i.e.\ a process burst).

\begin{note}
	The charts |ganttschedule| draws aren't actually really proper Gantt
	charts, which can indicate parallel activities; however, that's what
	Liuba calls them, so that's what they're called here.
\end{note}

\begin{desc}
|\pid{<pid>}{<burst length>}|
\end{desc}
Draw a burst for process |<pid>| of time length |<burst length>|.

\begin{latexcode}
\begin{ganttschedule}{19}
	\burst{2}{1}
	\burst{4}{1}
	\burst{3}{2}
	\burst{5}{5}
	\burst{1}{10}
\end{ganttschedule}
\end{latexcode}

\begin{note}
	Because |ganttschedule| relies on \ctan{tikz}, \ctan{fp}, and
	\ctan{calc}, it can add significantly to document compile times. If
	you intend to use the |ganttschedule| environment, make sure to use
	the \option{gantt} class option or set \option{gantt} in
	|\problemsetsetup|. If you fail to include the \option{gantt}
	option, you will see an error message:

\begin{latexcode}
! Package brandeis-problemset Error: ganttschedule enviornment not loaded in preamble.

See the brandeis-problemset package documentation for explanation.
Type  H <return>  for immediate help.
l.4 \burst
	{1}{1}
? H
Did you mean to use the 'gantt' option for the brandeis-problemset document class?

\end{latexcode}
\end{note}

\subsection{General formatting commands}

\begin{desc}
|\ac{<acronym>}|
\end{desc}
Typesets an acronym. The |<acronym>| should be lowercase (e.g.\ |\ac{cpu}|
rather than |\ac{CPU}|). Currently, |\ac| simply delegates to |\textsc|. In
the future, I'd like to support a bit of letterspacing; ``for abbreviations
and acronyms in the midst of normal text, use spaced small
caps.''\footnote{\textit{The Elements of Typographic Style} by Robert
Bringhurst, 2nd.\ ed, \S\ 3.2.2}

\begin{desc}|\Sc{<text>}|\end{desc}
An abbreviation for |\textsc|.
\begin{desc}|\Rm{<text>}|\end{desc}
An abbreviation for |\textrm|.
\begin{desc}|\Up{<text>}|\end{desc}
An abbreviation for |\textup|.
\begin{desc}|\Bf{<text>}|\end{desc}
An abbreviation for |\textbf|.
\begin{desc}|\It{<text>}|\end{desc}
An abbreviation for |\textit|.
\begin{desc}|\Tt{<text>}|\end{desc}
An abbreviation for |\texttt|.

\section{Example}\label{sec:example}

A brief example usage of \bps\ follows. For a longer, more in-depth example,
see
\href{https://github.com/9999years/brandeis-problemset/blob/master/example.tex}{\filename{example.tex}
in the \bps\ repository.}

\begin{latexcode}
\documentclass[gantt]{brandeis-problemset}
\author{Rebecca Turner}
\problemsetsetup{
	coursenumber=21a,
	instructor=Dr.\ Liuba Shrira,
	duedate=2018-10-20,
	number=3,
}
\newcommand{\io}{\ac{io}}
\newcommand{\cpu}{\ac{cpu}}
\begin{document}

\begin{problem}
	Write an assembly program!
\end{problem}

\begin{assembly}
        LOAD  R1, $200      ; A = (program location) + 200
        LOAD  R2, =1        ; i = 1
\end{assembly}

\begin{problem}
	What does this algorithm do? Analyze its worst-case running time and
	express it using big-O notation.

\begin{pseudocode}[Foo]
Foo(a, n)
	Input:  two integers, a and n
	Output: a^n
	k <- 0
	b <- 1
	while k < n do
		k <- k + 1
		b <- b * a
	return b
\end{pseudocode}
\end{problem}

$\Rm{Foo}(a, n)$ computes $a^n$, and will run in $O(n)$ time always.

\begin{problem}[number=5.4]
	Consider the following set of processes, with the length of the
	\cpu\ burst given in milliseconds:

	\begin{center}
		\begin{tabu} to 0.25\linewidth{X[1,$]rr}
			\Th{Process} & \Th{Burst time} & \Th{Priority} \\
			P_1 & 10 & 3 \\
			P_2 & 1 & 1 \\
			P_3 & 2 & 3 \\
			P_4 & 1 & 4 \\
			P_5 & 5 & 2 \\
		\end{tabu}
	\end{center}%$

	Draw a Gantt chart to illustrate the execution of these processes
	using the \ac{sjf} scheduling algorith.
\end{problem}

\begin{ganttschedule}{19}
	\burst{2}{1}
	\burst{4}{1}
	\burst{3}{2}
	\burst{5}{5}
	\burst{1}{10}
\end{ganttschedule}
\end{document}
\end{latexcode}

\begin{changelog}[author=Rebecca Turner]
\begin{version}[v=0.4.4, date=2019-02-14]
\changed
	\item Changed Times body copy font from \ctan{tex-gyre}'s Termes to
	the newer \ctan{stix2-otf} (for \fontspecok) and \ctan{stix2-type1}
	(for other \TeX\ engines) --- the \textsc{stix2} fonts are somewhat
	unique amongst Times-likes in that they contain small caps.

	\item Redefined |\Re| to print in blackboard-bold.
\end{version}

\shortversion{v=0.4.3, date=2019-01-20,
	changes={Fixed typos in license file, fixed distributed
	documentation \extension{pdf}.}}

\begin{version}[v=0.4.2, date=2019-01-19]
\added
	\item |author| and |date| keys added to |\problemsetsetup| to
	simplify class-wide configuration.
\fixed
	\item Fixed definitions for |\duedate|, |\instructor|, etc.\ to
	avoid spurious errors due to undefined commands.
\changed
	\item Translated documentation to the new \ctan{ltxguidex} document
	class for added beauty.
	\item Re-licensed \bps\ to the \textsc{lppl} v1.3c for easy transfer of
	maintenence in the future.
\end{version}

\shortversion{v=0.4.1, date=2019-01-03,
	changes={Updated |scheme| environment to properly recognize all
	primitive functions, added syntax coloring to all code.}}

\begin{version}[v=0.4.0, date=2018-12-20]
\added
	\item |solution| environment and \option{solutions} class
		option.
	\item |scheme| shorthand environment and \option{scheme} class
		option.
\fixed
	\item Boolean class options being overwritten by keys defined for
		|\problemsetsetup|.
	\item Title-formatting errors
\removed
	\item Assignment- and course-specific class options
		\option{duedate}, \option{assignment}, \option{instructor},
		and \option{course}. These settings should be configured
		with either |\problemsetsetup| or their specific commands.
		(|\duedate|, |\instructor|, etc.).
\end{version}

\begin{version}[v=0.3.0, date=2018-10-24]
\added
	\item This changelog.
	\item Support for |\part|s and referencing problems.
	\item Options to |problem| environment: \option{part},
		\option{label}, and \option{partlabel}.
	\item |\maketitle| (contrast with |\maketitlepage|).
\end{version}

\begin{version}[v=0.2.0, date=2018-10-20]
\changed
	\item Class renamed to from \ltxclass{problemset} to \bps.
\added
	\item A license header.
	\item |ganttschedule| environment.
	\item Additional keywords for |pseudocode| environment:
		\texttt{and}, \texttt{or}, \texttt{nil}, and \texttt{len}.
	\item |\ac| command for acronyms.
	\item An example document.
\end{version}

\shortversion{v=0.1.0, date=2018-10-19,
	changes=Initial beta as \ltxclass{problemset}.}
\end{changelog}
\end{document}
