% ======================================================================
% scrlayer-notecolumn-de.tex
% Copyright (c) Markus Kohm, 2013-2022
%
% This file is part of the LaTeX2e KOMA-Script bundle.
%
% This work may be distributed and/or modified under the conditions of
% the LaTeX Project Public License, version 1.3c of the license.
% 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 2005/12/01 or later and of this work.
%
% This work has the LPPL maintenance status "author-maintained".
%
% The Current Maintainer and author of this work is Markus Kohm.
%
% This work consists of all files listed in MANIFEST.md.
% ======================================================================
%
% Chapter about scrlayer-notecolumn of the KOMA-Script guide
% Maintained by Markus Kohm
%
% ----------------------------------------------------------------------
%
% Kapitel über scrlayer-notecolumn in der KOMA-Script-Anleitung
% Verwaltet von Markus Kohm
%
% ============================================================================

\KOMAProvidesFile{scrlayer-notecolumn.tex}
                 [$Date: 2022-07-17 12:36:46 +0200 (So, 17. Jul 2022) $
                  KOMA-Script guide (chapter:scrlayer-notecolumn)]

\chapter{Notizspalten mit \Package{scrlayer-notecolumn}}
\labelbase{scrlayer-notecolumn}

\BeginIndexGroup
\BeginIndex{Package}{scrlayer-notecolumn}%
Bis einschließlich Version~3.11b unterstützte \KOMAScript{} Notizspalten nur
in Form der Marginalienspalte, die mit \DescRef{maincls.cmd.marginpar} und
\DescRef{maincls.cmd.marginline} (siehe \autoref{sec:maincls.marginNotes},
\DescPageRef{maincls.cmd.marginline}) mit Inhalt versehen werden
können. Jene Art der Randnotizen hat allerdings einige Nachteile:
\begin{itemize}
\item Randnotizen können nur vollständig auf einer einzelnen Seite gesetzt
  werden. Seitenumbrüche\textnote{Seitenumbruch} innerhalb von Randnotizen
  sind nicht möglich. Dies führt teilweise dazu, dass die Randnotizen bis in
  den unteren Rand hineinragen.
\item Randnotizen in der Nähe des Seitenumbruchs können auf die nächste Seite
  rutschen und dort im Falle des doppelseitigen Layouts mit alternierenden
  Marginalienspalten im falschen Rand\textnote{Zuordnung zum richtigen Rand}
  ausgegeben werden. Dieses Problem ist mit dem Zusatzpaket
  \Package{mparhack}\IndexPackage{mparhack} oder durch Verwendung von
  \Macro{marginnote} aus dem Paket
  \Package{marginnote}\IndexPackage{marginnote} (siehe
  \cite{package:marginnote}) lösbar.
\item Randnotizen innerhalb von Gleitumgebungen\textnote{Gleitumgebungen} oder
  Fußnoten\textnote{Fußnoten} sind nicht möglich. Auch dieses Problem ist mit
  \Package{marginnote} lösbar.
\item Es gibt nur eine Marginalienspalte\textnote{mehrere Notizspalten} oder
  allenfalls zwei, wenn mit \Macro{reversemarginpar} und
  \Macro{normalmarginpar} gearbeitet wird, wobei \Macro{reversemarginpar} bei
  doppelseitigen Dokumenten kaum zu gebrauchen ist.
\end{itemize}
Die Verwendung von \Package{marginnote}\IndexPackage{marginnote} führt zu
einem weiteren Problem. Da das Paket keine Kollisionserkennung besitzt, können
sich Randnotizen, die in unmittelbarer Nähe veranlasst wurden, gegenseitig
ganz oder teilweise überdecken. Darüber hinaus führt \Macro{marginnote}, je
nach den gewählten Einstellungen von \Package{marginnote}, manchmal zu
Veränderungen beim Zeilenabstand des normalen Textes.

Das Paket \Package{scrlayer-notecolumn} tritt an, all diese Probleme zu
lösen. Dazu stützt es sich auf die Grundfunktionalität von
\hyperref[cha:scrlayer]{\Package{scrlayer}}\IndexPackage{scrlayer}%
\important{\hyperref[cha:scrlayer]{\Package{scrlayer}}}. Damit geht aber
auch ein Nachteil einher:\textnote{Achtung!} Notizen können nur auf den Seiten
ausgegeben werden, die einen auf \hyperref[cha:scrlayer]{\Package{scrlayer}}
basierenden Seitenstil besitzen. Dieser Nachteil lässt sich mit Hilfe von
\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}%
\important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}}%
\IndexPackage{scrlayer-scrpage} jedoch leicht auf"|lösen oder sogar in einen
Vorteil verwandeln.


\section{Hinweise zum Entwicklungsstand}
\seclabel{draft}

Das Paket wurde ausschließlich zur Demonstration des Potentials von
\hyperref[cha:scrlayer]{\Package{scrlayer}}\important{\hyperref[cha:scrlayer]{\Package{scrlayer}}}
als sogenannter\textnote{Proof of Concept} \emph{Proof of Concept}
entwickelt. Obwohl es sich derzeit noch in einem recht frühen
Entwicklungsstadium befindet, ist die Stabilität von weiten Teilen weniger
eine Frage von \Package{scrlayer-notecolumn} als von
\hyperref[cha:scrlayer]{\Package{scrlayer}}. Dennoch ist davon auszugehen,
dass sich auch in \Package{scrlayer-notecolumn} noch Fehler befinden. Es wird
darum gebeten, diese bei Auf"|finden zu melden. Einige
\emph{Unzulänglichkeiten} des Pakets sind jedoch auch der Minimierung des
Aufwands geschuldet. So können Notizspalten zwar über Seiten hinweg umbrochen
werden, allerdings findet dabei kein neuerlicher Absatzumbruch statt. Dies ist
bei \TeX{} schlicht nicht vorgesehen.

Da das Paket eher als experimentell\textnote{experimentell} gilt, findet sich
die Anleitung hier im zweiten Teil \iffree{der \KOMAScript-Anleitung}{dieses
  Buches}. Dementsprechend richtet sie sich auch in erster Linie an erfahrene
Anwender. Für Anfänger oder Anwender, die sich bereits deutlich auf dem Weg
zum \LaTeX-Experten\textnote{für \LaTeX-Experten} befinden, mag daher einiges
in den nachfolgenden Erklärungen unklar oder gar unverständlich
sein. \iffree{Ich bitte um Nachsicht, dass ich bei experimentellen Paketen den
  Aufwand für die Anleitung halbwegs erträglich halten will.}{Sie sollten
  jedoch genügen, um einfache Aufgaben mit \Package{scrlayer-notecolumn} lösen
  zu können. Gleichzeitig finden Entwickler hoffentlich nützliche Anregungen
  für eigene Ideen.}

\iffalse% Umbruchoptimierung
Es sei auch darauf\textnote{Achtung!} hingewiesen, dass der \KOMAScript-Autor
nicht für die Weiterentwicklung des Pakets garantiert und nur eingeschränkten
Support dafür bietet. Das liegt in der Natur eines Pakets, das nur zu
Demonstrationszwecken geschrieben wurde.%
\fi

\LoadCommonFile{options}% \section{Frühe oder späte Optionenwahl}

\LoadCommonFile{textmarkup}% \section{Textauszeichnungen}

\section{Deklaration neuer Notizspalten}
\seclabel{declaration}

Beim Laden des Pakets wird bereits automatisch eine Notizspalte namens
\PValue{marginpar} deklariert. Wie der Name andeutet, liegt diese Notizspalte
im Bereich der normalen Marginalienspalte von \DescRef{maincls.cmd.marginpar}
und \DescRef{maincls.cmd.marginline}. Dabei werden auch die Einstellungen
\Macro{reversemarginpar} und \Macro{normalmarginpar} beachtet, allerdings
nicht für die einzelnen Notizen, sondern nur für die gesamten Notizen einer
Seite. Maßgeblich ist die Einstellung, die am Ende der Seite, nämlich
bei der Ausgabe der Notizspalte, gilt. Will man hingegen innerhalb einer Seite
sowohl Notizen links als auch rechts neben dem Haupttext haben, so sollte man
sich eine zweite Notizspalte definieren.

Die Voreinstellungen für alle neu deklarierten Notizspalten entsprechen im
Übrigen \iffree{}{\pagebreak}% Umbruchkorrektur
den erwähnten Einstellungen für die vordefinierte
\PValue{marginpar}. %
\iftrue% Umbruchoptimierung
Diese können bei der Deklaration jedoch leicht geändert werden.%
\fi

Es ist zu beachten\textnote{Achtung!}, dass Notizspalten nur auf Seiten
ausgegeben werden, deren Seitenstil auf dem Paket
\hyperref[cha:scrlayer]{\Package{scrlayer}}\IndexPackage{scrlayer}%
\important{\hyperref[cha:scrlayer]{\Package{scrlayer}}} basiert. Das Paket
\hyperref[cha:scrlayer]{\Package{scrlayer}} wird von
\Package{scrlayer-notecolumn} automatisch geladen und stellt in der
Voreinstellung lediglich den Seitenstil
\PageStyle{empty}\IndexPagestyle{empty} bereit. Werden weitere Seitenstile
benötigt, wird zusätzlich das Paket
\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}%
\IndexPackage{scrlayer-scrpage}%
\important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}}
empfohlen.

\begin{Declaration}
  \Macro{DeclareNoteColumn}\OParameter{Liste~der~Einstellungen}
                           \Parameter{Name~der~Notizspalte}
  \Macro{DeclareNewNoteColumn}\OParameter{Liste~der~Einstellungen}
                              \Parameter{Name~der~Notizspalte}
  \Macro{ProvideNoteColumn}\OParameter{Liste~der~Einstellungen}
                           \Parameter{Name~der~Notizspalte}
  \Macro{RedeclareNoteColumn}\OParameter{Liste~der~Einstellungen}
                             \Parameter{Name~der~Notizspalte}%
\end{Declaration}
Mit Hilfe dieser Anweisungen können Notizspalten angelegt werden. Dabei
erzeugt \Macro{DeclareNoteColumn} die Notizspalte ungeachtet der Tatsache, ob
sie bereits existiert, während \Macro{DeclareNewNoteColumn} einen
Fehler ausgibt, falls der \PName{Name der Notizspalte} bereits für eine andere
Notizspalte vergeben ist, und \Macro{ProvideNoteColumn} in eben diesem Fall
schlicht nichts tut. Mit \Macro{RedeclareNoteColumn} wiederum kann nur eine
bereits existierende Notiz-Spalte neu konfiguriert werden.

Bei der Neukonfigurierung bereits existierender Notizspalten mit
\Macro{DeclareNoteColumn} oder \Macro{RedeclareNoteColumn} gehen im Übrigen
die bereits erzeugten Notizen für diese Spalte nicht verloren, sondern bleiben
erhalten.

\BeginIndex{FontElement}{notecolumn.\PName{Name der Notizspalte}}%
\BeginIndex{FontElement}{notecolumn.marginpar}%
Für neue Notizspalten wird immer ein Element zur Änderung der Schriftattribute
mit \DescRef{\LabelBase.cmd.setkomafont} und \DescRef{\LabelBase.cmd.addtokomafont} angelegt,
falls dieses noch nicht existiert. Als Name für das Element wird
\PValue{notecolumn.}\PName{Name der Notizspalte} verwendet. Dementsprechend
existiert für die vordefinierte Notizspalte \PValue{marginpar} das
Element\textnote{Name des Elements} \PValue{notecolumn.marginpar}. Die
Voreinstellung kann bei der Deklaration einer Notizspalte direkt über die
Option \Option{font} innerhalb der optionalen \PName{Liste der Einstellungen}
angegeben werden.%
\EndIndex{FontElement}{notecolumn.marginpar}%
\EndIndex{FontElement}{notecolumn.\PName{Name der Notizspalte}}%

Die \PName{Liste der Einstellungen} ist eine durch Komma separierte Liste von
Einstellungen oder Optionen. Die verfügbaren Optionen sind in
\autoref{tab:scrlayer-notecolumn.note.column.options} %
\iffalse % Umbruchkorrektur
\unskip, \autopageref{tab:scrlayer-notecolumn.note.column.options} %
\fi%
zu finden. Als\textnote{Voreinstellung: Option \Option{marginpar}}
Voreinstellung ist \Option{marginpar} immer gesetzt, kann aber durch
individuelle Einstellungen überschrieben werden.

%
%\begin{table}% Umbruchoptimierung: Tabelle hinter das Beispiel verschoben
\begin{desclist}
  \desccaption{%
%  \caption[Mögliche Einstellungen für die Deklaration von Notizspalten]{%
    Mögliche Einstellungen für die Deklaration von Notizspalten%
%  }%
    \label{tab:scrlayer-notecolumn.note.column.options}%
  }{%
    Mögliche Einstellungen für die Deklaration von Notizspalten
    (\emph{Fortsetzung})%
  }%
%  \begin{desctabular}
    \entry{\OptionVName{font}{Schriftattribute}}{%
      Einstellung der \PName{Schriftattribute} der Notizspalte mit Hilfe von
      \DescRef{\LabelBase.cmd.setkomafont}. Für erlaubte Werte sei auf
      \autoref{sec:\LabelBase.textmarkup},
      \DescPageRef{\LabelBase.cmd.setkomafont} verwiesen.\par%
      Voreinstellung: \emph{leer}%
    }%
    \entry{\Option{marginpar}}{%
      Position und Breite der Notizspalte werden so eingestellt, dass sie der
      Marginalienspalte von \DescRef{maincls.cmd.marginpar} entsprechen. Eine
      Umschaltung zwischen \Macro{reversemarginpar}\IndexCmd{reversemarginpar}
      und \Macro{normalmarginpar}\IndexCmd{normalmarginpar} wird immer nur am
      Ende der Seite bei der Ausgabe der Notizspalte beachtet. Es wird darauf
      hingewiesen, dass diese Option kein Argument erwartet oder erlaubt.\par%
      Voreinstellung: \emph{ja}%
    }%
    \entry{\Option{normalmarginpar}}{%
      Position und Breite der Notizspalte werden so eingestellt, dass sie der
      Marginalienspalte von \DescRef{maincls.cmd.marginpar} bei Einstellung
      \Macro{normalmarginpar} entsprechen. Es wird darauf hingewiesen, dass
      diese Option kein Argument erwartet oder erlaubt.\par%
      Voreinstellung: \emph{nein}%
    }%
    \entry{\OptionVName{position}{Abstand}}{%
      Die Notizspalte wird mit \PName{Abstand} vom linken Rand des Papiers
      gesetzt. Dabei sind für \PName{Abstand} auch komplexe Ausdrücke
      gestattet, solange diese voll expandierbar sind und zum Zeitpunkt der
      Ausgabe der Notizspalte zu einer Länge oder zu einem Längenwert oder
      einem Längenausdruck expandieren. Siehe
      \cite[Abschnitt~3.5]{manual:eTeX} für weitere Informationen zu
      Längenausdrücken.\par%
      Voreinstellung: \emph{durch Option \Option{marginpar}}%
    }%
    \entry{\Option{reversemarginpar}}{%
      Position und Breite der Notizspalte werden so eingestellt, dass sie der
      Marginalienspalte von \DescRef{maincls.cmd.marginpar} bei Einstellung
      \Macro{reversemarginpar} entsprechen. Es wird darauf hingewiesen, dass
      diese Option kein Argument erwartet oder erlaubt.\par%
      Voreinstellung: \emph{nein}%
    }%
    \entry{\OptionVName{width}{Breite}}{%
      Die Notizspalte wird mit der angegebenen Breite gesetzt. Dabei sind für
      \PName{Breite} auch komplexe Ausdrücke gestattet, solange diese voll
      expandierbar sind und zum Zeitpunkt der Ausgabe der Notizspalte zu einer
      Länge oder einem Längenwert oder einem Längenausdruck expandieren. Siehe
      \cite[Abschnitt~3.5]{manual:eTeX} für weitere Informationen zu
      Längenausdrücken.\par%
      Voreinstellung: \emph{durch Option \Option{marginpar}}%
    }%
%  \end{desctabular}
%\end{table}
\end{desclist}

Da die Notizspalten mit Hilfe von \hyperref[cha:scrlayer]{\Package{scrlayer}}%
\important{\hyperref[cha:scrlayer]{\Package{scrlayer}}} definiert werden, wird
auch für jede Notizspalte eine Ebene\Index{Ebenen} angelegt. Als
Name\textnote{Name der Ebene} für diese Ebene wird ebenfalls
\PValue{notecolumn.}\PName{Name der Notizspalte} verwendet. Näheres zu Ebenen
ist \autoref{sec:scrlayer.layers}, ab \autopageref{sec:scrlayer.layers} zu
entnehmen.
%
\begin{Example}
  Angenommen, Sie sind Professor für ulkiges Recht und wollen eine Abhandlung
  über das neue »Gesetz über die ausgelassene Verbreitung allgemeiner Späße«,
  kurz GüdaVaS, schreiben. Der Hauptaugenmerk soll dabei jeweils auf dem
  Kommentar zu einzelnen Paragraphen liegen. Sie entscheiden sich für ein
  zweispaltiges Layout, wobei der Kommentar in der Hauptspalte enthalten sein
  soll und die Paragraphen jeweils klein\iffree{ und in Farbe}{} in einer
  schmaleren Notizspalte rechts daneben.
\begin{lstcode}
  \documentclass{scrartcl}
  \usepackage[ngerman]{babel}

  \usepackage[T1]{fontenc}
  \usepackage{lmodern}
  \usepackage{xcolor}

  \usepackage{scrjura}
  \setkomafont{contract.Clause}{\bfseries}
  \setkeys{contract}{preskip=-\dp\strutbox}

  \usepackage{scrlayer-scrpage}
  \usepackage{scrlayer-notecolumn}

  \newlength{\paragraphscolwidth}
  \AfterCalculatingTypearea{%
    \setlength{\paragraphscolwidth}{%
      .333\textwidth}%
    \addtolength{\paragraphscolwidth}{%
      -\marginparsep}%
  }
  \recalctypearea
  \DeclareNewNoteColumn[%
    position=\oddsidemargin+1in
             +.667\textwidth
             +\marginparsep,
    width=\paragraphscolwidth,
    font=\raggedright\footnotesize
         \color{blue}
  ]{paragraphs}
\end{lstcode}
  Es wird ein einseitiger Artikel verfasst. Dazu wird die
  Sprache\textnote{Sprache mit \Package{babel}} mit Hilfe
  des \Package{babel}\IndexPackage{babel}-Pakets auf Deutsch (neue
  Rechtschreibung) festgelegt. Bezüglich der Eingabecodierung wird von UTF-8
  und einer \LaTeX-Version ab 2018-04-01 ausgegangen. Als Schrift
  wird Latin Modern in 8-Bit-Codierung verwendet.\iffree{ Für die
    Farbeinstellungen wird das Paket \Package{xcolor}\IndexPackage{xcolor}
    genutzt.}{}

  Bezüglich des Setzens von Gesetzestexten\textnote{Gesetz mit
    \hyperref[cha:scrjura]{\Package{scrjura}}} mit
  \hyperref[cha:scrjura]{\Package{scrjura}}\IndexPackage{scrjura} sei auf
  \iffree{dessen Anleitung}{\autoref{cha:scrjura}} verwiesen.

  Da ein Seitenstil\textnote{Seitenstil mit
    \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}} mit
  Seitenzahl verwendet werden soll, wird das Paket
  \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}%
  \IndexPackage{scrlayer-scrpage} geladen. Somit können Notizspalten auf allen
  Seiten ausgegeben werden.

  Dann wird das Paket \Package{scrlayer-notecolumn}\textnote{Notizspalte mit
    \Package{scrlayer-notecolumn}} für die Notizspalten geladen. Die
  gewünschte Breite der Notizspalte wird über
  \DescRef{typearea-experts.cmd.AfterCalculatingTypearea}%
  \IndexPackage{typearea}%
  \IndexCmd{AfterCalculatingTypearea} nach jeder etwaigen Neuberechnung des
  Satzspiegels\textnote{Satzspiegel mit
    \hyperref[cha:typearea]{\Package{typearea}}}%
  \IndexPackage{typearea} neu berechnet. Sie soll jeweils ein Drittel der
  Satzspiegelbreite betragen, wobei der Abstand zwischen Text und Notizspalte
  zu Lasten der Notizspalte geht. %
  \iftrue% Umbruchoptimierung
  Diese ist also effektiv um \Length{marginparsep}\IndexLength{marginparsep}
  schmaler.%
  \fi

  Mit dieser Information kann dann die neue Notizspalte definiert werden. Bei
  der Festlegung der Position wird ein einfacher Längenausdruck genutzt. Dabei
  ist zu beachten, dass \Length{oddsidemargin} nicht der gesamte linke Rand
  ist, sondern aus historischen Gründen der linke Rand abzüglich
  1\Unit{inch}. Daher muss dieser Wert noch hinzugezählt werden.

  Damit ist die Deklaration abgeschlossen. Es ist zu beachten, dass die
  Notizspalte bisher im Textbereich ausgegeben wird. Die Notizspalte würde
  also den Text überschreiben.

\begin{lstcode}
  \begin{document}

  \title{Kommentar zum GüdaVaS}
  \author{Professor R. O. Tenase}
  \date{11.\,11.~2011}
  \maketitle
  \tableofcontents

  \section{Vormerkung}
  Das GüdaVaS ist ohne jeden Zweifel das wichtigste
  Gesetz, das in Spaßmanien in den letzten eintausend
  Jahren verabschiedet wurde. Die erste Lesung fand
  bereits am 11.\,11.~1111 im obersten spaßmanischen
  Kongress statt, wurde aber vom damaligen Spaßvesier
  abgelehnt. Erst nach Umwandlung der spaßmanischen,
  aberwitzigen Monarchie in eine repräsentative,
  witzige Monarchie durch W. Itzbold, 
  den Urkomischen, am 9.\,9.~1999 war der Weg für 
  dieses Gesetz endlich frei.
\end{lstcode}
Dadurch,\textnote{Achtung!} dass der Textbereich nicht verkleinert wurde, wird
hier der ganze Vorspann über die Gesamtbreite ausgegeben. Um das Beispiel zu
testen, können Sie vorübergehend
\begin{lstcode}
  \end{document}
\end{lstcode}
  ergänzen.
\end{Example}
%
Offen blieb in dem Beispiel die Frage, wie der Text für den Kommentar schmaler
gesetzt werden kann. Dies werden Sie bei der Fortsetzung des Beispiels
erfahren.%
\EndIndexGroup


\section{Erstellen einer Notiz}
\seclabel{makenote}

Nachdem eine Notizspalte deklariert wurde, können Notizen für diese Spalte
erstellt werden. Diese Notizen werden allerdings nicht unmittelbar ausgegeben,
sondern zunächst nur in eine Hilfsdatei mit Endung »\File{.slnc}«
geschrieben. Ganz genau werden die Notizen sogar zunächst in die
\File{aux}-Datei geschrieben und erst beim Lesen der \File{aux}-Datei
innerhalb von \Macro{end}\PParameter{document} in die \File{slnc}-Datei
übertragen. Dabei wird gegebenenfalls auch die Einstellung
\Macro{nofiles}\IndexCmd{nofiles} beachtet.  Beim nächsten \LaTeX-Lauf wird
diese Hilfsdatei dann Stück für Stück je nach Fortschritt des Dokuments wieder
eingelesen und am Ende der Seite werden die Notizen für die jeweilige Seite
ausgegeben.

Es ist jedoch zu beachten\textnote{Achtung!}, dass Notizspalten nur auf Seiten
ausgegeben werden, deren Seitenstil auf dem Paket
\hyperref[cha:scrlayer]{\Package{scrlayer}}\IndexPackage{scrlayer}%
\important{\hyperref[cha:scrlayer]{\Package{scrlayer}}} basiert. Das Paket
\hyperref[cha:scrlayer]{\Package{scrlayer}} wird von
\Package{scrlayer-notecolumn} automatisch geladen und stellt in der
Voreinstellung lediglich den Seitenstil
\PageStyle{empty}\IndexPagestyle{empty} bereit. Werden weitere Seitenstile
benötigt, wird zusätzlich das Paket
\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}%
\IndexPackage{scrlayer-scrpage}%
\important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}}
empfohlen.


\begin{Declaration}
  \Macro{makenote}\OParameter{Name der Notizspalte}\Parameter{Notiz}\\
  \Macro{makenote*}\OParameter{Name der Notizspalte}\Parameter{Notiz}
\end{Declaration}
Mit Hilfe dieser Anweisungen kann eine \PName{Notiz} erstellt werden. Dabei
wird die aktuelle vertikale Position als vertikale Position für den Anfang der
\PName{Notiz} verwendet. Die horizontale Position für die Notiz ergibt sich
aus der definierten Position der Notizspalte. Für die korrekte Funktion ist
das Paket dabei auf \Macro{pdfsavepos}\IndexCmd{pdfsavepos},
\Macro{pdflastypos}\IndexCmd{pdflastypos} und
\Macro{pdfpageheight}\IndexLength{pdfpageheight} beziehungsweise deren
Entsprechungen bei neueren \LuaTeX-Versionen angewiesen. Ohne diese Befehle
funktioniert \Package{scrlayer-notecolumn} nicht. %
\iffalse % Umbruchkorrektur
Dabei wird außerdem davon ausgegangen, dass die genannten Primitiven exakt
die Ergebnisse von PDF\TeX{} liefern.%
\fi

Wird allerdings bei der Ausgabe der \PName{Notiz} eine
Kollision\textnote{Kollisionsauf"|lösung} mit einer früheren Notiz in derselben
Notizspalte erkannt, so wird die \PName{Notiz} bis unter diese frühere Notiz
verschoben. Passt die \PName{Notiz} nicht mehr auf die
Seite\textnote{Seitenumbruch}\Index{Seiten>Umbruch}, so wird sie ganz oder
teilweise auf die nächste Seite umbrochen.

Für welche Notizspalte die \PName{Notiz} erstellt werden soll, wird über das
optionale Argument \PName{Name der Notizspalte} bestimmt. Ist kein optionales
Argument angegeben, so wird die vordefinierte Notizspalte \PValue{marginpar}
verwendet.%
\begin{Example}
  Fügen wir nun dem Beispiel aus dem vorherigen Abschnitt einen kommentierten
  Paragraphen hinzu, wobei der Paragraph selbst in der neu definierten
  Notizspalte gesetzt werden soll.
\begin{lstcode}
  \section{Analyse}
  \begin{addmargin}[0pt]{.333\textwidth}
    \makenote[paragraphs]{%
      \protect\begin{contract}
        \protect\Clause{%
          title={Kein Witz ohne Publikum}%
        }
        Ein Witz kann nur dort witzig sein, wo er 
        auf ein Publikum trifft.
      \protect\end{contract}%
    }
    Dies ist eine der zentralsten Aussagen des 
    Gesetzes. Sie ist derart elementar, dass es
    durchaus angebracht ist, sich vor der Weisheit 
    der Verfasser zu verbeugen.
\end{lstcode}
  Die in \autoref{sec:maincls.lists}, \DescPageRef{maincls.env.addmargin}
  dokumentierte Umgebung
  \DescRef{maincls.env.addmargin}\IndexEnv{addmargin}\textnote{Spaltenbreite
    mit \DescRef{maincls.env.addmargin}} wird genutzt, um den
  Haupttext in der Breite um die Spalte für die Paragraphen zu
  vermindern.

  Hier ist auch eines der wenigen Probleme bei Verwendung von \Macro{makenote}
  zu erkennen. Da das obligatorische Argument in Dateien geschrieben wird,
  können Befehle\textnote{zerbrechliche Befehle} innerhalb des Arguments
  leider \emph{zerbrechen}. Um das zu verhindern, wird empfohlen, vor alle
  Befehle ein \Macro{protect} zu setzen. Anderenfalls kann die Verwendung von
  Befehlen innerhalb dieses Arguments zu Fehlermeldungen führen.

  Prinzipiell könnten Sie das Beispiel nun bereits mit
\begin{lstcode}
  \end{addmargin}
  \end{document}
\end{lstcode}
  beenden, wenn Sie ein Ergebnis sehen wollen.
\end{Example}%

Beim Testen des Beispiels, werden Sie feststellen, dass die Gesetzes\-spalte
tiefer hinunter reicht als der Kommentartext. Wenn\textnote{Achtung!} Sie
zwecks Übung einen weiteren Abschnitt mit einem weiteren Paragraphen
hinzufügen, ergibt sich eventuell das Problem, dass der Kommentar nicht
unterhalb des Gesetzestextes, sondern direkt im Anschluss an den bisherigen
Kommentar fortgesetzt wird. Eine Lösung für dieses Problem werden Sie gleich
kennenlernen.

Das\ChangedAt{v0.1.2583}{\Package{scrlayer-notecolumn}} im Beispiel erwähnte
Problem mit dem Zerbrechen von Befehlen tritt bei der
Sternvariante\important{\Macro{makenote*}} normalerweise nicht auf. Diese
verwendet \Macro{detokenize}, um die Expansion zu verhindern. Das bedeutet
aber auch, dass man in der \PName{Notiz} keine Befehle verwenden sollte, die
ihre Bedeutung innerhalb des Dokuments verändern.

Allerdings treten bei beiden Formen zwei andere Probleme\textnote{Achtung!}
auf. Das erste betrifft die Verwendung von Farbe mit Hilfe von
\Package{color}\IndexPackage{color} oder \Package{xcolor}\IndexPackage{xcolor}
innerhalb der Notizspalten. Um Farbumschaltungen innerhalb der Notizspalten zu
ermöglichen, wäre für jede Notizspalte eine eigene Farbverwaltung mit einem
sogenannten \emph{Color Stack} notwendig. Da das Paket lediglich als
Machbarkeitsstudie entworfen ist und \XeTeX{} nicht mehrere \emph{Color
  Stacks} unterstützt, sind mit \XeTeX{} Farbumschaltungen nur eingeschränkt
über die Schriftattribute des Elements \FontElement{notecolumn.\PName{Name der
    Notizspalte}} möglich, wodurch der Aufwand für die Implementierung einer
eigenen Farbverwaltung umgangen wurde.

Das zweite, eher konzeptionelle Problem\textnote{Achtung!} ist, dass die
Hilfsdatei mit den Informationen zum Inhalt der Notizspalte während der
Verarbeitung der Kopfzeile einer Seite eingelesen wird. Das hat vor allem dann
Auswirkungen, wenn dies geschieht, während eine Umgebung wie
\Environment{verbatim} aktiv ist. In diesem Fall wären während des Einlesens
der Hilfsdatei die \Macro{catcode}-Einstellungen dieser Umgebung aktiv. Das
würde zwangsläufig zu Fehlern in der Verarbeitung und Ausgabe führen. Um dies
abzumildern, werden während \Macro{begin}\PParameter{document} die
\Macro{catcode}-Einstellungen der in \Macro{dospecials}\IndexCmd{dospecials}
gespeicherten Zeichen gespeichert und während dem Einlesen der Hilfsdatei
explizit wiederhergestellt.%
\EndIndexGroup


\begin{Declaration}
  \Macro{syncwithnotecolumn}\OParameter{Name der Notizspalte}
\end{Declaration}
Mit Hilfe dieser Anweisung wird in einer Notizspalte und im Haupttext des
Dokuments je ein
Synchronisierungspunkt\textnote{Synchronisation}\Index{Synchronisation}
erstellt. Wann immer bei der Ausgabe einer Notizspalte oder des Haupttextes
ein solcher Synchronisierungspunkt erreicht wird, wird eine Marke angelegt,
deren Inhalt die aktuelle Seite und die aktuelle vertikale Position ist.

Parallel zum Erstellen der Synchronisierungspunkte wird ermittelt, ob in
der Notizspalte und im Haupttext beim letzten \LaTeX-Lauf eine Marke angelegt
wurde. Falls das der Fall ist, werden deren Werte miteinander
verglichen. Liegt die Marke der Notizspalte tiefer auf der Seite oder auf
einer späteren Seite, so wird im Haupttext bis zu der Stelle der Notizspalte
vorgerückt.

In der Regel sollten Synchronisierungspunkte\textnote{Hinweis!} nicht
innerhalb eines Absatzes des Haupttextes, sondern nur zwischen diesen gesetzt
werden. Wird \Macro{syncwithnotecolumn} dennoch innerhalb eines Absatzes
verwendet, so wird der Synchronisierungspunkt im Haupttext tatsächlich erst
nach der aktuellen Zeile eingefügt. In dieser Hinsicht ähnelt
\Macro{syncwithnotecolumn} also beispielsweise
\Macro{vspace}\IndexCmd{vspace}.

Dadurch, dass Synchronisierungspunkte in den Notizspalten erst beim nächsten
\LaTeX-Lauf\textnote{mehrere \LaTeX-Läufe} erkannt werden, benötigt der
Mechanismus mindestens drei \LaTeX-Läufe. Aus jeder neuen Synchronisierung
können sich außerdem Verschiebungen für spätere Synchronisierungspunkte
ergeben, was wiederum die Notwendigkeit weiterer \LaTeX-Läufe nach sich
zieht. Zu erkennen sind solche Verschiebungen in der Regel an der Meldung:
»\LaTeX{} Warning: Label(s) may have changed. Rerun to get cross-references
right.« Aber auch Meldungen über undefinierte \emph{Labels} können auf die
Notwendigkeit eines weiteren \LaTeX-Laufs hinweisen.

Wird das optionale Argument nicht angegeben, so wird an seiner Stelle
\PValue{marginpar}, also die vordefinierte Notizspalte
verwendet. Es\textnote{Achtung!} sei an dieser Stelle darauf hingewiesen, dass
ein leeres optionales Argument nicht gleichbedeutend mit dem Weglassen eines
optionalen Arguments ist!

Es ist nicht\textnote{Achtung!} erlaubt, \Macro{syncwithnotecolumn} innerhalb
einer Notiz selbst, also im obligatorischen Argument von
\Macro{makenote}\IndexCmd{makenote} zu verwenden! Dieser Fehler kann derzeit
nicht abgefangen werden und führt dazu, dass mit jedem \LaTeX-Lauf neue
Verschiebungen auf"|treten, so dass nie ein endgültiger Zustand erreicht
wird. Um zwei oder mehrere Notizspalten miteinander zu synchronisieren, sind
sie stattdessen mit dem Haupttext zu synchronisieren, da dabei auch die
Spalten miteinander synchronisiert werden. Die hierzu empfohlene Anweisung
wird nachfolgend beschrieben.%
%
\begin{Example}
  Führen wir nun das obige Beispiel fort, indem wir zunächst einen
  Synchronisationspunkt und dann einen weiteren Paragraphen
  mit Kommentar hinzufügen:
\begin{lstcode}
    \syncwithnotecolumn[paragraphs]\bigskip
    \makenote[paragraphs]{%
      \protect\begin{contract}
        \protect\Clause{title={Komik der Kultur}}
        \setcounter{par}{0}%
        Die Komik eines Witzes kann durch das 
        kulturelle Umfeld, in dem er erzählt wird,
        bestimmt sein.

        Die Komik eines Witzes kann durch das 
        kulturelle Umfeld, in dem er spielt, 
        bestimmt sein.
      \protect\end{contract}
    }
    Die kulturelle Komponente eines Witzes ist 
    tatsächlich nicht zu vernachlässigen. Über die
    politische Korrektheit der Nutzung des
    kulturellen Umfeldes kann zwar treff"|lich 
    gestritten werden, nichtsdestotrotz ist die 
    Treffsicherheit einer solchen Komik im
    entsprechenden Umfeld frappierend. Auf der 
    anderen Seite kann ein vermeintlicher Witz im
    falschen kulturellen Umfeld auch zu einer 
    echten Gefahr für den Witzeerzähler werden.
\end{lstcode}
  Außer dem Synchronisationspunkt wurde hier auch noch ein vertikaler
  Abstand mit \Macro{bigskip} eingefügt, um die einzelnen Paragraphen und ihre
  Kommentare besser voneinander abzusetzen.

  Außerdem\textnote{Achtung!} wird hier ein weiterer Punkt, der zu einem
  Problem werden kann, sichtbar. Da die Notizspalten mit Boxen arbeiten, die
  zusammengebaut und zerlegt werden, kann es bei Zählern\textnote{Zähler in
    Notizspalten} innerhalb der Notizspalten teilweise zu Verschiebungen
  kommen. Im Beispiel würde daher der erste Absatz nicht mit 1, sondern mit 2
  nummeriert. Dies kann jedoch mit einem beherzten Zurücksetzen des
  entsprechenden Zählers leicht korrigiert werden.

  Das Beispiel ist damit fast fertig, was noch fehlt, ist das Ende der
  Umgebungen:
\begin{lstcode}
  \end{addmargin}
  \end{document}
\end{lstcode}
  Tatsächlich wären natürlich auch noch die restlichen Paragraphen des
  Gesetzes zu kommentieren. Dies sei mir hier jedoch erlassen.
\end{Example}%
Doch halt! Was wäre, wenn in diesem Beispiel der Paragraph nicht mehr auf die
Seiten passen würde? Würde er dann auf der nächsten Seite ausgegeben? Diese
Frage wird im nächsten Abschnitt beantwortet werden.
\EndIndexGroup


\begin{Declaration}
  \Macro{syncwithnotecolumns}\OParameter{Liste von Notizspalte}
\end{Declaration}
Diese Anweisung führt eine Synchronisierung des Haupttextes mit allen in der
mit Komma separierten \PName{Liste von Notizspalten} angegebenen Notitzspalten
durch. Dabei wird der Haupttext mit der Notizspalte synchronisiert, deren
Marke am weitesten hinten im Dokument steht. Somit werden als Nebeneffekt auch
die Notizspalten untereinander synchronisiert.

Wird das optionale Argument nicht angegeben oder ist es leer, so wird mit
allen deklarierten Notizspalten synchronisiert.%
\EndIndexGroup


\section{Erzwungene Ausgabe von Notizspalten}
\seclabel{clearnotes}

\iftrue % Umbruchkorrektur
Im vorherigen Abschnitt wurde dokumentiert, wie die Ausgabe der Notitzspalten
normalerweise erfolgt. Manchmal ist es aber %
\else%
Neben der normalen Ausgabe der Notizspalten, wie sie im vorherigen Abschnitt
beschrieben ist, ist es manchmal %
\fi %
auch erforderlich, alle aufgesammelten Notizen, die noch nicht ausgegeben
wurden, unmittelbar auszugeben. Das ist insbesondere dann sinnvoll, wenn
längere Notizen dazu führen, dass immer mehr Notizen nach unten und auf neue
Seiten verschoben werden. Ein guter Zeitpunkt für eine solche erzwungene
Ausgabe\Index{Ausgabe>erzwungene} ist beispielsweise das Ende eines Kapitels
oder das Ende des Dokuments.

\begin{Declaration}
  \Macro{clearnotecolumn}\OParameter{Name der Notizspalte}
\end{Declaration}
Mit dieser Anweisung werden alle Notizen einer bestimmen Notizspalte
ausgegeben, die\textnote{anhängige Notizen}\Index{Notiz>anhaengige=anhängige}
bis zum Ende der aktuellen Seite noch nicht ausgegeben sind, aber auf dieser
oder einer vorherigen Seite erstellt wurden. Zur Ausgabe dieser noch
anhängigen Notizen werden nach Bedarf Leerseiten erstellt. Während der Ausgabe
der anhängigen Notizen dieser Notizspalte werden gegebenenfalls auch anhängige
Notizen anderer Notizspalten ausgegeben, jedoch nur so lange, wie dies zur
Ausgabe der anhängigen Notizen der angegebenen Notizspalte notwendig ist.

Während der Ausgabe der anhängigen Notizen kann es auch geschehen, dass
irrtümlich Notizen\textnote{irrtümliche
  Notizen}\Index{Notiz>irrtuemliche=irrtümliche} ausgegeben werden, die im
vorherigen \LaTeX-Lauf auf den Seiten erstellt wurden, die nun durch die
eingefügten Leerseiten ersetzt werden. Dies normalisiert sich in einem der
nächsten \LaTeX-Läufe. Zu erkennen sind solche Verschiebungen in der Regel an
der Meldung: »\LaTeX{} Warning: Label(s) may have changed. Rerun to get
cross-references right.«

Die Notizspalte, deren anhängige Notizen ausgegeben werden soll, ist über das
optionale Argument \PName{Name der Notizspalte} angegeben. Ist kein solches
Argument angegeben, so wird die vordefinierte Notizspalte \PValue{marginpar}
verwendet.

Dem aufmerksamen Leser wird nicht entgangen sein, dass die
erzwungene\textnote{erzwungene Ausgabe vs. Synchronisation} Ausgabe einer
Notizspalte der Synchronisierung nicht unähnlich ist. Allerdings befindet man
sich nach der erzwungenen Ausgabe im Fall, dass tatsächlich eine Ausgabe
stattfindet, am Anfang der Seite nach der letzten Ausgabe und nicht
unmittelbar unterhalb der letzten Ausgabe. Dafür terminiert die erzwungene
Ausgabe in der Regel mit weniger \LaTeX-Läufen.%
\EndIndexGroup


\begin{Declaration}
  \Macro{clearnotecolumns}\OParameter{Liste von Notizspalten-Namen}
\end{Declaration}
Diese Anweisung arbeitet vergleichbar mit
\DescRef{\LabelBase.cmd.clearnotecolumn}. Allerdings kann hier als optionales
Argument nicht nur eine Notizspalte angegeben werden, sondern es ist eine
durch Komma getrennte Liste mehrerer Namen von Notizspalten erlaubt. Es werden
dann die anhängigen Notizen all dieser Spalten ausgegeben.

Wurde das optionale Argument nicht angegeben oder ist es leer, so werden die
anhängigen Notizen aller Notizspalten ausgegeben.%
\EndIndexGroup


\begin{Declaration}
  \OptionVName{autoclearnotecolumns}{Ein-Aus-Wert}
\end{Declaration}
In der Regel wird man anhängige Notizen immer dann ausgeben lassen, wenn im
Dokument explizit oder implizit -- beispielsweise in Folge von
\DescRef{maincls.cmd.chapter} -- die Anweisung \DescRef{maincls.cmd.clearpage}
ausgeführt wird. Dies ist auch am Ende eines Dokuments innerhalb von
\Macro{end}\PParameter{document} der Fall. Über die Option
\Option{autoclearnotecolumns} kann daher gesteuert werden, ob bei Ausführung
von \DescRef{maincls.cmd.clearpage} automatisch auch
\DescRef{\LabelBase.cmd.clearnotecolumns} ohne Argument ausgeführt werden
soll. Da davon ausgegangen wird, dass dies in der Regel erwünscht ist, ist die
Option in der Voreinstellung aktiv. Man kann sie jedoch über die
entsprechenden Werte für einfache Schalter (siehe
\autoref{tab:truefalseswitch} auf \autopageref{tab:truefalseswitch}) jederzeit
aus- und auch wieder einschalten.

Es ist zu beachten\textnote{Achtung!}, dass im Falle der Deaktivierung der
automatischen Ausgabe anhängiger Notizen am Ende des Dokuments Notizen ganz
oder teilweise verloren gehen können. Daher sollte man in diesem Fall vor
\Macro{end}\PParameter{document} sicherheitshalber ein
\DescRef{\LabelBase.cmd.clearnotecolumns} einfügen.

Damit ist nun auch die Frage nach dem Beispiel im letzten Abschnitt
beantwortet, ob der Paragraph auch komplett ausgegeben würde, wenn er auf die
nächste Seite umbrochen werden müsste. Dies ist in der Voreinstellung
selbstverständlich der Fall. Da es jedoch nach dem Ende der
\DescRef{maincls.env.addmargin}-Umgebung geschehen würde, könnte es eventuell
noch zu Überlappungen durch nachfolgenden Text kommen. Daher wäre es im
Beispiel durchaus sinnvoll, nach der \DescRef{maincls.env.addmargin}-Umgebung
einen weiteren Synchronisationspunkt einzufügen.

Das Ergebnis des Beispiels ist übrigens in
\autoref{fig:scrlayer-notecolumn.example} zu sehen.\iffree{}{ Dabei wurde
  lediglich die Farbeinstellung für die \PValue{paragraphs}-Spalte von Blau in
  Grau geändert.}

\begin{figure}
  \KOMAoptions{captions=bottombeside}%
  \setcapindent{0pt}%
  \begin{captionbeside}[{Eine Ergebnisseite zu dem Beispiel aus dem Kapitel}]%
    {Eine Ergebnisseite zu dem Beispiel aus diesem
      Kapitel\label{fig:scrlayer-notecolumn.example}}[l]
  \frame{\includegraphics[width=.667\textwidth,keepaspectratio]%
    {scrlayer-notecolumn-example-de}}
  \end{captionbeside}
\end{figure}
\EndIndexGroup
%
\EndIndexGroup

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "scrguide-de.tex"
%%% coding: utf-8
%%% ispell-local-dictionary: "de_DE"
%%% eval: (flyspell-mode 1)
%%% End:

%  LocalWords:  Randnotizen Entwicklungsstadium Notizspalte Notizspalten
%  LocalWords:  Neukonfigurierung Synchronisierungspunkt marginpar marginline
%  LocalWords:  Haupttext Demonstrationszwecken Längenausdruck Gesetzestexten
%  LocalWords:  Längenausdrücken Satzspiegels typearea scrlayer notecolumn
%  LocalWords:  AfterCalculatingTypearea scrjura scrpage Farbeinstellung
%  LocalWords:  Sternvariante
