path: root/macros/latex/contrib/tuda-ci/example/DEMO-TUDaPub.tex

%% This is file `DEMO-TUDaPub.tex' version 2.10 (2020/04/25),
%% it is part of
%% TUDa-CI -- Corporate Design for TU Darmstadt
%% ----------------------------------------------------------------------------
%%
%%  Copyright (C) 2018--2020 by Marei Peischl <marei@peitex.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
%% http://www.latex-project.org/lppl.txt
%% and version 1.3c or later is part of all distributions of LaTeX
%% version 2008/05/04 or later.
%%
%% This work has the LPPL maintenance status `maintained'.
%%
%% The Current Maintainers of this work are
%%   Marei Peischl <tuda-ci@peitex.de>
%%   Markus Lazanowski <latex@ce.tu-darmstadt.de>
%%
%% The development respository can be found at
%% https://github.com/tudace/tuda_latex_templates
%% Please use the issue tracker for feedback!
%%
%% ============================================================================
%%
% !TeX program = lualatex
%%

\documentclass[
	ngerman,
	accentcolor=9c,% Farbe für Hervorhebungen auf Basis der Deklarationen in den Corporate Design Richtlinien
%	logofile=example-image, %Falls die Logo Dateien nicht vorliegen
	]{tudapub}

\usepackage[english, main=ngerman]{babel}
\usepackage[babel]{csquotes}

\usepackage{biblatex}
\bibliography{DEMO-TUDaBibliography}

%Formatierungen für Beispiele in diesem Dokument. Im Allgemeinen nicht notwendig!
\let\file\texttt
\let\code\texttt
\let\pck\textsf
\let\cls\textsf

\usepackage{hologo}

\begin{document}

%Zusätzliche Metadaten für PDF/A. In diesem Fall notwendig, weil Titel ein Makro enthält.
\Metadata{
	author=Marei Peischl (peiTeX),
	title=TUDaPub - LaTeX-Paper im Corporate Design der TU Darmstadt,
	subject=Basisdokumentation und Template zur Nutzung der tudapub-Dokumentenkasse,
	date=2019-04-29,
	keywords=TU Darmstadt \sep Corporate Design \sep LaTeX
}

\title{TUDaPub -- \LaTeX-Paper im Corporate Design der TU Darmstadt}
\subtitle{Die Dokumentenklasse tudapub}
\author{Marei Peischl\thanks{pei\TeX{} \TeX{}nical Solutions}\and der \TeX-Löwe}

\titleimage{
%	%Folgende Box kann selbstverständlich durch ein mit \includegraphics geladenes Bild ersetzt werden.
	\color{black!30}\rule{\width}{\height}
}


%Varianten der Infoboxen
\addTitleBox{Institutsbezeichnung bzw. Logo in 2/3 Größe, vgl. \code{addTitleBoxLogo}}
%\addTitleBoxLogo{example-image}
%\addTitleBoxLogo*{\includegraphics[width=.3\linewidth]{example-image}}



\maketitle

\begin{abstract}
	Dieses Dokument stellt ein Template und gleichzeitig die Verwendungsdokumentation zur Dokumentenklasse tudapub, einem Teil des TUDa-CI-Paketes dar.

	Noch befindet sich das Projekt in der Testphase. Sollten Sie Fragen, Wünsche und Anregungen haben, bitten wir um eine entsprechende Mitteilung.
\end{abstract}

\begin{abstract}[english]
	Example for an additional abstract in English.
\end{abstract}



\tableofcontents

\section{Über diese Datei}
Die Datei \file{DEMO-TUDaPub.tex} beziehungsweise ihre Ausgabe \file{DEMO-TUDaPub.pdf} ist die Dokumentation der Dokumentenklasse \file{tudapub.sty}.

Sie ist Teil des TUDa-CI-Bundles und basiert in Teilen auf dem tuddesign-Paket von C.~v.~Loewenich und J.~Werner.

In diesem Dokument werden die speziellen Optionen und Einstellungsmöglichkeiten erläutert.

\section{Verwendung}
Die Klasse wird wie gewohnt geladen:
\begin{verbatim}
\documentclass[<Optionen>{tudapub}
\end{verbatim}
Im folgenden werden die möglichen Optionen beschrieben.

\subsection{Klassenoptionen}

\begin{description}
	\item[class=<article|report|book>] Diese Option legt die Basisdokumentenklasse fest. Die Werte laden die entsprechende KOMA-Script-Klasse \cite{scrguide}. Der Wert \code{article} lädt somit die Klasse \code{scrartcl}.

	KOMA-Script ist eine Sammlung von Klassen und Paketen für \LaTeX, die neben den typografischen Anpassungen an den Europäischen Raum auch die Konfigurationsmöglichkeiten stark erweitert.
	\item[color=<Farbe>] Wählt die Schmuckfarbe für die Nutzung in der Identitätsleiste aus. Die Farbcodes finden sich in der Farbübersicht in den Corporate Design Richtlinien. Neben diesen Farben kann prinzipiell jede beliebige Farbe übergeben werden. Die Optionen \code{accentcolor}, \code{textaccentcolor} und \code{identbarcolor} werden anlog direkt an \pck{tudacolors} übergeben. Auf diesem Weg können die Farben unabhängig voneinander gesetzt werden.
	\item[marginpar] Schaltet die Randnotizspalte um. Voreingestellt ist \code{auto}. Dies bedeutet, dass die Randnotizspalte wie im Corporate Design Handbuch über die fünfte Spalte läuft.  \marginpar{Beispiel für eine Randnotiz}.
	Darüber werden auch die Werte \code{true} und \code{false} akzeptiert. \code{false} setzt die Breite der Randnotizspalte auf 0. Der Mechanismus selbst wird nicht deaktiviert.

	Randnotizen werden über den komafont-Mechanismus \cite[vgl.][]{scrguide} im Element \code{marginpar} gesetzt. Seine Voreinstellung entspricht
	\begin{verbatim}
	\setkomafont{marginpar}{\accentfont}
	\end{verbatim}
	Um zusätzlich farbige Randnotizen zu setzen, könnte dies geändert werden, über
	\begin{verbatim}
	\addtokomafont{marginpar}{\color{textaccentcolor}}
	\end{verbatim}
	\marginline{
		\includegraphics[width=\marginparwidth]{example-image}\\
		Flattersatz in der marginnline aus \KOMAScript
	}
	\item[twocolumn] Aktiviert den zweispaltigen Modus global. In diesem Fall werden jedoch aufgrund ihrer Natur zwei Randnotizspalten erzeugt. Eine Nutzung in Kombination mit \code{marginpar=auto} ist daher in den meisten Fällen fragwürdig. Falls der zweispaltige Modus lediglich lokal aktiviert wird, entfällt dieses Verhalten, allerdings werden dann Randnotizen deaktiviert.
	\item[ruledheaders] Wählt den Stil der Überschriften aus. \code{ruledheaders=all} wählt den mit Linien eingerahmten Stil für alle bis zur \verb+\subsubsection+. Bei \code{chapter} beziehungsweise \code{section} ist dieser Stil entsprechend
	beschränkt. False lädt den Standardstil aus \KOMAScript.
	\item[type] Als Typ stehen im Moment \code{publication} und \code{thesis} zur Verfügung. Die besonderen Möglichkeiten im Typ thesis sind in der Datei DEMO-TUDaThesis.tex/.pdf geschildert. Voreingestellt ist \code{publication}.
	Zusätzlich existiert ab Version 1.2 noch der Modus \code{intern}. Dieser wählt die Optionen \code{titlepage=false} für einen Titelkopf statt Titelseiten, sowie die TUDaPub-Optionen \code{pdfa=false} und \code{IMRAD=false}. Dieser Modus ist für kurze, interne Berichte gedacht.
	\item[headline] Die Kopfzeile verfügt über die im Corporate Design beschriebenen Layoutmöglichkeiten über den Wert \code{automark}. Da diese Lösung typografisch nicht sonderlich sinnvoll ist, ist es auch möglich, diese abzuschalten. Voreingestellt ist ein Stil ohne Kolumnentitel.
	\item[logo] Option für die Titelseite, siehe \ref{sec:title}
	\item[colorback] Option für die Titelseite, siehe \ref{sec:title}
	\item[IMRAD=true/false] Deaktiviert die Prüfung auf IMRAD-Labels, siehe Abschnitt \ref{sec:IMRAD}.
	\item[logofile=<Dateipfad>] Erlaubt es ein alternatives Logo zu übergeben. Diese Option existiert, um die Templates auch ohne das TUDa-Logo nutzen zu können. Die Logos sind der internen Verwendung vorbehalten und dürfen daher nicht mit diesem Template veröffentlicht werden.
\end{description}

\noindent Der Rest der Dokumentenklasse entspricht dem Standard von \KOMAScript, vgl. Abschnitt \ref{sec:KOMA}.

\subsection{Die Titelseite}
\label{sec:title}

Die Titelseite wird von tudapub automatisch generiert. Die Verwendung hierfür entspricht größtenteils der klassischen Methode unter Verwendung von \code{maketitle}.

Die \KOMAScript-Option \code{titlepage} erlaubt es üblicherweise, zwischen Titelseiten und Titelkopf umzuschalten. Bis Version 1.2 war diese Option deaktiviert. Mittlerweile existiert ein Modus für einen Titelkopf, dieser entspricht jedoch nicht den offiziellen Vorgaben und ist für interne Verwendung gedacht. Aufgrund der Implementierung wird \code{titlepage=true} identisch zu \code{titlepage=firstiscover} behandelt.

Die Makros wie \code{author}, \code{title}, \code{subtitle} und \code{date} entsprechen der normalen Verwendung. Für die Institutszuweisung kann ebenfalls wie gewohnt \code{thanks} verwendet werden.

Zusätzlich stehen die Makros \code{titleimage} und \code{addTitleBox} zur Verfügung um weitere Informationen bereit zu stellen.

\minisec{titleimage}
Das Makro \code{titleimage} akzeptiert beliebigen Inhalt. Dieser wird bündig mit der oberen Ecke im Hauptteil der Titelseite platziert.
Üblicherweise wird dieses Makro zur Platzierung einer Grafik genutzt:

\begin{verbatim}
\titleimage{\includegraphics[width=\width]{example-image}}
\end{verbatim}

Zusätzlich stehen die Makros \code{titleimage} und \code{addTitleBox} zur Verfügung, um den unteren Teil der Titelseite zu füllen.

\begin{verbatim}
\titleimage{\includegraphics[height=\height]{titleimage}}
\addTitleBox{Institut 1}
\end{verbatim}
Die Institutsboxen werden mit vorgegebenem Abstand unter dem Logo platziert. Hier kann Text erscheinen oder auch ein Institutslogo. Der Hintergrund ist weiß.

Um die Institutsboxen für Logos zu verwenden, liefert \cls{tudapub} das Makro \code{\addTitleBoxLogo}. Als Argument akzeptiert es einen Bilddateipfad.

\begin{verbatim}
\addTitleBoxLogo{example-image}
\addTitleBoxLogo*{\includegraphics[width=\linewidth]{example-image}}
\end{verbatim}

\minisec{Optionen für die Titelseite}
Die Position des Logos ist umschaltbar. Dies geschieht über die Dokumentenklassenoption \code{logo=head/body}.
\begin{description}
	\item[logo=head] Das Logo wird im Kopf direkt neben dem Titel platziert. Der Titel wird in der Breite reduziert. Der Hintergrund des Titels wird in der Farbe der Identitätsleiste eingefärbt. Zusätzliche Infoboxen (s.u.) werden ebenfalls im Kopf platziert.
	\item[logo=body] Das Logo samt der Infoboxen wird im Körper der Titelseite platziert.
\end{description}

Darüber hinaus lässt sich die Farbgebung umschalten. Die Option \code{colorback} schaltet zwischen dem farbigen Block auf der Titelseite und weißem Hintergrund um. Falls die Kombination \code{colorback=false} und \code{logo=head} geschaltet ist, bleibt der obere Teil der Titelseite jedoch farbig.

\subsection{Strukturierungselemente}
\minisec{Die abstract-Umgebung}
Die \code{abstract}-Umgebung wird für \cls{tudapub} um eine Option für die Sprache erweitert. Somit ist es möglich, mehrere Zusammenfassungen in einem Dokument zu nutzen.

\begin{verbatim}
\begin{abstract}
	Zusammenfassung entsprechend der Dokumentensprache. In diesem Fall Deutsch.
\end{abstract}

\begin{abstract}[english]
	Zusätzliche Zusammenfassung in englischer Sprache
\end{abstract}
\end{verbatim}

Für die Verwendung ist wichtig, dass alle im Dokument genutzten Sprachen geladen werden. Im Falle des Beispiels muss also sowohl \code{ngerman} als auch \code{english} an das \pck{babel}-Paket übergeben werden.


\subsection{PDF/A Konformität}
Die Klasse TUDaPub unterstützt den Standard PDF/A 2b. Der PDF/A-Modus ist automatisch aktiviert. die zugehörige Option kann jedoch über \code{pdfa=false} ausgeschaltet werden.
Nun wird zusätzlich eine \code{\textbackslash.xmpdata}-Datei generiert. Üblicherweise werden die Titelinformationen direkt übernommen.

Dies kann jedoch bei der Verwendung einiger Makros innerhalb der Felder zu Problemen führen. Beispielsweise enthält der Titel für dieses Dokument das Makro \code{\LaTeX}. Es können daher nur Textelemente übernommen werden. Ähnlich den Linkbezeichnungen über PDF-Lesezeichen.

Um dieses Problem zu umgehen stellt \cls{tudapub} hierfür das Makro \code{\textbackslash{}Metadata\{\}} zur Verfügung. Hier können sämtliche von \pck{pdfx} verarbeitbaren Variablen nach Schlüssel$=$Wert-Struktur gesetzt werden. Es ist zu beachten, dass dieses Makro nur dann funktioniert, wenn die \code{pdfa}-Ausgabe aktiviert ist. Ist dies nicht der Fall, so gibt \cls{tudapub} eine entsprechende Fehlermeldung zu diesem Widerspruch aus.
Zum Beispiel:
\begin{verbatim}
\Metadata{
	author=Marei Peischl (peiTeX),
	title=LaTeX im Corporate Design der TU Darmstadt,
}
\end{verbatim}
Das Feld \code{publisher} ist mit \enquote{TU Darmstadt} vorbelegt, kann aber überschrieben werden.

Um mehrere Einträge zu trennen, wird das Makro \code{\textbackslash{}sep} genutzt.
\begin{verbatim}
keywords={TU Darmstadt \sep Corporate Design \sep LaTeX}
\end{verbatim}
Wenn der Eintrag selbst Kommata enthalten könnte, dann ist eine Gruppierung um den Eintrag notwendig. Sonst wird der Text nach dem Komma als nächstes Keyword interpretiert.

\minisec{Möglich Probleme mit älteren Systemen:}

Bei älteren \TeX-Distributionen kann es vorkommen, dass die Farbprofile nicht vorinstalliert sind. In diesem Fall wird eine Fehlermeldung im folgenden Sinn erzeugt:
\begin{verbatim}
No color profile found to use for RGB screen colors
\end{verbatim}
Um diesen Fehler zu beheben, können die notwendigen *.icc-Dateien unter \url{http://mirror.ctan.org/support/colorprofiles} heruntergeladen und entweder installiert oder im Projektordner mit abgelegt werden. Die einfachste Lösung bleibt jedoch, das eigene \TeX-System zu aktualisieren.

Darüber hinaus werden bei \hologo{XeLaTeX} einige Features nicht unterstützt. In diesem Fall erzeugt \code{pdfa=false} ein kompilierbares Dokument, allerdings sollte für validierbare PDF/A-Dateien auf \hologo{LuaLaTeX} einer möglichst aktuellen Version umgestiegen werden.

\subsection{Zusätzliche Metadaten nach Wunsch der Universitätsbibliothek}
\label{sec:IMRAD}
Es existiert ein Mechanismus um das Strukturierungsmodell IMRaD \cite{imrad} zu kennzeichnen.
Im Stil der einzelnen Teilbereiche können so, über Aufruf von

\begin{verbatim}
\IMRADlabel{introduction}
\IMRADlabel{methods}
\IMRADlabel{results}
\IMRADlabel{discussion}
\end{verbatim}
entsprechende Labels generiert werden. Sie haben den Namen \code{IMRAD:<Schlüssel>}.

Der Prüfmechanismus ist auf Wunsch der Bibliothek standardmäßig aktiviert, kann jedoch durch die Option \code{IMRAD=false} deaktiviert werden.


\section{Erweiterte Konfigurationsmöglichkeiten}


\subsection{Anpassungen, die von den Corporate Design Richtlinien abweichen}
\cls{tudapub} kann entgegen der Corporate Design Richtlinien auch andere Schriftgrößen verarbeiten. Hierfür wird die \code{fontsize}-Option aus \KOMAScript{} genutzt (z.\,B. \code{fontsize=11pt}). Sofern keine spezielle Schriftgrößendatei für TUDa-CI vorliegt, wird die mit \KOMAScript{} ausgelieferte Datei gewählt.

Beispiele für Abweichungen aus typografischen Gründen sind Beispielsweise auch in den Demo-Dateien für Abschlussarbeiten gezeigt.

\subsection{Frontmatter/Mainmatter/Backmatter}
Üblicherweise existieren die Makros \verb+\frontmatter+, \verb+\mainmatter+ und \verb+\backmatter+ lediglich bei der Basisklasse \cls{scrbook}.
Auf Wunsch wurden diese Makros auch bei \cls{scrartcl} und \cls{scrreprt} als Basis bereitgestellt.

Somit ist es möglich, für den Vorspann auf römische Ziffern zu wechseln. Ab \verb+\mainmatter+ werden dann arabische Ziffern verwendet.


\subsection{Mathematikschriften}
Da es keine Compiler-unanbhängige, universelle Mathematikschrift gibt und die Corporate Design Richtlinien auch keinerlei Empfehlung berücksichtigen, wurden hierfür einige mögliche Varianten diskutiert. Die Voreinstallung entspricht immer dem Standard der Installation. Es werden keine spezifischen Einstellungen geladen.

Die Diskussion hierzu findet sich unter \url{https://github.com/tudace/tuda_latex_templates/issues/19}

Im Folgenden werden ein paar Beispielkonfigurationen gezeigt. Grundsätzlich ist die Mathematikschriftart jedoch -- abgesehen durch Einschränkungen des Compilers -- frei wählbar.

Bei Auswahl und Verwendung ist häufig der \enquote{\TeX{} Font Catalogue hilfreich}: \url{https://tug.org/FontCatalogue/mathfonts.html}

\subsection{\hologo{pdfLaTeX}}
Hier existiert eine Variante, die die Buchstaben der Basischriftart \enquote{Charter} mit Mathematiksymbolen aus unterschiedlichen Zeichensätzen möglichst passend kombiniert.

\begin{verbatim}
\usepackage[charter]{mathdesign}
\end{verbatim}

Es gibt ähnliche Ansätze für ein paar weitere Kombinationen. Einige Beispiele finden sich in der XCharter Dokumentation. \url{http://mirrors.ctan.org/fonts/xcharter/doc/xcharter-doc.pdf}


\section{Standard-KOMA-Script}
\label{sec:KOMA}
Da die Klasse bis auf ein paar erzwungene Einstellungen, die das Layout betreffen, vollständig \KOMAScript-kompatibel ist, ist für sämtliche Modifikationen ein Blick in die \KOMAScript-Dokumentation hilfreich. Für einen Großteil bietet \KOMAScript{} eine eigene Lösung, wodurch Ergänzungspakete oft hinfällig sind.

Beispiele für typische Modifikationen, die auch im Rahmen des Corporate Design zulässig sind:
\begin{itemize}
	\item Umstellung der Absatzkennzeichnungsmethode von Einzug auf Abstand (Klassenoption parskip)
	\item Elementnummerierung mit oder ohne Endpunkt
	\item Positionierung, Ausrichtung und Abstände bei captions.
\end{itemize}

\printbibliography


\section{Bekannte Inkompatibilitäten}

\subsection{\texorpdfstring{\hologo{XeLaTeX}}{XeLaTeX} und PDF/A}
Das Paket \pck{pdfx}, über welches die PDF/A Kompatibilität erzeugt wird, hat nur einen begrenzten Support für \hologo{XeLaTeX}.
Es wird eine entsprechende Warnung erzeugt, allerdings kann es bei älteren \hologo{XeLaTeX}-Versionen passieren, dass \pck{pdfx} bereits Fehlermeldungen erzeugt. Diese werden vor der Überprüfung auf das Paketalter ausgegeben. Das Paket muss geladen worden sein, bevor die Überprüfung auf Alter möglich ist.


\end{document}