seu-ml-assign-doc.tex

%! TEX program = pdflatex

\documentclass[twoside]{seu-ml-assign}

\usepackage{booktabs}
\usepackage{colortbl}
\usepackage{multicol}
\usepackage{threeparttable}

\title{Documentation}
\author{Teddy van Jerry}
\studentID{}
\instructor{TeX - LaTeX Stack Exchange}
\date{\today}
\duedate{20:00 March 30, 2022}
\assignno{1.1}
\semester{LaTeX Template}
\mainproblem{Template Documentation}

\renewcommand{\sectionheadname}{Section}
\renewcommand{\pdftitleadditionalname}{}
\definecolor{tblgray}{rgb}{ .906,  .902,  .902}

% option for tabular with '\midrule'
\aboverulesep = 0mm \belowrulesep = 0mm

\newcommand{\grayrow}{\rowcolor[rgb]{ .906,  .902,  .902}}

\begin{document}
  \maketitle

  \problem{Basic Information of This Template Class}

    Despite this \textit{SEU-ML-Assign} class is dedicated to Southeast University as the Machine Learning assignment \LaTeX{} template both for teachers and students, it can also be used for other schools.
    In the near future, it will eventually become an elegant template for all assignment requirememts.

    \begin{table}[htbp]
      \bgroup
        \def\arraystretch{1.2}
        \setlength{\tabcolsep}{1.5em}
        \rowcolors{1}{tblgray}{white}
        \begin{tabular}{ll}
        \toprule
          \textbf{Package Class Name} & \texttt{seu-ml-assign} \\
          \textbf{Version} & 1.1 (2022/03/28) \\
          \textbf{Description} & \LaTeX{} Template for Southeast University Machine Learning Assignment \\
          \textbf{Author} & Teddy van Jerry (Wuqiong Zhao) \\
          \textbf{Maintainer} & Teddy van Jerry (Wuqiong Zhao) \\
          \textbf{GitHub Repository} & \url{https://tvj.one/ml-tex} \\
          \textbf{Issues} & \url{https://tvj.one/ml-tex/issues} \\
          \textbf{CTAN Package} & \url{https://www.ctan.org/pkg/seu-ml-assign} \\
          \textbf{Information Page} & \url{https://seu-ml-assign.github.io} \\
          \textbf{Open Source License} & MIT License (\url{https://tvj.one/ml-tex/blob/master/LICENSE}) \\
        \bottomrule
        \end{tabular}%
      \egroup
    \end{table}

    You can contact me at \href{mailto:me@tvj.one}{me@tvj.one} for support.

  \problem{Class Options}

    To use this template, put \texttt{seu-ml-assign.cls} file under the same directory with your main \texttt{tex} file.
    \begin{lstlisting}[language=tex,numbers=none]
\documentclass{seu-ml-assign} % SEU Machine Learning Assignment Template
    \end{lstlisting}
    The page size is A4 paper. There are 8 supported options:
    \begin{table}[htbp]
      \bgroup
        \def\arraystretch{1.2}
        \setlength{\tabcolsep}{1.5em}
        \rowcolors{1}{white}{tblgray}
        \begin{tabular}{llc}
          \toprule
          \textbf{Option} & \textbf{Description} & \textbf{Default} \\
          \midrule\midrule
          \texttt{solution} & Write solutions (for students). & \Large\textbullet \\
          \texttt{problem} & Write problem sets (for instructors). & \\
          \hline
          \texttt{oneside} & One-sided document. & \Large\textbullet \\
          \texttt{twoside}& Two-sided document. & \\
          \hline
          \texttt{9pt} & Set font size as 9 points. & \\
          \texttt{10pt} & Set font size as 10 points. & \Large\textbullet \\
          \texttt{11pt} & Set font size as 11 points. & \\
          \texttt{12pt} & Set font size as 12 points. & \\
          \hline
          \texttt{lang=} & Set the language. (English as \texttt{en}, Chinese as \texttt{cn}.) & \texttt{en} \\
        \bottomrule
      \end{tabular}%
      \egroup
    \end{table}

    For example, a 10pt, two-sided document for instructors to create an assignment consisting of problem sets should use

    \begin{lstlisting}[language=tex,numbers=none]
\documentclass[10pt,twoside,problem]{seu-ml-assign} % The 10pt option can be omitted.
    \end{lstlisting}

    With the \texttt{twoside} option, the header will switch style every page, as is the case in this documentation.
    In contrast, the sample file uses the \texttt{oneside} option.

    There are several differences between the \texttt{solution} mode and \texttt{problem} mode,
    including the preset texts on the document (for example the student name is not shown in the \texttt{problem} mode) and some properties can only be used with the \texttt{problem} mode which will be elaborated on in \S\ref{subsec:prob_only_properties}.

  \problem{Document Properties}

    \subproblem{Fields}

      There are several fields to set.
      The \verb|\mainproblem{}| can be left empty.
      Consider the following example used in the sample file:
      \begin{lstlisting}[language=tex,numbers=none]
\title{Assignment}                       % Document Type: assignment, quiz, etc.
\author{Teddy van Jerry}                 % Your Name
\studentID{61520522}                     % Your Student ID
\instructor{TeX - LaTeX Stack Exchange}  % The Name of Your Instructor
\date{\today}                            % The Submission or Release Date
\duedate{20:00 March 21, 2022}           % The Time the Assignment is Due
\assignno{1}                             % Assignment Number
\semester{SEU --- 2022 Spring}           % Semester
\mainproblem{Linear Algreba}             % The Main Problem or Topic
      \end{lstlisting}
    
      With these fields set, you can use the command \verb|\maketitle| to print the title.
      At the same time, the metadata for the PDF document is automatically set.

    \subproblem{Problem Mode Only Properties}\label{subsec:prob_only_properties}
    One of the fields \verb|\author{}| and \verb|\instructor{}| can be omitted or set as empty provided that they are the same.

  \problem{Section Title (Problem) Settings}

    \subproblem{Normal Title}\label{subsec:section_normal_title}

      The title of a problem can be set as \verb|\problem{This is a Section Title}| or uses a lower level command \verb|\section{This is a Section Title}|.
      There are two slight different between these two ways.
      \begin{itemize}
        \item The name in the table of contents (ToC) using \verb|\problem{}| will add the section/problem number before the section/problem title name.
        \item The optional argument of \verb|\section{}| will set the name in the ToC which is by default in \LaTeX{} in the format of \verb|\section[<ToC Name>]{<Section Title Name>}|.
        By contrast, the optional argument in \verb|\problem{}| sets the problem points as is detailed in \S\ref{subsec:problem_with_points}.
      \end{itemize}
      \verb|\section[\thesection~<Title>]{<Title>}|
      is equivalent to
      \verb|\problem{<Title>}| or \verb|\problem[]{<Title>}|.
      
      
    \subproblem{Unnumbered Title}

      Use the \verb|\section*{}| or \verb|\problem*{}| to get an unnumbered section.\vspace{-8mm}

      \problem*{This is an Unnumbered Problem}

      This title will also not appear in the ToC or bookmarks of the PDF.

    \subproblem{Problem with Points}\label{subsec:problem_with_points}

      The points of a problem can be set using command \verb|\problempts{xxx}| before calling the \verb|\section{}| command.
      These two commands can be simplified to \verb|\problem[xxx]{}|.
      For example, using the command \verb|\problem[15]{This is a Problem Worth 15 Points}| will have:\footnote{This title is actually faked in this documentation because I do not want the ToC of this documentation contaminated. But it will look the same.}\vspace{-8mm}

      \renewcommand{\sectionheadname}{Problem}
      \setproblem{1}

      % \problem[15]{This is a Problem Worth 15 Points}
      % Here I have to 'fake' this title
      % because I do not want it to ruin the ToC.
      \problempts{15}
      \section*{Problem 1:\hspace{0.33em}This is a Problem Worth 15 Points}
      Note that if the point is an empty string, the point information will not be shown.

    \subproblem{Long Title Compatibility}
      There is also no problem if the section title is too long.\footnote{This title is also faked.}\vspace{-8mm}

      % Here I have to 'fake' this title again
      % because I do not want it to ruin the ToC.
      \setproblem{2}
      \problempts{20}
      \section*{Problem 2:\hspace{0.33em}I Don't Think that Anyone Will Enjoy Themselves Seeing a Very\\\hspace{5.2em}Very Long Problem That is Worth Twenty Points in this Machine\\\hspace{5.2em}Learning Course}

      \renewcommand{\sectionheadname}{Section}
      \setproblem{4}

    \subproblem{Section Title Name}
      The name of the section (default name as \texttt{problem}) can be changed by using \verb|\renewcommand{\sectionheadname}{Name}|.

    \subproblem{Section Number}
    The number of the section can be changed, for example \verb|\texttt{\setproblem{4}}| will make the next section number be \texttt{5}.
    For experienced \LaTeX{} users to understand, this command actually change the section counter.

    \subproblem{Solution Declaration}
    You can use \verb|\startsolution| to declare you start writing the solution.
    This will reset the section number and it is especially useful when your document contains problems and solutions as two separate parts.
    There is an option \texttt{print} and if you use \verb|\startsolution[print]| you will get:
    \vspace{-\baselineskip}

    \startsolution[print]
    and the word \textsc{Solution} can be changed using command \verb|\renewcommand{\solutionname}{Other Name}|.


  \setproblem{4}
  \problem{Subsection Title (Sub Problem) Settings}

    \subproblem{Normal Title} This is a normal title using command \verb|\subproblem{Normal Title}| or alternatively the command \verb|\subsection{Normal Title}|.
    There is a slight difference between these two commands which is similar to the case stated in \S\ref{subsec:section_normal_title}.
    The command
    \verb|\subproblem{}| adds the sub problem number in ToC and bookmarks.
    \verb|\subsection[(\arbic{subsection}) <Title>]{<Title>}|
    is equivalent to \verb|\subproblem{<Title>}|.

    \subproblem{} Use \verb|\subproblem{}| or \verb|\subsection{}| if only the sub problem number is required (like this line).

    \subproblem{Subsection Number} Similar to \verb|\setproblem{}|, there is also \verb|\setsubproblem{}|.

    \subproblem{Subsubsection (Sub Sub Problem)} For completeness,
    \verb|\subsubsection{}| and \verb|\subsubproblem{}| are provided.
    One example is \S\ref{subsubsec:hint}, where
    \verb|\subsubsection[\arbic{subsubsection}. <Title>]{<Title>}|
    is equivalent to \verb|\subsubproblem{<Title>}|.

  \problem{Other Tools}

    \subproblem{Equation Numbering} The equation number is within the section (problem), for example
      \begin{equation}\label{eq:eq_num_example}
        \mathrm{det}(\mathbf{A})=1\times\begin{vNiceArray}{rr}
          -5&3\\-6&4
        \end{vNiceArray}-(-3)\times\begin{vNiceArray}{rr}
          3&3\\6&4
        \end{vNiceArray}+3\times\begin{vNiceArray}{rr}
          3&-5\\6&-6
        \end{vNiceArray}=1\times(-2)+3\times(-6)+3\times 12=16,
      \end{equation}
      which uses the \texttt{equation} environment and can be referenced using the command \verb|\eqref{eq:xxx}|
      with a corresponding \verb|\label{eq:xxx}| in Eq.~\eqref{eq:eq_num_example}.

    \subproblem{Maths Packages} Maths Package \texttt{mathtools}, \texttt{amssymb}, \texttt{amsthm}, \texttt{bm} and \texttt{nicematrix} are automatically loaded.
    The \texttt{nicematrix} package is especially powerful in terms of writing a matrix.
    You can find its documentation at \url{https://ctan.org/pkg/nicematrix}.
    It is worth noting that \texttt{nccmath} can lead to potential subsection (sub problem) title indentation problem and therefore should not be loaded.

    \subproblem{Theorem Environment} Environments \texttt{theorem}, \texttt{proposition}, \texttt{lemma}, \texttt{corollary} have been defined.
    For example:
    \begin{lemma}
      This is a lemma. Its numbering is within the section.
      You can create such environment using the code \verb|\begin{lemma} Your lemma contents here. \end{lemma}|.
      % The same code pattern applies to \texttt{theorem}, \texttt{proposition} and \texttt{corollary}.
    \end{lemma}

    \subproblem{Additional Math Operator} The additional math operator is listed in the table below.
    \begin{table}[htbp]
      \begin{threeparttable}
        \bgroup
          \def\arraystretch{1.2}
          \setlength{\tabcolsep}{1.5em}
          \begin{tabular}{lll}
          \toprule
            \textbf{Command} & \textbf{Definition} & \textbf{Inline Example} \\
            \midrule\midrule
            \grayrow \verb|\argmin| & \verb|\DeclareMathOperator*{\argmin}{\arg\min}| & $\argmin_{x}(x-2)^2+1$ \\
            \verb|\argmax| & \verb|\DeclareMathOperator*{\argmax}{\arg\max}| & $\argmax_{\mathbf{x}} f(\mathbf{x})$ \\
          \bottomrule
          \end{tabular}%
          \begin{tablenotes}\footnotesize
            \item Operators defined with the \texttt{*} after \verb|\DeclareMathOperator| have their subscript under the operator in the \texttt{equation} mode, which can be suppressed by adding \verb|\nolimits| before the \verb|_|.
          \end{tablenotes}
        \egroup
      \end{threeparttable}
    \end{table}

    Here is an example:
    \begin{lstlisting}[language=tex,numbers=none,morekeywords={begin}]
\begin{equation}
  \argmin_{x}(x-2)^2+1,\quad \argmax_{\mathbf{x}} f(\mathbf{x}),\quad \argmin\nolimits_{\alpha}g(\alpha)
\end{equation}
    \end{lstlisting}
    \begin{equation}
      \argmin_{x}(x-2)^2+1,\quad \argmax_{\mathbf{x}} f(\mathbf{x}),\quad \argmin\nolimits_{\alpha}g(\alpha)
    \end{equation}

    \subproblem{Shortcuts} Some shortcuts commands have been defined in this class.

      \subsubproblem{Hint}\label{subsubsec:hint}
      You can easily use command \verb|\hint{}| to show a hint to a problem.
      This is especially useful in the \texttt{problem} mode.
      \hint{You can use \texttt{\string\renewcommand\{\string\hintstyle\}\{<Your Style>\}} to change the default one.}

    \subproblem{Code Block} You can use code blocks in this class which is implemented by the \texttt{lstlisting} environment.
    Their default styles have been set and you can make changes by passing optional arguments when using the environment.
    For more information, please refer to \url{https://ctan.org/pkg/listings}.

    \subproblem{Fancy Box} A fancy box has been defined.
      \begin{fancybox}{This is a Fancy Box}
        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin viverra massa rutrum felis vulputate, ac faucibus velit accumsan. Vivamus aliquet felis nec interdum sollicitudin. Nullam ornare eu velit id cursus. Maecenas a sodales velit, vel cursus magna. Cras lobortis venenatis.
      \end{fancybox}

    You can use the following code to generate it.
    \begin{lstlisting}[language=tex,numbers=none,morekeywords={begin}]
\begin{fancybox}{This is a Fancy Box}
  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin viverra massa rutrum felis vulputate, ac faucibus velit accumsan. Vivamus aliquet felis nec interdum sollicitudin. Nullam ornare eu velit id cursus. Maecenas a sodales velit, vel cursus magna. Cras lobortis venenatis.
\end{fancybox}
    \end{lstlisting}

    There is also a \texttt{notice} box:
    \begin{notice}{This is a Notice Box}
      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin viverra massa rutrum felis vulputate, ac faucibus velit accumsan. Vivamus aliquet felis nec interdum sollicitudin. Nullam ornare eu velit id cursus. Maecenas a sodales velit, vel cursus magna. Cras lobortis venenatis.
    \end{notice}

    You can use the following code to generate it.
    \begin{lstlisting}[language=tex,numbers=none,morekeywords={begin}]
\begin{notice}{This is a Notice Box}
  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin viverra massa rutrum felis vulputate, ac faucibus velit accumsan. Vivamus aliquet felis nec interdum sollicitudin. Nullam ornare eu velit id cursus. Maecenas a sodales velit, vel cursus magna. Cras lobortis venenatis.
\end{notice}
    \end{lstlisting}

  \appendix
  \renewcommand{\sectionheadname}{Appendix}

  \problem{Known Issues}\label{sec:known_issues}

    \begin{itemize}
      \item The section title background height may not be accurate;
    \end{itemize}

    If you find more issues, please report them on \url{https://tvj.one/ml-tex/issues}.

  \problem{Change Log}

    \begin{multicols}{2}
      \begin{itemize}
        \item [\textbf{v1.1}] 2022/03/28 -- Bug Fix and Enhancement
          \begin{enumerate}
            \item Add \verb|\mainproblem{}| command;
            \item Add \verb|\subsubproblem{}| command;
            \item Add \verb|\hint{}| shortcut;
            \item Support for \verb|\section*{}|, \verb|\problem*{}|, \verb|\subsection*{}| and \verb|\subproblem*{}|;
            \item Fix ToC/Bookmarks problem;
            \item Set footnote line style;
            \item Add the \texttt{twoside} option.
          \end{enumerate}
        \item [\textbf{v1.0}] 2022/03/19 -- Initial Version
          \begin{enumerate}
            \item Initial \texttt{cls} file in addition to a sample file and documentation;
            \item Publish at GitHub and CTAN.
          \end{enumerate}
      \end{itemize}
    \end{multicols}

  \problem{Source Code}

    The source code of \texttt{seu-ml-assign.cls} is listed below.

    \lstinputlisting[language=tex,linerange={15-1000},firstnumber=15,morekeywords={begin}]{seu-ml-assign.cls}

\end{document}