% \iffalse meta-comment
%
% File: rub-kunstgeschichte.dtx
% Copyright (C) 2024 by Joran Schneyer <joran.schneyer@ruhr-uni-bochum.de>
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
% of this license or (at your option) any later version.
% The latest version of this license is in
%   https://www.latex-project.org/lppl.txt
% and version 1.3c or later is part of all distributions of LaTeX
% version 2008 or later.
%
% This work has the LPPL maintenance status `maintained'.
% 
% The Current Maintainer of this work is Joran Schneyer <joran.schneyer@ruhr-uni-bochum.de>.
%
% This work consists of the files rub-kunstgeschichte.dtx
%                                 rub-kunstgeschichte.ins
%           and the derived files rub-kunstgeschichte.cls
%                                 rub-kunstgeschichte-example.tex
%
% \fi

% \iffalse
%<*driver>
\ProvidesFile{rub-kunstgeschichte.dtx}
%</driver>
%<class>\NeedsTeXFormat{LaTeX2e}[2022-06-01]
%<class>\ProvidesClass{rub-kunstgeschichte}
%<*class>
    [2024-09-06 v0.2.0 RUB Kunstgeschichte class]
%</class>
%<*driver>
\documentclass{ltxdoc}

%^^A Load packages needed for the documentation
\usepackage{dtxdescribe}
\fvset{commandchars={|()}}

\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
    \DocInput{\jobname.dtx}
    \PrintChanges
    \PrintIndex
\end{document}
%</driver>
% \fi
%
%^^A Document general changes here
% \changes{v0.1.0}{2024-05-26}{Initial version}
%
% \GetFileInfo{\jobname.dtx}
%
% \DoNotIndex{\newcommand,\newenvironment}
% \DoNotIndex{\begin,\end}
% \DoNotIndex{\fi}
% \DoNotIndex{\section,\subsection,\subsubsection}
% \DoNotIndex{\title,\author,\tableofcontents}
% \DoNotIndex{\LaTeX,\verb}
%
%^^A define helper commands for consistent typesetting in the documentation
% \DeclareDocumentCommand\email{m}{\href{mailto:#1}{\nolinkurl{#1}}}
%
% \title{The \pkg{\jobname} class^^A
%   \thanks{This document corresponds to \pkg{\jobname}~\fileversion,
%     dated \filedate.}}
% \author{\copyright{} Joran Schneyer^^A
%   \thanks{Released under the LaTeX Project Public License v1.3c or later.^^A
%   \\ See \url{https://www.latex-project.org/lppl.txt}}^^A
%   \\ \email{joran.schneyer@ruhr-uni-bochum.de}}
% \date{\filedate}
%
% \maketitle
% \tableofcontents
%
% \section{Introduction}\label{sec:introduction}
%
% This \LaTeX{} class aims to implement the guidelines on scientific writing of the art history institute (Kunstgeschichtliches Institut - short: KGI) at Ruhr University Bochum.^^A
% \footnote{Guidelines version July 2023 \url{https://kgi.ruhr-uni-bochum.de/wp-content/uploads/2023/04/Anleitung-zum-Erstellen-von-Hausarbeiten-im-Fach-Kunstgeschichte_Fassung-Juli-2023.pdf}}
%
% Note, that at this point this is not an official class made by anyone at the institute but rather a free-time hobby project of me, Joran, who knows \LaTeX{} from studying Electrical Engineering and just wants to help out some friends studying art history.
%
% You can find the latest releases and the development of this project at GitHub: \url{https://github.com/rub-kgi/rub-kunstgeschichte-latex}
%
% \section{Usage}\label{sec:usage}
%
% To use this class, simply specify it as the document class.^^A
% \footnote{You can also find a complete example usage of this class in \autoref{sec:example}.}
% \begin{sourceverb}
% \documentclass{rub-kunstgeschichte}
% \end{sourceverb}
%
% \subsection{Caveats}
% When using this class, some packages are loaded automatically with options (see also \autoref{sec:implementation:package-loading}).
% That means that you can't reload the same package with different options without risking an option clash error.
% The relevant packages offer other ways to change their options in the preamble:
%
% \DescribePackage{biblatex}
% Customize citations and bibliography.
%
% \verb|\ExecuteBibliographyOptions|\oarg{entrytype}\marg{options} can be used to set most options,
% but some can only be set at the time of loading the \pkg{biblatex} package.
% Those can be set in the class options using the \optn{biblatex} key (see also \autoref{sec:usage:class-options}).
%
% \DescribePackage{hyperref}
% Customize behavior of clickable elements and pdf meta-data.
%
% \verb|\hypersetup|\marg{options} should be used for nearly all options.
% The few options that can only be given at load time of the package have to be passed along using the \optn{hyperref} class option (see also \autoref{sec:usage:class-options}).
%
% \DescribePackage{setspace}
% Overwrite the 1.5 line-spacing setting.
%
% Either \verb|\singlespacing|,
% \verb|\doublespacing|
% or for custom spacing factors also
% \verb|\setstretch|\marg{baselinestretch}.
%
% \DescribePackage{geometry}
% Overwrite geometry options such as the page margin settings.
%
% \verb|\geometry|\marg{options}
%
% \subsection{Class options}\label{sec:usage:class-options}
% You can pass several \meta{options} to the class by using
% \begin{sourceverb}
% \documentclass|oarg(options){rub-kunstgeschichte}
% \end{sourceverb}
% The \meta{options} are key/value pairs that sometimes defer to a default value when only the key is given.
%
% \DescribeOption{biblatex}
% Pass along options to the \pkg{biblatex} package. They overwrite default options set by this class.
%
% \DescribeOption{hyperref}
% Pass along options to the \pkg{biblatex} package. They do \textbf{not} overwrite default options set by this class as they are set after loading the package using the \verb|\hypersetup| command.
% To overwrite them, use \verb|\hypersetup|\marg{options} in the preamble.
%
% \DescribeOption{parskip}
% \DescribeDefault{\optn{true}}
% Specify wether to load the \pkg{parskip} package to remove indentation at the start of paragraphs.
%
% \DescribeOption{noparskip}
% \DescribeDefault{\optn{true}}
% The complementary option to the \optn{parskip} option.
%
% If neither \optn{parksip} nor \optn{noparskip} are given, the \pkg{parskip} package is automatically loaded by default.
%
% \StopEventually{}
%
% \clearpage
% \appendix
%
% \section{Implementation}\label{sec:implementation}
%
% \iffalse
%<*class>
% \fi
%
% \subsection{Class options}\label{sec:implementation:class-options}
% \iffalse
%% Class options
% \fi
% The class options are defined as keyval options for great flexibility.
% They toggle some of the class features or customize their behavior.
%
% \begin{option}{biblatex}
% The \optn{biblatex} option stores its content in a macro until it is later passed along to the \pkg{biblatex} package after specifying the default options (see \autoref{sec:implementation:package-loading:bibliography}).
% Therefore, options provided with this key overwrite the ones set per default by this class.
%    \begin{macrocode}
\DeclareKeys[rubkgi]{
    biblatex.store = \@rubkgi@biblatexOptions,
    biblatex.usage = load
}
%    \end{macrocode}
% \end{option}
%
% \begin{option}{hyperref}
% The \optn{hyperref} option passes its content along immediately, to be used as options when the \pkg{hyperref} package is loaded.
% This will \textbf{not} overwrite default options set by this class as they are set after loading the package using \verb|\hypersetup|\marg{options} (see also \autoref{sec:implementation:package-loading:others}).
%    \begin{macrocode}
\DeclareKeys[rubkgi]{
    hyperref.code  = \PassOptionsToPackage{#1}{hyperref},
    hyperref.usage = load
}
%    \end{macrocode}
% \end{option}
%
% \paragraph{Paragraph indentation}
% First we define a TeX switch which is later used (see \autoref{sec:implementation:package-loading}) to check wether to load the \pkg{parskip} package to remove the indentation at the start of paragraphs.
% \iffalse
%% TeX switch to decide wether to load the parskip package
% \fi
%    \begin{macrocode}
\newif\if@rubkgi@parskip
%    \end{macrocode}
% By default we set the switch to true, so the parskip package is normally loaded when using this class.
%    \begin{macrocode}
\@rubkgi@parskiptrue
%    \end{macrocode}
% \begin{option}{parskip}
% Then we declare the key so the switch can be turned on and off by the user in the class options.
%    \begin{macrocode}
\DeclareKeys[rubkgi]{
    parskip.if      = @rubkgi@parskip,
    parskip.usage   = load,
%    \end{macrocode}
% \end{option}
% \begin{option}{noparskip}
% Finally we define the complementary key for easier disabling of the parskip feature.
%    \begin{macrocode}
    noparskip.ifnot = @rubkgi@parskip,
    noparskip.usage = load
}
%    \end{macrocode}
% \end{option}
%
% \paragraph{Process options}
% After defining the class options it is necessary to process them too in order to actually make use of them.
%    \begin{macrocode}
\ProcessKeyOptions[rubkgi]
%    \end{macrocode}
%
% \subsection{Base class}\label{sec:implementation:base-class}
% \DescribeClass{article}
% The \pkg{\jobname} class is based on the \pkg{article} class.
% When loading the class we specify \texttt{12pt} as the base font size, as required by the guidelines.
% \iffalse
%% Load base class with 12pt base font size
% \fi
%    \begin{macrocode}
\LoadClass[12pt]{article}
%    \end{macrocode}
%
% \subsection{Loading packages}\label{sec:implementation:package-loading}
%
% \subsubsection{Bibliography}\label{sec:implementation:package-loading:bibliography}
%
% \DescribePackage{biblatex}
% \changes{v0.2.0}{2024-09-06}{Use biblatex with authortitle-dw style from biblatex-dw package.}^^A
% To support bibliography facilities out of the box, the \pkg{biblatex} package is loaded. To customize the behavior, a few options are passed to the package.
% \iffalse
%% biblatex options
% \fi
%    \begin{macrocode}
\PassOptionsToPackage{
%    \end{macrocode}
%
% \DescribeOption[biblatex]{backend}
% Defines the backend program. To use all features of \pkg{biblatex}, the \prog{biber} backend must be used.
%    \begin{macrocode}
    backend=biber,
%    \end{macrocode}
%
% \DescribeOption[biblatex]{singletitle}
% Prints the title of a cited work in short citations only if there is more than one work of the same author.
%    \begin{macrocode}
    singletitle=true,
%    \end{macrocode}
%
% \DescribeOption[biblatex]{autocite}
% Defines the behavior of the \cs{autocite} command, which in this case will behave like the \cs{footcite} command and will print citations in the footnotes instead of directly in the text.
%    \begin{macrocode}
    autocite=footnote,
%    \end{macrocode}
%
% \DescribeOption[biblatex]{autopunct}
% Controls whether the citation commands scan ahead for punctuation marks.
%    \begin{macrocode}
    autopunct=false
}{biblatex}
%    \end{macrocode}
%
% \DescribePackage{biblatex-dw}
% \iffalse
%% biblatex-dw package
% \fi
% Further approximation of the suggested bibliography and citation styles in the guidelines is achieved by using the \pkg{biblatex-dw} package.
% To use it, a few more options are passed to \pkg{biblatex}:
%    \begin{macrocode}
\PassOptionsToPackage{
%    \end{macrocode}
%
% \DescribeOption[biblatex]{style}
% The \optn{authortitle-dw} provided by the \pkg{biblatex-dw} package is probably the closest style to the one suggested in the guidelines.
%    \begin{macrocode}
    style=authortitle-dw,
%    \end{macrocode}
%
% The following options are provided by the \pkg{biblatex-dw} package:
%
% \DescribeOption[biblatex]{firstfull}
% Delivers a full citation for the first occurence of an entry.
%    \begin{macrocode}
    firstfull=true,
%    \end{macrocode}
%
% \DescribeOption[biblatex]{addyear}
% Adds the year of the publication after the title.
%    \begin{macrocode}
    addyear=true
}{biblatex}
%    \end{macrocode}
%
% After specifying the default options, we pass along the ones that might have been set in the class options.
% \iffalse
%% pass biblatex class options along
% \fi
%    \begin{macrocode}
\PassOptionsToPackage{\@rubkgi@biblatexOptions}{biblatex}
%    \end{macrocode}
%
% And finally the \pkg{biblatex} package is loaded.
% \iffalse
%% load biblatex
% \fi
%    \begin{macrocode}
\RequirePackage{biblatex}
%    \end{macrocode}
%
% \subsubsection{Document format}
%
% \DescribePackage{setspace}
% To achieve 1.5 times line spacing as required by the guidelines,
% we simply load the package \pkg{setspace} with the \optn{onehalfspacing} option.
% \iffalse
%% Set 1.5 times line spacing
% \fi
%    \begin{macrocode}
\RequirePackage[onehalfspacing]{setspace}
%    \end{macrocode}
%
% \DescribePackage{geometry}
% Used to set page size and margins.
% The guidelines require 2cm top, left and bottom margins as well as a 4cm correction margin on the right side.
% Furthermore A4 paper is the standard page size here.
% \iffalse
%% Set a4 paper size and margins
% \fi
%    \begin{macrocode}
\RequirePackage[
    a4paper,
    top=2cm,left=2cm,bottom=2cm,right=4cm
]{geometry}
%    \end{macrocode}
%
% \DescribePackage{parskip}
% \changes{v0.2.0}{2024-09-06}{Use parskip to avoid paragraph indentation}^^A
% To avoid indentation at the start of paragraphs, the \pkg{parskip} package is loaded if the corresponding switch is set to true. See also \autoref{sec:implementation:class-options}.
% \iffalse
%% Avoid paragraph indentation
% \fi
%    \begin{macrocode}
\if@rubkgi@parskip
    \RequirePackage{parskip}
\fi
%    \end{macrocode}
%
% \subsubsection{Other useful packages}\label{sec:implementation:package-loading:others}
%
% \DescribePackage{hyperref}
% \changes{v0.2.0}{2024-09-06}{Use hyperref for clickable links and references.}^^A
% Makes links and references clickable.
% \iffalse
%% Hyperref
% \fi
%    \begin{macrocode}
\RequirePackage{hyperref}
%    \end{macrocode}
% By default, we configure it to not highlight clickable elements.
%    \begin{macrocode}
\hypersetup{hidelinks=true}
%    \end{macrocode}
% \iffalse

%</class>
%<*example>
% \fi
% \clearpage
%
% \section{Example}\label{sec:example}
%
% To further exemplify the use of this class,
% we create an example \filenm{.tex} file.
% The full \filenm{rub-kunstgeschichte-example.tex} and the corresponding \PDF{} are available on GitHub.^^A
% \footnote{\url{https://github.com/rub-kgi/rub-kunstgeschichte-latex/releases}}
%
% First, the \pkg{rub-kunstgeschichte} class is loaded
% \iffalse
%% Load the rub-kunstgeschichte class
% \fi
%    \begin{macrocode}
\documentclass{rub-kunstgeschichte}
%    \end{macrocode}
% \iffalse

% \fi
%
% followed by the information that is needed to typeset a title:
%    \begin{macrocode}
\title{Example usage of the \textsf{rub-kunstgeschichte} class}
\author{Joran Schneyer}
%    \end{macrocode}
%
% For citations, the bibtex entries are usually written to a seperate \filenm{.bib} file.
% For the sake of this example we keep everything in one \filenm{.tex} file and use the \env{filecontents} environment instead.
% \iffalse

%% bibliography file (usually you would put this in a seperate .bib file)
% \fi
%    \begin{macrocode}
\begin{filecontents}{rub-kunstgeschichte-example.bib}
@article{exampleArticle,
    author  = {Maxi Mustermann},
    title   = {A very interesting article},
    year    = {2001},
    journal = {Important example journal}
}
@book{exampleBook,
    author    = {John Smith},
    title     = {A long example book},
    year      = {2024}
}
@online{exampleWebsite,
    author  = {{Example consortium}},
    title   = {The truth about example documents},
    year    = {2020},
    note    = {Internet forum article},
    url     = {https://example.com},
    urldate = {2100-04-01}
}
@manual{biblatexDocs,
    author   = {Philip Kime and Moritz Wemheuer and Philipp Lehman},
    title    = {The biblatex Package},
    subtitle = {Programmable Bibliographies and Citations},
    year     = {2024},
    url      = {https://ctan.org/pkg/biblatex},
    urldate  = {2024-06-25}
}
@online{biblatexCheatsheet,
    title   = {Biblatex Cheat Sheet},
    author  = {Clea F. Rees},
    year    = {2017},
    url     = {https://ctan.org/pkg/biblatex-cheatsheet},
    urldate = {2024-06-25}
}
\end{filecontents}
%    \end{macrocode}
% \iffalse

% \fi
% After that, we need to load the bibliography to use it with biblatex.
%    \begin{macrocode}
\addbibresource{rub-kunstgeschichte-example.bib}
%    \end{macrocode}
%
% Having finished the preamble, we begin the document, typeset the title and include a table of contents.
%    \begin{macrocode}
\begin{document}
    \maketitle
    \tableofcontents
%    \end{macrocode}
% \iffalse

% \fi
%
% Next we add different sections that explain common usage and some features of this class.
%    \begin{macrocode}
    \section{Introduction}
    The \textsf{rub-kunstgeschichte} class aims to implement
    the guidelines on scientific writing of the art history institute
    ``KGI'' (\textit{Kunstgeschichtliches Institut})
    at Ruhr University Bochum.

    This example document showcases a typical use
    of the \textsf{rub-kunstgeschichte} class.
    Just by using the class, the page is already formatted
    so that the typeset text has 12pt font size,
    there is a 1.5 times line-spacing present
    and the page size is A4 with 2cm margins at top, left and bottom,
    as well as a 4cm margin on the right.

    Also, paragraphs don't have an indentation
    in the first line by default,
    contrary to typical \LaTeX{} documents.
    Furthermore the \texttt{hyperref} package
    is automatically loaded to enable clickable
    links and references.

    \section{How to cite sources}
    This class automatically loads the \texttt{biblatex} package
    for sophisticated bibliography and citations.
    The class also sets some options by default
    that make \texttt{biblatex} behave closer to the
    suggested citation style in the guidelines of the institute.

    You can cite sources using the \verb|\autocite| command,
    which is configured by this class to use footnotes
    \autocite{exampleArticle}.
    Page numbers can be added in the optional argument
    \autocite[394]{exampleBook}
    and citation signals in a second one
    that comes before the one for page numbers
    \autocite[see][]{exampleWebsite}.
    You can even cite multiple sources at once
    using the \verb|\autocites| command
    \autocites[111]{exampleBook}[see also][13]{exampleArticle}.

    For more information refer to the documentation
    of the \texttt{biblatex} package
    \autocite{biblatexDocs}
    or the biblatex cheatsheet
    \autocite{biblatexCheatsheet}.

    At the end of the document we can include a bibliography
    containing all cited sources with \verb|\printbibliography|.
%    \end{macrocode}
% \iffalse

% \fi
%
% As suggested in the example document itself, we include the bibliography.
%    \begin{macrocode}
    \printbibliography
%    \end{macrocode}
%
% Finally we end the document environment
%    \begin{macrocode}
\end{document}
%    \end{macrocode}
% \clearpage
% \iffalse

%</example>
% \fi
%
% \Finale