\documentclass[color,table,cover,twoside,lot,lof]{../../fithesis3}
\usepackage[english]{babel}
\usepackage{hologo}
\usepackage{fancyvrb}
\usepackage{minted}
\usepackage{ltxcmds}
\usepackage[
  backend=biber,
  style=numeric,
  citestyle=numeric-comp,
  sorting=none
]{biblatex}
\addbibresource{guide.bib}
\makeatletter
\thesissetup{
  title=A fithesis3 user guide for the \thesis@english@facultyName,
  TeXtitle=A \textit{fithesis3} user guide\medskip\\\Large for the
    \thesis@english@facultyName,
  type=bc,
  department=Department of Computer Graphics and Design,
  programme=Applied Informatics,
  field=Typesetting,
  titleEn=\thesis@title,
  departmentEn=\thesis@department,
  programmeEn=\thesis@programme,
  fieldEn=\thesis@field,
  author=Vít Novotný,
  advisor={Doc.\ RNDr.\ Petr Sojka, Ph.D.},
  assignment={},
  TeXkeywords={thesis, typesetting, \LaTeX{}},
  keywords={thesis, typesetting, LaTeX},
  abstract=This user guide describes the installation process of
    the \textsf{fithesis3} document class and documents selected
    parts of the public API of the \textsf{fithesis3} document
    class that bear relevance to the style of the
    \thesis@english@facultyName.,
  keywordsEn=\thesis@keywords,
  abstractEn=\thesis@abstract,
  faculty=?,
  basePath=../..,
  autoLayout=false}
\makeatother
\begin{document}
  \makeatletter\thesis@preamble\makeatother
  \chapter{Introduction} \textsf{Fithesis3} is a \LaTeX{} document
  class, which aims to streamline the typesetting of mandatory
  parts of theses and dissertations, so that the author can focus
  at content alone. Unlike its predecessors, \textsf{fithesis3} can
  be used to write theses across the faculties of the
  \makeatletter\thesis@english@universityName\makeatother. To this
  end, the class comprises:
  \begin{itemize}
    \item\emph{Style files}, which are unique for each faculty and
      which encapsulate the look and the arrangement of the final
      documents
    \item\emph{Locale files}, which define the strings for the
      given locale
    \item\emph{The base class}, which serves as a glue between
      style files, locale files and the input document
  \end{itemize}
  The overarching desing and the interactions between the style
  files, locale files and the base class are described in the
  technical documentation of the class \cite{novotny15} distributed
  along with the class. This guide, on the other hand, only aims to
  document the selected parts of the public API of the
  \textsf{fithesis3} class that bear relevance to the style file of
  the \makeatletter\thesis@english@facultyName\makeatother. Note
  that this guide is typeset using the said style file.

  \section{Required packages and fonts}\label{sec:req-packages}
  In order to be able to use the \textsf{fithesis3} class, your
  \TeX{} installation needs to include the \textsf{rapport3}
  class\footnote{See
  \url{http://www.ctan.org/pkg/ntgclass}} and the following
  packages:\begin{itemize}
    \item\textsf{keyval}, \textsf{etoolbox}, \textsf{ifxetex},
      \textsf{ifluatex}
    \item\textsf{inputenc} -- only when typesetting with \TeX{} or
      \hologo{pdfTeX}
  \end{itemize} In order to be able to use the \textsf{fithesis3}
  class with the style files of the
  \makeatletter\thesis@english@facultyName\makeatother, your
  \TeX{} installation needs to also include the following
  packages:\begin{itemize}
    \item\textsf{xcolor}, \textsf{graphix}, \textsf{pdfpages},
      \textsf{hyperref}, \textsf{keyval}%
      {\makeatletter % The following macro typesets loaded packages
      \def\thguide@prnpkg#1{\ltx@ifpackageloaded%
        {#1}{, \textsf{#1}}{}}%
      \thguide@prnpkg{tikz}%
      \thguide@prnpkg{changepage}%
      \thguide@prnpkg{setspace}%
      \thguide@prnpkg{geometry}}
    \item\textsf{fontspec}, \textsf{unicode-math} -- only when
      typesetting with \Hologo{XeTeX} or \Hologo{LuaTeX}
    \item\textsf{mathpazo}, \textsf{tgpagella}, \textsf{lmodern},
       \textsf{cmap}, \textsf{fontenc} -- only when typesetting
       with \TeX{} or \hologo{pdfTeX}
    \item\textsf{tabularx}, \textsf{booktabs} -- only when the
      \texttt{table} option is specified (see Section
      \ref{sec:options})
  \end{itemize}
  The \TeX{} Gyre Pagella\footnote{See
  \url{http://www.ctan.org/pkg/tex-gyre-pagella}} and
  \TeX{} Gyre Pagella Math\footnote{See
  \url{http://www.ctan.org/pkg/tex-gyre-math-pagella}} OpenType
  fonts are also required, when typesetting with \Hologo{XeTeX} or
  \Hologo{LuaTeX}. All these are likely to be a part of any
  reasonably modern \TeX{} distribution.

  \section{Installation}
  This section covers the installation of the \textsf{fithesis3}
  class. Please note that the installation of the class is fully
  optional. You can typeset your thesis by either directly editing
  either the \path{pdflatex.tex}, \path{xelatex.tex} or
  \path{lualatex.tex} example files distributed along with
  the class or by pointing your source document to the class as
  follows:
  \begin{minted}{latex}
    \documentclass{path/fithesis3}
    \thesissetup{basepath=path}
    % The rest of the document
  \end{minted}
  where \texttt{path} corresponds to the path of the directory
  containing the \path{fithesis3.cls} file.

  When installing, first make sure that the \textsf{fithesis3} class
  is not a part of
  your \TeX{} distribution already. This can be easily verified by
  creating the minimal document described in the next section and
  typesetting it using either the \Hologo{XeTeX}, \Hologo{LuaTeX} or
  the \hologo{pdfTeX} engine, respectively. In case
  \textsf{fithesis3} is not a part of your \TeX{}
  distribution, the typesetting will prematurely terminate with the
  following error: \begin{Verbatim}[frame=single]
! LaTeX Error: File `fithesis3/fithesis3.cls' not found.
  \end{Verbatim}
  If the \textsf{fithesis3} class is not a part of
  your distribution, you can proceed to the installation.
  This can be achieved by extracting the \path{fithesis3.tds.zip}
  archive distributed along with the class into into one of
  the \TeX{} directory structure trees within your \TeX{}
  distribution. If you are using \TeX{}Live\footnote{See
  \url{http://www.tug.org/texlive/doc.html}, Chapter 2.3},
  this can be achieved by creating a \texttt{texmf/}
  directory within your user home directory and by extracting the
  \path{fithesis3.tds.zip} archive into it. For \Hologo{MiKTeX},
  see the online documentation\footnote{See
  \url{http://docs.miktex.org/manual/localadditions.html}}.

  \section{A minimal document}
  Before using the \textsf{fithesis3} class, you should be familiar
  with the \LaTeX{} typesetting system. A good way to get started
  is to read one of the introductory texts in English
  \cite{veryshortlatex,shortlatex,longlatex,latex} or in Czech
  \cite{rybicka03,satrapa11}.
  We will start by creating a plain text document named
  \path{helloworld.tex} in the UTF-8 encoding with the following
  content:
  \begin{minted}{latex}
    \documentclass{fithesis3}
    \thesissetup{faculty=?}
    \begin{document}
      Hello world
    \end{document}
  \end{minted}
  Now, typeset the document using either the \Hologo{XeTeX},
  \Hologo{LuaTeX} or the \Hologo{XeTeX} engine with the \LaTeX{}
  format. If everything is set up correctly, you should end up with
  a document containing all the mandatory parts of a thesis and one
  page of the main matter containing a \texttt{Hello world}
  paragraph.  You should notice that the document is implicitly
  typeset in English and that it contains lots of placeholder
  strings for missing metadata (see Figure \ref{fig:example01}). In
  the next chapter, we are going to address that.
  \begin{figure}[!bt]
    \centering\makeatletter
    \fbox{\includegraphics[clip,trim=0cm 14.8cm 0cm 4.2cm,%
      width=0.975\textwidth]{examples/\thesis@faculty-01.pdf}}
    \makeatother
    \caption{The placeholder strings in the minimal document}
    \label{fig:example01}
  \end{figure}

  \chapter{Configuring the class}
  In this chapter, we will configure the class to use the correct
  locale, to insert the correct metadata into the output document
  and to be laid out in a meaningful way.

  \section{Setting the locale}
  First, we are going to set the locale of the document class. This
  affects the locale of the mandatory parts of thesis. To see what
  locales are available, list the contents of the
  \path{fithesis3/locale/} directory. It should contain several
  \texttt{\textit{locale}.dtx} files. Each of these
  \textit{locale}s can be leaded by inserting the \texttt{\string%
  \thesis\-setup\{locale=\textit{locale}\}} command into the
  preamble of the document.

  If you use the \textsf{babel} or the \textsf{polyglossia} package
  to load the hyphenation patterns for your locale, you don't need
  to set the locale at all, \textsf{fithesis3} will use the main
  language of \textsf{babel} or \textsf{polyglossia}.
  \begin{minted}{latex}
    \documentclass{fithesis3}
    \thesissetup{faculty=?}
    % Using the babel package:
    \usepackage[czech]{babel}
    \begin{document}
      The mandatory parts of the thesis
      are going to be typeset in Czech.
    \end{document}

    \documentclass{fithesis3}
    \thesissetup{faculty=?}
    % Using the polyglossia package:
    \usepackage{polyglossia}
    \setmainlanguage{czech}
    \begin{document}
      The mandatory parts of the thesis
      are going to be typeset in Czech.
    \end{document}
  \end{minted}
  At the time of writing this text, \textsf{polyglossia} can only
  be used with \Hologo{XeTeX}, whereas \textsf{babel} can be used
  with \hologo{pdfTeX}, \Hologo{XeTeX} and \Hologo{LuaTeX}. On the
  other hand, the \textsf{babel} package can only be used with
  Latin scripts, while the \textsf{polyglossia} package supports
  non-Latin scripts as well. You are advised to use one of them,
  depending on your choice of \TeX{} engine and requirements.

  \section{Inserting metadata}
  Next, we are going to insert some metadata into the document
  using the \texttt{\string\thesis\-setup} command. This command
  accepts a comma-delimited \textit{key}\texttt{=}\textit{value}
  list.  The placeholder strings in our minimal document map
  directly into the
  \textit{key}s, so to change the \emph{<<author>>} placeholder
  into \emph{Jane Doe}, simply insert the
  \texttt{\string\thesis\-setup\{author=Jane Doe\}} command into the
  preamble of your document.

  Note, however, that some keys can not be deduced directly from
  the output document. The \texttt{thanks} key, for example, is
  invisible by default, since the acknowledgement is not a
  mandatory part of the thesis and it only gets inserted into the
  document, when the \texttt{thanks} key is defined. Some other
  \textit{key}s, like the \texttt{abstract} key, can also span
  multiple paragraphs, in which case they need to be set using the
  \texttt{\string\thesis\-long\{\textit{key}\}\-\{\textit{value}%
  \}} command as follows:
  \begin{minted}{latex}
    \documentclass{fithesis3}
    \thesissetup{
      faculty=?,
      author=Jane Doe}
    \thesislong{abstract}{
      In this document, I am going to
      explore the craft of creating
      abstracts \ldots
        
      \ldots that span multiple
      paragraphs.}
    \begin{document}
      Hello world!
    \end{document}
  \end{minted}
  If the \textit{value} of a \textit{key} contains a comma, the
  \texttt{\string\thesis\-setup\{\textit{key}=\textit{value}\}}
  command would erroneously interpret it as a delimiter. To prevent
  this behaviour, enclose the \textit{value} in curly braces as
  follows:
  \begin{minted}{latex}
    \documentclass{fithesis3}
    \thesissetup{
      faculty=?,
      author=Jane Doe,
      advisor={RNDr.\ John Doe, Ph.D.},
      keywords={keyword1, keyword2}}
    \begin{document}
      Hello world!
    \end{document}
  \end{minted}
  The complete list of \textit{key}s and their effects can
  be found in the technical documentation of the
  class \cite[chapter \emph{Public API}]{novotny15} distributed
  along with the class.

  \section{Style options}\label{sec:options}
  The look of the resulting document can be affected by
  \textit{options} passed to the style file using the
  \texttt{\string\documentclass[\textit{options}]\{fithesis3\}}
  syntax. The complete list of options for the style files
  of the \makeatletter\thesis@english@universityName\makeatother\
  can be found in the technical documentation of the class
  \cite[chapter \emph{Style files}]{novotny15} distributed along
  with the package. Some of the more important options are listed
  in Table \ref{tab:options} for your convenience.
  
  \begin{table}[bt]
    \begin{tabularx}{\textwidth}{lX}
      \toprule
        \emph{Name} & \emph{Description} \\
      \midrule
        \texttt{oneside} & Enables one-sided typesetting. This
        is generally discouraged. Use only if you don't
        have access to a double-sided printer, or if one-sided
        typesetting is a formal requirement. \\
        \texttt{twoside} & Enables double-sided typesetting.
        Double-sided typesetting consumes less paper, is generally
        regarded as more visually pleasing and is enabled by default.
        Use at least 120 grams per square meter paper to prevent
        show-through. \\
        \texttt{color} & Enables colors. A colorful version of the
        document is more visually pleasing, but shouldn't be used
        in a printed version, if you don't have access to a color
        printer. Unless you have a compelling reason not to, always use
        this option in the e-version. \\
        \texttt{monochrome} & Disables colors. Disabling colors is
        generally discouraged, unless you don't have access to a
        color printer. \\
        \texttt{cover} & Typesets the cover of the thesis. Should
        be generally used in the e-version. \\
        \texttt{nocover} & Forbids the typesetting of the thesis
        cover. Use, if you're typesetting the printed version and
        have no desire to have a cover made for your thesis. This
        option is the default. \\
        \texttt{table} & Redefines the \texttt{tabular} and
        \texttt{tabularx} environments to use alternating colors
        for odd and even rows like this table does. \\
        \texttt{oldtable} & Instructs the style not to redefine the
        \texttt{tabular} and \texttt{tabularx} environments. This
        option is the default. \\
      \bottomrule
    \end{tabularx}
    \caption{A non-exhaustive list of basic options accepted by the
      styles of the Masaryk University}
    \label{tab:options}
  \end{table}

  \chapter{Advanced usage}
  This chapter is dedicated to those users, who wish to customize
  the class to better suit their needs.

  \section{Throubleshooting option clashes}
  When a package is required twice, each time with different
  options, an option clash error occurs: \begin{Verbatim}%
  [frame=single]
! LaTeX Error: Option clash for package hyperref
  \end{Verbatim}
  If you need to load a \textit{package} with a specific set of
  \textit{options} and the \textit{package} happens to be
  required by the \textsf{fithesis3} class, as specified in
  Section \ref{sec:req-packages}, prepend the
  \texttt{\string\Pass\-Options\-To\-Package\discretionary{}{}{}%
  \{\textit{options}\}\discretionary{}{}{}\{\textit{package}\}}
  command before the \texttt{\string\documentclass\{\ldots\}}
  statement. If you need to configure the \textit{package}, you can
  do that anywhere within the document preamble.

  If you need to load a \textit{package} with a specific set of
  \textit{options} and the \textit{package} happens to be
  required by the style files of the \makeatletter%
  \thesis@english@universityName\makeatother, as specified in
  Section \ref{sec:req-packages}, insert the
  \texttt{\string\Pass\-Options\-To\-Package\discretionary{}{}{}%
  \{}\textit{options}\texttt{\}\discretionary{}{}{}%
  \{}\textit{package}\texttt{\}} command anywhere within the
  document preamble. If you need to configure the \textit{package},
  you can do that anywhere after the document preamble. If you need
  to configure the \textit{package} within the preamble, you can
  load the style files prematurely using the
  \texttt{\string\thesis@load} command as follows:
  \begin{minted}{latex}
    \documentclass{fithesis3}
    % Preamble
    \makeatletter\thesis@load\makeatother
    % The package configuration goes here
    \begin{document}
    \end{document}
  \end{minted}
  Note that only a small portion of the packages required by the
  style files needs to be loaded with a specific set of options,
  so clashes should be relatively rare.
  
  \section{Changing the layout}
  If you are unsatisfied with the automatic arrangement of the
  mandatory parts of the thesis, you can disable it using the
  \texttt{autoLayout} metadata key:
  \begin{minted}{latex}
    \documentclass{fithesis3}
    \thesissetup{faculty=?,autoLayout=false}
    \begin{document}
      A document which, except for this line,
      is completely empty.
    \end{document}
  \end{minted}
  This results in a document, which only consists of the main
  matter of the thesis (see Figure \ref{fig:example02}).  You can
  now manually insert the preamble and the postamble of the
  document as follows:
  \begin{minted}{latex}
    \documentclass{fithesis3}
    \thesissetup{
      faculty=?,
      autoLayout=false}
    \begin{document}
      \makeatletter\thesis@preamble\makeatother
      A document which once again contains all
      the mandatory parts of a thesis.
      \makeatletter\thesis@postamble\makeatother
    \end{document}
  \end{minted}
  \begin{figure}[!bt]
    \centering\makeatletter
    \fbox{\includegraphics[clip,trim=2cm 24.5cm 2cm 4.5cm,%
      width=0.975\textwidth]{examples/02.pdf}}
    \makeatother
    \caption{A document with disabled \texttt{autoLayout}}
    \label{fig:example02}
  \end{figure}
  This alone would be a useless excercise, as we're now back to the
  original document. However, instead of inserting the
  \texttt{\string\thesis\-@preamble} and 
  \texttt{\string\thesis\-@postamble} commands into the document,
  we can insert only certain sections of the document preamble and
  postamble to which these commands expand.
  \texttt{\string\thesis\-@preamble} expands to the following
  commands:
  {% The following macro typesets the meaning of another macro
  \makeatletter
  \def\thguide@macromeaning#1{%
      \let\ea\expandafter%
      \ea\let\ea\thguide@macro\csname#1\endcsname%
      \ea\def\ea\thguide@meaning\ea{\meaning\thguide@macro}%
      \def\thguide@parse##1 ##2{%
        ##1\ifx##2\relax\ea\@gobbletwo\else\\\fi\thguide@parse##2}%
      \begin{verse}%
        \ea\ifx\@empty\thguide@macro\@empty%
          $\langle$\emph{empty}$\rangle$
        \else%
          \tt\ea\ea\ea\ea\ea\ea\ea\ea\ea\ea\ea\ea\ea\ea\ea\ea\ea\ea%
          \ea\ea\ea\ea\ea\ea\ea\ea\ea\ea\ea\ea\ea\thguide@parse\ea%
          \ea\ea\ea\ea\ea\ea\ea\ea\ea\ea\ea\ea\ea\ea\@gobbletwo\ea%
          \ea\ea\ea\ea\ea\ea\@gobbletwo\ea\ea\ea\@gobbletwo\ea%
          \@gobbletwo\thguide@meaning \relax%
        \fi%
      \end{verse}}
  \thguide@macromeaning{thesis@preamble} and
  \texttt{\string\thesis\-@postamble} 
  expands to the following commands:
  \thguide@macromeaning{thesis@postamble}
  \makeatother}
  To create a document, which only contains the thesis cover prior
  to the text, we would use the following:
  \begin{minted}{latex}
    \documentclass{fithesis3}
    \thesissetup{
      faculty=?,
      autoLayout=false}
    \begin{document}
      \makeatletter
        \thesis@blocks@cover
        \thesis@blocks@mainMatter
      \makeatother
      A document which contains only the cover
      of the thesis and the main matter.
    \end{document}
  \end{minted}
  The available blocks are documented in the technical
  documentation of the class \cite[chapter
  \emph{Style files}]{novotny15} distributed along with the
  package.

  \makeatletter\thesis@postamble\makeatother
  \tolerance=300\emergencystretch=1em
  \printbibliography[heading=bibintoc]
\end{document}
