\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/01/19} \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{}| \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{}|\end{desc} Sets the due date in full. \begin{desc}|\instructor{}|\end{desc} Sets the instructor name. \begin{desc}|\course{}|\end{desc} Sets the course name in full. \begin{desc}|\coursenumber{}|\end{desc} Sets the course name by number; e.g. |\coursenumber{21a}| gives a course of ``\cosi{21a}''. \begin{desc}|\assignment{}|\end{desc} Sets the assignment name in full. \begin{desc}|\problemsetnumber{}|\end{desc} Sets the assignment name by number; e.g. |\problemsetnumber{3}| gives an assignment of ``Problem Set 3''. \begin{desc} |\setcodefont[]{}| \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}[]...\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. || 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[]| \end{desc} Prints a sub-problem, i.e.\ a |\subsection|. It doesn't do very much at the moment. \begin{desc} |\Th[]{
}| \end{desc} Typesets a table header in bold-face. || defaults to |l|. Useful for when a column is wrapped in a math environment. \begin{desc} |\begin{pseudocode}[]...\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}[]...\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. || 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}[]...\end{java}| \end{desc} Tragically-common shorthand environment for a listing of Java code. || is passed directly to the \ctan{listings} package. \begin{desc} |\begin{scheme}[]...\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. || is passed directly to the \ctan{listings} package. \begin{desc} |\begin{ganttschedule}[]...\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{}{}| \end{desc} Draw a burst for process || of time 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 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{}| \end{desc} Typesets an acronym. The || 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{}|\end{desc} An abbreviation for |\textsc|. \begin{desc}|\Rm{}|\end{desc} An abbreviation for |\textrm|. \begin{desc}|\Up{}|\end{desc} An abbreviation for |\textup|. \begin{desc}|\Bf{}|\end{desc} An abbreviation for |\textbf|. \begin{desc}|\It{}|\end{desc} An abbreviation for |\textit|. \begin{desc}|\Tt{}|\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.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}