dsekdocs.tex

\documentclass[a4paper, oneside]{ltxdoc}
\usepackage[
  colorlinks=true,
  bookmarks=true,
  bookmarksnumbered=true,
  bookmarksopen=true,
  bookmarksopenlevel=3,
  pdfauthor={D-sektionen},
  pdftitle={dsekdocs manual},
  pdfsubject={Manual for the dsekdocs LaTeX package},
]{hyperref}
\usepackage[color]{dsek}
\usepackage{array}
\setlength{\parindent}{0mm}
\setlength{\parskip}{3mm}

\author{D-sektionen}
\title{The \textsf{dsekdocs} manual}

\begin{document}
\maketitle

\tableofcontents

\section{Overview}
This is the manual for version 0.1.1 of the \textsf{dsekdocs} packages for the
typesetting of documents for the D-guild within Teknologkåren at the Faculty of
Engineering LTH, Lund University.

\textsf{dsekdocs} consists of one package and 13 document classes.  All 13
document classes depend on the package, \textsf{dsek}.  The document classes are
based on each other like this:

\begin{itemize}
\item \textsf{dsekdoc}
  \begin{itemize}
  \item \textsf{dsekmotion}
  \item \textsf{dseknotice}
  \item \textsf{dsekdocket}
  \item \textsf{dsekelectionproposal}
  \item \textsf{dsekrequirementprofile}
  \item \textsf{dsekparagraphed}
    \begin{itemize}
    \item \textsf{dsekminutes}
    \item \textsf{dsekregdoc}
      \begin{itemize}
      \item \textsf{dsekstatutes}
      \item \textsf{dsekregulations}
      \item \textsf{dsekpolicy}
      \item \textsf{dsekguideline}
      \end{itemize}
    \end{itemize}
  \end{itemize}
\end{itemize}

\textsf{dsekdoc}, \textsf{dsekparagraphed} and \textsf{dsekregdoc} are the most
important classes with the others mostly acting as thin wrappers around these
three.

\section{The \textsf{dsek} package}
This package contains macros for the inclusion of D-guild related stuff in any
document.  To use it, write \cs{usepackage\{dsek\}}.

\subsection{Commands}

\subsubsection{Text snippets}

These are commands that insert a snippet of text when used.  They exist to
prevent misspellings when writing hard to spell phrases.

\begin{center}
  \begin{tabular}{r | l}
    \cs{Dseklongname}  & \Dseklongname  \\
    \cs{idet}          & \idet          \\
    \cs{medaljk}       & \medaljk       \\
    \cs{overphos}      & \overphos      \\
    \cs{overpeppare}   & \overpeppare   \\
    \cs{medaljkmedlem} & \medaljkmedlem \\
  \end{tabular}
\end{center}

\subsubsection{Graphics}

These are commands that insert some kind of graphic when used.  All graphics
accept these options as the optional arguments (comma separated if multiple):

\begin{description}
  \item[\texttt{bw}] Forces the usage of the black and white version of the
        graphic.
  \item[\texttt{color}] Forces the usage of the colored version of the graphic
        (if it exists).
  \item[\texttt{height=}\textit{dim}] Sets the height of the graphic.
\end{description}

\begin{center}
  \begin{tabular}{r | c c}
    Command         & Colored                         & Black and white           \\ \hline
    \cs{Dsymbol}    & N/A                             & \Dsymbol[bw, height=10mm] \\
    \cs{Dseksigil}  & \Dseksigil[color, height=20mm]  & \Dseksigil[bw,
    height=20mm]                                                                  \\
    \cs{Cprogsigil} & \Cprogsigil[color, height=20mm] & \Cprogsigil[bw,
    height=20mm]                                                                  \\
    \cs{Dprogsigil} & \Dprogsigil[color, height=20mm] & \Dprogsigil[bw,
    height=20mm]                                                                  \\
  \end{tabular}
\end{center}

\subsubsection{Adding and striking}
When proposing changes to documents we want to be able to highlight these
changes.  For this purpose, the \textsf{dsek} package provides the \cs{add} and
\cs{strike} commands.  They work as follows:

\begin{center}
  \begin{tabular}{l | l}
    \begin{minipage}{0.5\linewidth}
      \texttt{Sektionens färg är}
      \cs{strike}\texttt{\{Rosa\}}\cs{add}\texttt{\{Råsa\}.} \\
    \end{minipage}
     &
    \begin{minipage}{0.5\linewidth}
      Sektionens färg är \strike{Rosa}\add{Råsa}.
    \end{minipage}
  \end{tabular}
\end{center}

The commands \cs{stryk} and \cs{läggtill} alias to \cs{strike} and \cs{add},
respectively.

\subsubsection{Lists}
As it is often desirable to create so called ``att-listor'' to reflect decisions
taken or the proposed actions in motions, facilities to create them are
provided:

\begin{center}
  \begin{tabular}{l}
    \cs{begin\{attlist\}}\oarg{options} \\
    \ldots                              \\
    \cs{end\{attlist\}}
  \end{tabular}
\end{center}

For example:

\begin{center}
  \begin{tabular}{l | l}
    \begin{minipage}{0.5\linewidth}
      \texttt{Mötet beslutade}                \\
      \cs{begin\{attlist\}}                   \\
      \cs{item} \texttt{steka pannkakor,}     \\
      \cs{item} \texttt{D-sektionen är bäst!} \\
      \cs{end\{attlist\}}
    \end{minipage}
     &
    \begin{minipage}{0.5\linewidth}
      Mötet beslutade
      \begin{attlist}
        \item steka pannkakor,
        \item D-sektionen är bäst!
      \end{attlist}
    \end{minipage}
  \end{tabular}
\end{center}

If the number of items in the list exceeds three, they are automatically
enumerated:

\begin{center}
  \begin{tabular}{l | l}
    \begin{minipage}{0.5\linewidth}
      \texttt{Mötet beslutade}                       \\
      \cs{begin\{attlist\}}                          \\
      \cs{item} \texttt{alla bananer ska vara raka,} \\
      \cs{item} \texttt{öka kaffebudgeten,}          \\
      \cs{item} \texttt{vara, eller}                 \\
      \cs{item} \texttt{inte vara.}                  \\
      \cs{end\{attlist\}}
    \end{minipage}
     &
    \begin{minipage}{0.5\linewidth}
      Mötet beslutade
      \begin{attlist}
      \item alla bananer ska vara raka,
      \item öka kaffebudgeten,
      \item vara, eller
      \item inte vara.
      \end{attlist}
    \end{minipage}
  \end{tabular}
\end{center}

The \texttt{attlist} environement also accepts optional arguments:

\begin{description}
  \item[\texttt{num}] Forces the list to be enumerated.
  \item[\texttt{nonum}] Forces the list to \emph{not} be enumerated.
\end{description}

For the users convenience, provided are also a couple of commands for
items. \cs{att} is a shorthand for \cs{item}, and \cs{attdesc} includes a
description of the item. The commands can be used like this:

\begin{center}
  \begin{tabular}{l | l}
    \begin{minipage}{0.5\linewidth}
      \cs{begin\{attlist\}}                                   \\
      \cs{att} \texttt{sänka ribban,}                         \\
      \cs{attdesc}\texttt{\{höja ribban vid nästa fullmåne.\} \\
        \{Nästa fullmåne är 24 februari.\}}                   \\
      \cs{end\{attlist\}}
      \end{minipage}
     &
    \begin{minipage}{0.5\linewidth}
      Mötet beslutade
      \begin{attlist}
        \att sänka ribban,
        \attdesc{höja ribban vid nästa fullmåne.}{Nästa fullmåne är 24 februari.}
      \end{attlist}
    \end{minipage}
  \end{tabular}
\end{center}

If you would like to create a list in the same style as the att-lists but with
another word in place of \textit{att}, use the \texttt{boldlist} environment:

\begin{center}
  \begin{tabular}{l}
    \cs{begin\{boldlist\}}\marg{bullet word} \\
    \ldots                                   \\
    \cs{end\{boldlist\}}
  \end{tabular}
\end{center}

\subsubsection{Signatures}
Finally, the \textsf{dsek} package also includes facilities for adding
signatures.

\begin{center}
  \cs{signature}\oarg{options}\marg{date and location}\marg{name}\marg{title}
\end{center}

For instance, a signature declaration that looks like this:

\begin{center}
  \cs{signature}\texttt{\{Lund, dag som ovan\}\{Trula Trulsson\}\{Ordförande\}}
\end{center}

results in

\begin{center}
  \signature{Lund, dag som ovan}{Trula Trulsson}{Ordförande}
\end{center}

The signature command accepts the following options:
\begin{description}
  \item[\texttt{width=}\textlangle\textit{dim}\textrangle] Sets the width of the
    signature.  By default, it is set to the maximum of the widths of the
    entered texts.
  \item[\texttt{hspace=}\textlangle\textit{dim}\textrangle] Sets the height of
    the signature space.  By default it is set to 15mm.
  \item[\texttt{signfile=}\textlangle\textit{file}\textrangle] Sets the file
    from which an image of a signature is loaded. By default it is unset.  Be
    aware that some file formats (like SVG) might not work.
\end{description}

Additionally, the default signature height space for all signatures can be set
through this command:
\begin{center}
  \cs{setsignspaceheight}\marg{dim}
\end{center}

\subsection{Package options}
The \textsf{dsek} package accepts the following options, (comma separated if
multiple):

\begin{description}
  \item[\texttt{bw}] Makes graphics render in black and white by default.
  \item[\texttt{color}] Makes graphics render in color by default.
\end{description}

\section{The \textsf{dsekdoc} document class}
The \textsf{dsekdoc} document class is meant as a base to create more specific
document classes upon, but can also be used for any guild related documents for
which there doesn't exist a specific document class.  It is based of the
\textsf{article} document class, but changes fonts, paragraph styles, headers
and footers amongst a few other things.

\subsection{Fonts}
The \textsf{dsekdoc} document class uses the free Domitian and \TeX Gyre Heros
as stand ins for non-free Palatino and Helvetica fonts.

It is worth noting that it by default uses old style figures, i.e. ``lower case
numbers'', by default.  If you want to turn that off somewhere, like maybe in a
table, use

\cs{addfontfeatures\{Numbers=\{Monospaced,Lining\}\}}

This makes the numbers full height and monospaced to increase readability.

\subsection{Options}
The \textsf{dsekdoc} document class takes two special options:
\begin{description}
  \item[\texttt{titlecoverpage}] makes \textsf{dsekdoc} redefine the
        \cs{maketitle} command to insert the cover page (like \cs{coverpage}
        always does).
  \item[\texttt{english}] tells the language package \textsf{polyglossia} that
        the main language for the document is English instead of Swedish.
\end{description}
All other arguments are passed through to the \textsf{article} document class.

\subsection{Commands}
\subsubsection{Document properties}
\label{props}
Because of how the \cs{title}, \cs{author} and \cs{date} commands work, we can't
easily use what is given to them for our own purposes, so as a replacement we
have
\begin{center}
  \cs{settitle}\marg{title}, \cs{setauthor}\marg{author} and
  \cs{setdate}\marg{date}
\end{center}
These commands wrap around the usual \cs{title} commands etc., so there's no
need to use both.

In addition to the default properties, you can also set the \emph{short title}
and the \emph{meeting}.  These are displayed in the page headers of the
document.  These can be set with

\begin{center}
  \cs{setshorttitle}\marg{short title} and \cs{setmeeting}\marg{meeting}
\end{center}

\subsubsection{Cover page}
\label{cover_page}
For longer, more important documents it is nice for them to have a cover page.
By default, the cover page is inserted with

\begin{center}
  \cs{coverpage}
\end{center}

By giving the \texttt{titlecoverpage} to the document class, it can also be
inserted with \cs{maketitle}.

In addition to the guild's name, the guild's sigil and the title of the
document, the cover page also features a small text that might be used as a
subtitle.  It can be set with

\begin{center}
  \cs{setcovptext}\marg{text}
\end{center}

\subsubsection{Reusing}
To use any of the properties we have described in this section so far, change
the ``set'' in the command to ``use''.  So, to use the title you set with the
\cs{settitle} command in another part of your document, you write \cs{usetitle}
and it will be inserted.

\subsection{The agenda environment}
The \textsf{dseknotice} document class provides a document environment for
typesetting meeting agendas and to populate them with issues.  The agenda is
essentially a list of issues in a table format, containing four columns, where
the first one is used for enumerating. The \cs{issue} requires a title of the
issue as the first argument, and provides two optional arguments for the type of
action for the issue and attachments. The argument included for attachments
could be a link to the attachments.

\begin{center}
  \begin{tabular}{l}
    \cs{begin\{agenda\}}                                  \\
    \cs{issue}\marg{title}                                \\
    \cs{issue}\marg{title}\oarg{action}                   \\
    \cs{issue}\marg{title}\oarg{action}\oarg{attachments} \\
    \cs{end\{agenda\}}
  \end{tabular}
\end{center}

The default headers for the agenda table are ``Ärende'', ``Åtgärd'' and
``Bilaga''. If users want to customize this, the \texttt{agenda} environment
takes three optional arguments for the table headers and can be used like this:

\begin{center}
  \begin{tabular}{l}
    \cs{begin\{agenda\}}\oarg{header 1}\oarg{header 2}\oarg{header 3} \\
    \ldots                                                            \\
    \cs{end\{agenda\}}
  \end{tabular}
\end{center}

The \texttt{dagordning} environment is an alias to the \texttt{agenda} one, so
they are equivalent.  Likewise, the \cs{punkt} command is an alias to
\cs{issue}.

\subsection{Attachments}

One thing that often goes hand in hand with agendas are attachments
(sv. bilagor) to them.  As they can be tedious to manage manually, the
\texttt{dsekdoc} class provides a command:

\begin{center}
  \cs{attachment}\oarg{alternative name}\marg{URL}
\end{center}

Attachments usually render just as a number and are automatically counted for
you.  Should you want an attachment with another name, you can pass it as an
optional argument.  This excludes it from the automatic numbering.

The \cs{bilaga} command is an alias for the \cs{attachment} command.

\subsection{Symbols}

\section{The \textsf{dsekmotion} document class}
The \textsf{dsekmotion} document class is meant to be used for typesetting
motions and propositions.

\subsection{Options}
Since motions and propositions are very similar, the \textsf{dsekmotion}
document class has options to switch between them:
\begin{description}
  \item[\texttt{motion}] makes the document a motion. This is the default and
    can be omitted.
  \item[\texttt{proposition}] makes the document a proposition.
\end{description}

\section{The \textsf{dsekelectionproposal} document class}
The \textsf{dsekelectionproposal} document class is meant for the documents in
which nomination commitees announce who they nominate to different positions.
The class provides three environments and one command to make creating such
documents as easy as possible.  The \texttt{vemsection} and \texttt{vemlist}
environments are intended for creating a list of proposed candidates, like this:

\begin{center}
  \begin{minipage}{0.4\linewidth}
    \cs{begin\{vemsection\}}        \\
    \cs{begin\{vemlist\}\{Post 1\}} \\
    \cs{item} \texttt{Donald Knuth} \\
    \cs{item} \texttt{Ada Lovelace} \\
    \cs{end\{vemlist\}}             \\
    \cs{begin\{vemlist\}\{Post 2\}} \\
    \cs{item} \texttt{Alan Turing}  \\
    \cs{end\{vemlist\}}             \\
    \cs{end\{vemsection\}}
  \end{minipage}
\end{center}

Also provided is the \texttt{statistikpage} environment and \cs{statistik}
command for typesetting statistics about the amount of candidates that applied
for the position.  They can be utilized like this:

\begin{center}
  \begin{minipage}{0.4\linewidth}
    \cs{begin\{statistikpage\}}     \\
    \cs{statistik}\texttt{\{Post 1\}\{100-104\}} \\
    \cs{statistik}\texttt{\{Post 2\}\{0-4\}} \\
    \cs{end\{statistikpage\}}
  \end{minipage}
\end{center}

\section{The \textsf{dsekparagraphed} document class}
The \textsf{dsekparagraphed} document class is meant to be used for the creation
of guild documents that use a paragraphed structure, e.g. regulatory documents
and minutes.  Since this class builds upon the \textsf{dsekdoc} class,
everything from the last section applies here as well.

Paragraphs are inserted with the \cs{paragraph} command (it shadows the
\LaTeX-default \cs{paragraph}).  Each paragraph is numbered and labeled
according to what kind of section it is in.  So a paragraph under a \cs{section}
would be labeled §\(X.Y\), where \(X\) is the section number and \(Y\) is the
paragraph number.

\subsection{Cross-referencing}
All paragraphs can be labeled with \cs{label} and linked to using \cs{ref}.  So,
if I were to label a paragraph, like so:

\begin{center}
  \cs{paragraph}\texttt{\{Examples\}} \cs{label}\texttt{\{examples\}}
\end{center}

I could then refer to it in another part of the document and it will be numbered
correctly automatically:

\begin{center}
  \begin{tabular}{l | l}
    \begin{minipage}{0.6\linewidth}
      \texttt{See }\cs{ref}\texttt{\{examples\} for further examples.}
    \end{minipage}
     &
    \begin{minipage}{0.4\linewidth}
      See §1.2 for further examples.
    \end{minipage}
  \end{tabular}
\end{center}

This will also insert a hyperlink to the correct part of the document.

\subsection{Technical notes}
The paragraphed part of the document usually runs until you start a new section,
subsection etc. or until the end of the document.  Should you need to end the
paragraphed section early, you can do so with \cs{endparagraphed}.  This can be
useful if you want the whole page width available for signatures at the end of
some meeting minutes, for example.

\section{The \textsf{dsekdocket} and \textsf{dseknotice}}
The \textsf{dsekdocket} and \textsf{dseknotice} document classes are meant for
typesetting docket (sv. föredragningslista) and notice (sv. kallelse) documents,
respectively.  Both of these classes are simple wrappers around the
\textsf{dsekdoc} class: they just set the appropriate document properties.

\section{The \textsf{dsekregdoc} document class}
The \textsf{dsekregdoc} document class is to be used for the creation of
regulatory documents.  It is based on the \textsf{dsekparagraphed} document
class.  It features two new document properties:

\begin{description}
\item[adoptedon] The meeting during which the document was adopted.  Set with
  \cs{setadoptedon}.
\item[revisedon] The meeting during which the document was last revised.  Set
  with \cs{setrevisedon}.
\end{description}

\section{The \textsf{dsekguideline} and \textsf{dsekpolicy} document classes}
The \textsf{dsekguideline} and \textsf{dsekpolicy} document classes for
typesetting guidelines and policies, respectively.  These classes are very
similar, and are just thin wrappers around the \textsf{dsekregdoc} document
class.  As such, they set the appropriate document properties (as described in
\ref{props}) and just provide one command each:

\begin{center}
  \cs{riktlinjeför}\marg{subject} and \cs{policyför}\marg{subject}
\end{center}

So, if I were writing a policy about voting, I would write:

\begin{center}
  \cs{riktlinjeför}\texttt{\{röstning}\}
\end{center}

Be aware that these are just aliases to the \cs{settitle} command, which these
classes change to ensure that document titles follow the same naming scheme.

\section{The \textsf{dsekstatutes} and \textsf{dsekregulations} document classes}
The \textsf{dsekregulations} and \textsf{dsekstatutes} document classes are
meant for the typesetting of the guild statutes and the guild regulations,
respectively.  They are thin wrappers around the \textsf{dsekregdoc} document
class and set the appropriate document properties.

Special for these are that they both use the cover page as the document title.
See \ref{cover_page} for more info.

\section{Technical notes}

\subsection{Compatibility}

The \textsf{dsekdoc} and \textsf{dsekparagraphed} document classes make use of
the \href{https://ctan.org/pkg/fontspec}{\textsf{fontspec}} and
\href{https://ctan.org/pkg/polyglossia}{\textsf{polyglossia}} packages, both of
which are incompatible with \textsf{pdflatex}.  So, to use them, use
\textsf{xelatex} or \textsf{lualatex} insitead.

\end{document}