summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/koma-script/doc/scrlayer-notecolumn-en.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/koma-script/doc/scrlayer-notecolumn-en.tex')
-rw-r--r--macros/latex/contrib/koma-script/doc/scrlayer-notecolumn-en.tex700
1 files changed, 700 insertions, 0 deletions
diff --git a/macros/latex/contrib/koma-script/doc/scrlayer-notecolumn-en.tex b/macros/latex/contrib/koma-script/doc/scrlayer-notecolumn-en.tex
new file mode 100644
index 0000000000..5e502c9823
--- /dev/null
+++ b/macros/latex/contrib/koma-script/doc/scrlayer-notecolumn-en.tex
@@ -0,0 +1,700 @@
+% ======================================================================
+% scrlayer-notecolumn-en.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
+%
+% ============================================================================
+
+\KOMAProvidesFile{scrlayer-notecolumn-en.tex}
+ [$Date: 2018-02-05 01:50:56 -0800 (Mon, 05 Feb 2018) $
+ KOMA-Script guide (chapter:scrlayer-notecolumn)]
+
+\translator{Markus Kohm\and Arndt Schubert\and Karl Hagen}
+
+\chapter{Note Columns with \Package{scrlayer-notecolumn}}
+\labelbase{scrlayer-notecolumn}
+
+\BeginIndexGroup
+\BeginIndex{Package}{scrlayer-notecolumn}%
+Through version~3.11b, \KOMAScript{} supported note columns only in the form
+of marginal notes that get their contents from \DescRef{maincls.cmd.marginpar}
+and \DescRef{maincls.cmd.marginline} (see \autoref{sec:maincls.marginNotes},
+\DescPageRef{maincls.cmd.marginline}). This kind of note column has several
+disadvantages:
+\begin{itemize}
+\item Marginal notes must be set completely on a single page. Page
+ breaks\textnote{page break} inside marginal notes are not possible. This
+ sometimes causes the marginal notes to protrude into the lower margin.
+\item Marginal notes near page breaks sometimes float to the next page and
+ then, in the case of two-sided printing, cause alternate marginal columns to
+ appear in the wrong margin.\textnote{assignment to the correct margin}. This
+ problem can be solved with the additional package
+ \Package{mparhack}\IndexPackage{mparhack} or by using \Macro{marginnote}
+ from the \Package{marginnote}\IndexPackage{marginnote} package (see
+ \cite{package:marginnote}).
+\item Marginal notes inside floating environments\textnote{floating
+ environments} or footnotes\textnote{footnotes} are not possible. This
+ problem can also be solved with \Macro{marginnote} of the
+ \Package{marginnote}\IndexPackage{marginnote} package.
+\item There is only one marginal note column\textnote{several note columns},
+ or at most two if you use \Macro{reversemarginpar} and
+ \Macro{normalmarginpar}. Note that \Macro{reversemarginpar} is of less
+ utility with two-sided documents.
+\end{itemize}
+Using \Package{marginnote}\IndexPackage{marginnote} leads to one more problem.
+Because the package does not have any collision detection, marginal notes that
+are set near to each other can partially or totally overlap. Moreover,
+depending on the settings used, \Macro{marginnote} sometimes changes the
+baseline distance of the normal text.
+
+The \Package{scrlayer-notecolumn} package should solve all these problems. To
+do so, it relies on the basic functionality of
+\hyperref[cha:scrlayer]{\Package{scrlayer}}\IndexPackage{scrlayer}%
+\important{\hyperref[cha:scrlayer]{\Package{scrlayer}}}. However, using this
+package has a drawback:\textnote{Attention!} you can only output notes on
+pages that use a page style based on
+\hyperref[cha:scrlayer]{\Package{scrlayer}}. This disadvantage, however, can
+easily be resolved, or even turned into an advantage, with the help of
+\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}%
+\important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}}%
+\IndexPackage{scrlayer-scrpage}.
+
+\section{Note about the State of Development}
+\seclabel{draft}
+
+This package was originally developed as a so-called \emph{proof of
+ concept}\textnote{proof of concept} to demonstrate the potential of
+\hyperref[cha:scrlayer]{\Package{scrlayer}}%
+\important{\hyperref[cha:scrlayer]{\Package{scrlayer}}}. Although it is still
+in its early stages of development, most of its stability is less a question
+of \Package{scrlayer-notecolumn} than of
+\hyperref[cha:scrlayer]{\Package{scrlayer}}. Nevertheless, you can assume that
+there are still bugs in \Package{scrlayer-notecolumn}. Please report such bugs
+whenever you find them. Some of the package's shortcomings are caused by the
+attempt to minimise complexity. For example, although note columns can break
+across several pages, there is no new paragraph break. \TeX{} itself does not
+provide this.
+
+Because the package is rather experimental\textnote{experimental}, its
+instructions are found here in the second part of \iffree{the \KOMAScript{}
+manual}{this book}. Accordingly, it is primarily directed towards experienced
+users. If you are a beginner or a user on the way to become an
+expert\textnote{for experts}, some of the following explanations may be
+unclear or even incomprehensible.
+\iffree{Please understand that I want to keep the effort spent on the manual
+ to something halfway bearable when it comes to experimental packages.}{%
+ However, this should be enough to solve simple tasks with
+ \Package{scrlayer-notecolumn}. At the same time, developers will hopefully
+ find useful stimulus for their own ideas.}
+
+\iffalse% Umbruchoptimierung
+Note also\textnote{Attention!} that the author of \KOMAScript{} does not
+guarantee the further development of this package and offers only limited
+support for it. This is the nature of a package written solely for the
+purposes of demonstration.%
+\fi
+
+\LoadCommonFile{options}% \section{Early or late Selection of Options}
+
+\LoadCommonFile{textmarkup}% \section{Text Markup}
+
+\section{Declaring New Note Columns}
+\seclabel{declaration}
+
+Loading the package automatically declares a note column named
+\PValue{marginpar}. As the name implies, this note column is placed in the
+area of the normal marginal column used by \DescRef{maincls.cmd.marginpar} and
+\DescRef{maincls.cmd.marginline}. The \Macro{reversemarginpar} and
+\Macro{normalmarginpar} settings are also taken into account, but only for all
+the notes on a page instead of note by note. The relevant setting is the one
+that applies at the end of the page, namely during the output of the note
+column. If you want to have notes in both the left and right margin of the
+same page, you should define a second note column.
+
+The default settings for all newly declared note columns are the same as the
+defaults for \PValue{marginpar}. %
+\iftrue% Umbruchoptimierung
+But you can easily change them during their initialisation.%
+\fi
+
+Note\textnote{Attention!} that note columns can be output only on pages that
+use a page style based on the
+\hyperref[cha:scrlayer]{\Package{scrlayer}}\IndexPackage{scrlayer}%
+\important{\hyperref[cha:scrlayer]{\Package{scrlayer}}} package. The
+\Package{scrlayer-notecolumn} package automatically loads
+\hyperref[cha:scrlayer]{\Package{scrlayer}}, which by default provides only
+\PageStyle{empty}\IndexPagestyle{empty} page style. If you need additional
+page styles, \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}%
+\IndexPackage{scrlayer-scrpage}%
+\important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}} is
+recommended.
+
+\begin{Declaration}
+ \Macro{DeclareNoteColumn}%
+ \OParameter{option~list}\Parameter{note~column~name}%
+ \Macro{DeclareNewNoteColumn}%
+ \OParameter{option~list}\Parameter{note~column~name}%
+ \Macro{ProvideNoteColumn}%
+ \OParameter{option~list}\Parameter{note~column~name}%
+ \Macro{RedeclareNoteColumn}%
+ \OParameter{option~list}\Parameter{note~column~name}%
+\end{Declaration}
+You can use these commands to create note columns. \Macro{DeclareNoteColumn}
+creates the note column regardless of whether it already exists.
+\Macro{DeclareNewNoteColumn} throws an error if the \PName{note column name}
+has already been used for another note column. \Macro{ProvideNoteColumn}
+simply does nothing in that case. You can use \Macro{RedeclareNoteColumn} only
+to reconfigure an existing note column.
+
+By the way, when reconfiguring existing note columns with
+\Macro{DeclareNoteColumn} or \Macro{RedeclareNoteColumn}, the notes that have
+already been generated for this column are retained.
+
+\BeginIndex{FontElement}{notecolumn.\PName{note column name}}%
+\BeginIndex{FontElement}{notecolumn.marginpar}%
+Declaring a new note column always defines a new element for changing its font
+attributes with \DescRef{\LabelBase.cmd.setkomafont} and
+\DescRef{\LabelBase.cmd.addtokomafont}, if such an element does not yet exist.
+The name of the element is \PValue{notecolumn.}\PName{note column name}. For
+this reason, the default note column \PValue{marginnote} has the
+element\textnote{element name} \FontElement{notecolumn.marginpar}. You can
+directly specify the initial setting of the element's font when declaring a
+note column by using the \Option{font} option within the \PName{option list}.%
+\EndIndex{FontElement}{notecolumn.marginpar}%
+\EndIndex{FontElement}{notecolumn.\PName{note column name}}%
+
+The \PName{option list} is a comma-separated list of keys with or without
+values, also known as options. The available options are listed in
+\autoref{tab:scrlayer-notecolumn.note.column.options},
+\autopageref{tab:scrlayer-notecolumn.note.column.options}.
+The\textnote{default: option \Option{marginpar}} \Option{marginpar} option is
+set by default, but you can overwrite this default with your individual
+settings.
+
+Because note columns are implemented using \Package{scrlayer}, a
+layer\Index{layer} is created for each note column. The layer
+name\textnote{layer name} is the same as the name of the element,
+\PValue{notecolumn.}\PName{note column name}. For more information about
+layers see \autoref{sec:scrlayer.layers}, starting on
+\autopageref{sec:scrlayer.layers}.
+%
+\begin{Example}
+ Suppose you are a professor of comedy law and want to write a treatise on
+ the new ``Statute Concerning the Riotous Airing of Common Humour'', SCRACH
+ for short. The better part of the work will consist of commentary on
+ individual paragraphs of the statute. You decide on a two-column layout,
+ with the comments in the main column and the paragraphs placed in a smaller
+ note column on the right of the main column using a font that is
+ smaller\iffree{ and in a different colour}{}.
+\begin{lstcode}
+ \documentclass{scrartcl}
+ \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}
+ The treatise should be a one-sided article. The font is Latin Modern, and
+ the colour selection uses the \Package{xcolor}\IndexPackage{xcolor} package.
+
+ For formatting legal texts\textnote{legal texts with
+ \hyperref[cha:scrjura]{\Package{scrjura}}} with the
+ \hyperref[cha:scrjura]{\Package{scrjura}}\IndexPackage{scrjura} package, see
+ \autoref{cha:scrjura}.
+
+ Since this document uses a page style\textnote{page style with
+ \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}} with a
+ page number, the
+ \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}%
+ \IndexPackage{scrlayer-scrpage} package is loaded. Thus, note columns can be
+ output on all pages.
+
+ Next, the \Package{scrlayer-notecolumn}\textnote{note columns with
+ \Package{scrlayer-notecolumn}} package is loaded. The required width of the
+ note column is calculated with
+ \DescRef{typearea-experts.cmd.AfterCalculatingTypearea}%
+ \IndexPackage{typearea}\IndexCmd{AfterCalculatingTypearea} after any
+ recalculation\textnote{type area with
+ \hyperref[cha:typearea]{\Package{typearea}}}%
+ \IndexPackage{typearea} of the type area. It should be one third of the type
+ area minus the distance between the main text and the note column. %
+
+ With this information, we define the new note column. For the positions, we
+ use a simple dimension expression. Note that \Length{oddsidemargin} is not
+ the total left margin but for historical reasons the left margin minus
+ 1\Unit{inch}. So we have to add this value.
+
+ This concludes the definition. Note that the note column would currently be
+ placed inside the type area. This means that the note column would overwrite
+ the text.
+
+\begin{lstcode}
+ \begin{document}
+
+ \title{Commentary on the SCRACH}
+ \author{Professor R. O. Tenase}
+ \date{11/11/2011}
+ \maketitle
+ \tableofcontents
+
+ \section{Preamble}
+ The SCRACH is without doubt the most important law
+ on the manners of humour that has been passed in
+ the last thousand years. The first reading took
+ place on 11/11/1111 in the Supreme Manic Fun
+ Congress, but the law was rejected by the Vizier
+ of Fun. Only after the ludicrous, Manic Fun
+ monarchy was transformed into a representative,
+ witty monarchy by W. Itzbold, on 9/9/1999 was
+ the way finally clear for this law.
+\end{lstcode}
+ Because\textnote{Attention!} the text area was not reduced, the preamble is
+ output extending over the whole width of the type area. To test this, you
+ can temporarily add:
+\begin{lstcode}
+ \end{document}
+\end{lstcode}
+\end{Example}
+%
+In the example, the question of how the text for the commentary can be set in
+a narrower column remains unresolved. You will discover how to do this by
+continuing the example below.%
+%
+%\begin{table}% Umbruchoptimierung: Tabelle hinter das Beispiel verschoben
+\begin{desclist}
+ \desccaption{%
+% \caption[Available settings for declaring note columns]{%
+ Available settings for declaring note columns%
+% }%
+ \label{tab:scrlayer-notecolumn.note.column.options}%
+ }{%
+ Available settings for declaring note columns
+ (\emph{continued})%
+ }%
+% \begin{desctabular}
+ \entry{\OptionVName{font}{font attribute}}{%
+ The font attributes of the note column set with
+ \DescRef{\LabelBase.cmd.setkomafont}. For possible values, refer to
+ \autoref{sec:maincls.textmarkup},
+ \DescPageRef{maincls.cmd.setkomafont}.\par%
+ Default: \emph{empty}%
+ }%
+ \entry{\Option{marginpar}}{%
+ Sets \Option{position} and \Option{width} to correspond to the marginal
+ note column of \DescRef{maincls.cmd.marginpar}. Switching between
+ \Macro{reversemarginpar}\IndexCmd{reversemarginpar} and
+ \Macro{normalmarginpar}\IndexCmd{normalmarginpar} is only considered at
+ the end of the page when the note column is output. Note that this
+ option does not expect or allow any value.\par%
+ Default: \emph{yes}%
+ }%
+ \entry{\Option{normalmarginpar}}{%
+ Sets \Option{position} and \Option{width} to use the normal marginal
+ note column and ignore \Macro{reversemarginpar} and
+ \Macro{normalmarginpar}. Note that this option does not expect or allow
+ a value.\par%
+ Default: \emph{no}%
+ }%
+ \entry{\OptionVName{position}{offset}}{%
+ Sets the horizontal offset of the note column from the left edge of the
+ paper. The \PName{offset} can be a complex expression as long as it is
+ fully expandable and expands to a length or a dimensional expression at
+ the time the note column is output. See \cite[section~3.5]{manual:eTeX}
+ for more information about dimensional expressions.\par%
+ Default: \emph{through the \Option{marginpar} option}%
+ }%
+ \entry{\Option{reversemarginpar}}{%
+ Sets \Option{position} and \Option{width} to use the reverse marginal
+ note column of \DescRef{maincls.cmd.marginpar} with the
+ \Macro{reversemarginpar} setting. Note that this option does not expect
+ or allow a value.\par%
+ Default: \emph{no}%
+ }%
+ \entry{\OptionVName{width}{length}}{%
+ Sets the width of the note column. The \PName{length} can be a complex
+ expression as long as it is fully expandable and expands to a length or
+ a dimensional expression at the time the note column is output. See
+ \cite[section~3.5]{manual:eTeX} for more information about dimensional
+ expressions.\par%
+ Default: \emph{through the \Option{marginpar} option}%
+ }%
+% \end{desctabular}
+%\end{table}
+\end{desclist}
+\EndIndexGroup
+
+
+\section{Making a Note}
+\seclabel{makenote}
+
+After you declare a note column, you can create notes for this column. But
+these notes are not be output immediately. Initially, they are written to an
+auxiliary file with extension ``\File{.slnc}''. Specifically, they are first
+written to the \File{aux}-file and, when the \File{aux}-file is read inside
+\Macro{end}\PParameter{document}, they are copied to the \File{slnc}-file. If
+necessary, the \Macro{nofiles}\IndexCmd{nofiles} setting is also taken into
+account. At the next \LaTeX{} run, this auxiliary file will be read piece by
+piece, according to the progress of the document, and at the end of the page
+the notes for that page will be output.
+
+Note\textnote{Attention!}, however, that note columns are output only on pages
+whose page style is based on the \Package{scrlayer}\IndexPackage{scrlayer}
+package. This package is loaded automatically by \Package{scrlayer-notecolumn}
+and by default provides only the \PageStyle{empty}\IndexPagestyle{empty} page
+style. If you need additional page styles, the
+\Package{scrlayer-scrpage}\IndexPackage{scrlayer-scrpage} package is
+recommended.
+
+\begin{Declaration}
+ \Macro{makenote}\OParameter{note-column name}\Parameter{note}\\
+ \Macro{makenote*}\OParameter{note-column name}\Parameter{note}\\
+\end{Declaration}
+You can use this command to make a new \PName{note}. The current vertical
+position is used as the vertical position for the start of the \PName{note}.
+The horizontal position for the note results from the defined position of the
+note column. To work correctly, the package relies on
+\Macro{pdfsavepos}\IndexCmd{pdfsavepos},
+\Macro{pdflastypos}\IndexCmd{pdflastypos}, and
+\Macro{pdfpageheight}\IndexLength{pdfpageheight} or their equivalent in newer
+Lua\TeX{} versions. Without these commands, \Package{scrlayer-notecolumn} will
+not work. The primitives should act exactly as they would using pdf\TeX.
+
+However, if the package detects a collision\textnote{collision avoidance} with
+a previous \PName{note} in the same note column, the new \PName{note} is moved
+below that earlier \PName{note}. If the \PName{note} does not fit on the
+page\textnote{page break}\Index{page>break}, it will be moved completely or
+partially to the next page.
+
+The optional argument \PName{note column name} determines which note column
+should be used for the \PName{note}. If the optional argument is omitted, the
+default note column \PValue{marginpar} is used.%
+\begin{Example}
+ Let's add a commented paragraph to the example of the previous section. The
+ paragraph itself should be placed in the newly defined note column:
+\begin{lstcode}
+ \section{Analysis}
+ \begin{addmargin}[0pt]{.333\textwidth}
+ \makenote[paragraphs]{%
+ \protect\begin{contract}
+ \protect\Clause{%
+ title={No Joke without an Audience}%
+ }
+ A joke can only be funny if is has an
+ audience.
+ \protect\end{contract}%
+ }
+ This is one of the most central statements of
+ the law. It is so fundamental that it is quite
+ appropriate to bow to the wisdom of the authors.
+\end{lstcode}
+ The \DescRef{maincls.env.addmargin}\IndexEnv{addmargin}%
+ \textnote{column width with \DescRef{maincls.env.addmargin}} environment,
+ which is described in \autoref{sec:maincls.lists},
+ \DescPageRef{maincls.env.addmargin}, is used to reduce the width of the main
+ text by the width of the column for the paragraphs.
+
+ Here you can see one of the few problems of using \Macro{makenote}. Because
+ the mandatory argument is written to an auxiliary file,
+ commands\textnote{fragile commands} inside this argument can, unfortunately,
+ \emph{break}. To avoid this, you should use \Macro{protect} in front of all
+ commands that should not expand when written to the auxiliary file.
+ Otherwise, using a command inside this argument could result in error
+ messages.
+
+ In principle you could now finish this example with
+\begin{lstcode}
+ \end{addmargin}
+ \end{document}
+\end{lstcode}
+ to see a preliminary result.
+\end{Example}
+If you test this example, you will see that the column for the legal text is
+longer than that of the commentary. If\textnote{Attention!} you add another
+section with another paragraph, you may encounter the problem that the
+commentary will not continue below the legal text but immediately after the
+previous comment. Next you will find a solution to this problem.
+
+The\ChangedAt{v0.1.2583}{\Package{scrlayer-notecolumn}} problem with fragile
+commands mentioned in the example above does not occur with the starred
+variant\important{\Macro{makenote*}}. It uses \Macro{detokenize} to prevent
+the expansion of commands. But this also means that you should not use
+commands in the \PName{note} that change their definition within the
+document.
+
+Unfortunately, both commands have two other known
+limitations\textnote{Attention!}. The first issue is related to colours using
+\Package{color}\IndexPackage{color} or \Package{xcolor}\IndexPackage{xcolor}
+within the note columns. To make such colour changes possible each note column
+requires its own colour management using so-called \emph{colour stacks}.
+Because the package was designed only as a \emph{proof of concept} and because
+\XeTeX{} does not support multiple colour stacks, \XeTeX{} colour switching is
+restricted to the attributes of the font element
+\FontElement{notecolumn.\PName{note column name}}, a limitation which
+eliminates the time and effort required to implement custom colour management.
+
+The second issue is of a more conceptual nature. The content of the auxiliary
+file that contains the note-column information is read while processing the
+page header. This has consequences in particular if the read occurs while
+an environment like \Environment{verbatim} is active. In this case, the
+\Macro{catcode} settings of this environment would be active while reading the
+auxiliary file. This will inevitably lead to errors in processing and output.
+To attenuate this risk, the \Macro{catcodes} of the characters from
+\Macro{dospecials}\IndexCmd{dospecials} are stored during
+\Macro{begin}\PParameter{document} and explicitly restored when reading from
+the auxiliary file.%
+\EndIndexGroup
+
+
+\begin{Declaration}
+ \Macro{syncwithnotecolumn}\OParameter{note column name}
+\end{Declaration}
+This command adds a
+synchronisation\textnote{synchronisation}\Index{synchronisation} point in a
+note column and in the main text of the document. Whenever a synchronisation
+point is reached during the output of a note column or the main text, a mark
+will be generated that consists of the current page and the current vertical
+position.
+
+In parallel with the generation of synchronisation points,
+\Package{scrlayer-notecolumn} determines whether a mark has been set in the
+note column or the main text during the previous \LaTeX{} run. If so, it
+compares their values. If the mark of the note column is lower on the current
+page or on a later page, the main text will be moved down to the position of
+the mark.
+
+As a rule,\textnote{Hint!} you should not place synchronisation points within
+paragraphs of the main text but only between them. If you nonetheless use
+\Macro{syncwithnotecolumn} inside a paragraph, the synchronisation point will
+be delayed until the current line has been output. This behaviour is similar
+to that of, e.\,g., \Macro{vspace}\IndexCmd{vspace} in this respect.
+
+Because synchronisation points are not recognized until the next \LaTeX{}
+run\textnote{several \LaTeX{} runs}, this mechanism requires at least three
+\LaTeX{} runs. Any new synchronisation may also result in shifts of later
+synchronisation points, which in turn will require additional \LaTeX{} runs.
+Such shifts are usually indicated by the message: ``\LaTeX{} Warning: Label(s)
+may have changed. Rerun to get cross-references right.'' But reports about
+undefined labels may also indicate the need for another \LaTeX{} run.
+
+If you omit the optional argument, the default note column \PValue{marginpar}
+will be used. Note\textnote{Attention!} that an empty optional argument is not
+the same as omitting the optional argument!
+
+You cannot use\textnote{Attention!} \Macro{syncwithnotecolumn} inside a note
+itself, that is, inside the mandatory argument of
+\Macro{makenote}\IndexCmd{makenote}! Currently the package cannot recognise
+such a mistake, and it causes new shifts of the synchronisation point with
+each \LaTeX{} run, so the process will never terminate. To synchronise two or
+more note columns, you have to synchronise each of them with the main text.
+The recommended command for this is described below.%
+%
+\begin{Example}
+ Let's extend the example above by first adding a synchronisation point
+ and then another paragraph with a comment:
+\begin{lstcode}
+ \syncwithnotecolumn[paragraphs]\bigskip
+ \makenote[paragraphs]{%
+ \protect\begin{contract}
+ \protect\Clause{title={Humor of a Culture}}
+ \setcounter{par}{0}%
+ The humour of a joke can be determined by the
+ cultural environment in which it is told.
+
+ The humour of a joke can be determined by the
+ cultural environment in which it acts.
+ \protect\end{contract}
+ }
+ The cultural component of a joke is, in fact, not
+ negligible. Although the political correctness of
+ using the cultural environment can easily be
+ disputed, nonetheless the accuracy of such comedy
+ in the appropriate environment is striking. On
+ the other hand, a supposed joke in the wrong
+ cultural environment can also be a real danger
+ for the joke teller.
+\end{lstcode}
+ In addition to the synchronisation point, a vertical skip has been added
+ with \Macro{bigskip} to better distinguish each paragraph and the
+ corresponding comments.
+
+ Further\textnote{Attention}, this example illustrates another potential
+ problem. Because the note columns uses boxes that are assembled and
+ disassembled, counters\textnote{counter in note column} inside note columns
+ can sometimes jitter. In the example, therefore, the first paragraph would
+ be numbered 2 instead of 1. This, however, can easily be fixed by a direct
+ reset of the corresponding counter.
+
+ The example is almost complete. You just have to close the environments:
+\begin{lstcode}
+ \end{addmargin}
+ \end{document}
+\end{lstcode}
+ In reality, of course, all the remaining section of the law should also be
+ commented. But let us focus on the main purpose.
+\end{Example}
+But stop! What if, in this example, the \PName{paragraphs} would no longer fit
+on the page? Would it be printed on the next page? We will answer this
+question in the next section.%
+\EndIndexGroup
+
+
+\begin{Declaration}
+ \Macro{syncwithnotecolumns}\OParameter{list of note column names}
+\end{Declaration}
+This command synchronises the main text with all note columns of the
+comma-separated \PName{list of note column names}. The main text
+will be synchronised with the note column whose mark is closest to the
+end of the document. As a side effect, the note columns will be synchronised
+with each other.
+
+If the optional argument is omitted or empty (or begins with \Macro{relax}),
+synchronisation will be done with all currently declared note columns.%
+\EndIndexGroup
+
+
+\section{Forced Output of Note Columns}
+\seclabel{clearnotes}
+
+In addition to the normal output of note columns described in the previous
+section, you may sometimes need to output all collected notes that have
+not yet been output. This is especially useful when large notes cause more and
+more notes to be moved down to new pages. A good time to force the
+output\textnote{force output} is, for example, the end of a chapter or the end
+of the document.
+
+\begin{Declaration}
+ \Macro{clearnotecolumn}\OParameter{note column name}
+\end{Declaration}
+This command prints all notes\textnote{pending notes} of a particular note
+column that have not yet been output by the end of the current page but which
+were created on that or a previous page. Blank pages are generated as needed
+to output these pending notes. During the output of the pending notes of this
+note column, notes of other note columns may also be output, but only as
+necessary to output the pending notes of the specified note column.
+
+During the output of the pending notes, notes created in the previous \LaTeX{}
+run on the pages that are now replaced by the inserted blank pages may be
+output by mistake. This will be corrected automatically in one of the
+subsequent \LaTeX{} runs. Such shifts are usually indicated by the message:
+``\LaTeX{} Warning: Label(s) may have changed. Rerun to get cross-references
+right.''
+
+The note column whose pending notes are to be output is indicated by the
+optional argument \PName{note column name}. If this argument is omitted, the
+notes of the default note column \PValue{marginpar} will be output.
+
+The attentive reader\textnote{forced output vs. synchronisation} will have
+noticed that the forced output of a note column is not unlike synchronisation.
+But if the forced output actually results in an output, it will be at the
+start of a new page and not just below the previous output. Nonetheless, a
+forced output usually results in fewer \LaTeX{} runs.%
+\EndIndexGroup
+
+
+\begin{Declaration}
+ \Macro{clearnotecolumns}\OParameter{list of note column names}
+\end{Declaration}
+This command is similar to \DescRef{\LabelBase.cmd.clearnotecolumn}, but the
+the optional argument here can be not only the name of one note column but a
+comma-separated \PName{list of note column names}. The pending notes of all
+these note columns are then ouput.
+
+If you omit the optional argument or leave it empty, all pending notes of all
+note columns will be output.%
+\EndIndexGroup
+
+
+\begin{Declaration}
+ \OptionVName{autoclearnotecolumns}{simple switch}
+\end{Declaration}
+As a rule, pending notes will always be output if a document
+implicitly\,---\,e.\,g. because of a \DescRef{maincls.cmd.chapter}
+command\,---\,or explicitly executes \DescRef{maincls.cmd.clearpage}. This is
+also the case at the end of the document within
+\Macro{end}\PParameter{document}. The \Option{autoclearnotecolumns} option can
+be used to control whether \DescRef{\LabelBase.cmd.clearnotecolumns} should be
+executed automatically without arguments when running
+\DescRef{maincls.cmd.clearpage}.
+
+Since this is generally the desired behaviour, the option is active by
+default. But you can change this with the appropriate value for a simple
+switch (see \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch})
+at any time.
+
+Note\textnote{Attention!} that disabling the automatic output of pending notes
+can result in lost notes at the end of the document. So in this case you
+should insert \DescRef{\LabelBase.cmd.clearnotecolumns} before
+\Macro{end}\PParameter{document} fore safety's sake.
+
+The question from the end of the last section should now be answered. If the
+paragraph is to be completely output, it had to be wrapped to the next page.
+This is, of course, the default setting. However, since this would happen
+after the end of the \DescRef{maincls.env.addmargin} environment, the forced
+output could still overlap with subsequent text. So in the example it would
+make sense to add another synchronisation point after the
+\DescRef{maincls.env.addmargin} environment.
+
+The result of the example is shown in
+\autoref{fig:scrlayer-notecolumn.example}.\iffree{}{ Only the colour has been
+changed from blue to grey.}
+
+\begin{figure}
+ \KOMAoptions{captions=bottombeside}%
+ \setcapindent{0pt}%
+ \begin{captionbeside}[{A sample page for the example in
+ \autoref{cha:scrlayer-notecolumn}}]{A sample page for the example in
+ this chapter\label{fig:scrlayer-notecolumn.example}}[l]
+ \frame{\includegraphics[width=.5\textwidth,keepaspectratio]%
+ {scrlayer-notecolumn-example-en}}
+ \end{captionbeside}
+\end{figure}
+\EndIndexGroup
+%
+\EndIndexGroup
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: "scrguide-en.tex"
+%%% coding: utf-8
+%%% ispell-local-dictionary: "en_GB"
+%%% eval: (flyspell-mode 1)
+%%% End: