path: root/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer-notecolumn.tex

% ======================================================================
% scrlayer-notecolumn.tex
% Copyright (c) Markus Kohm, 2013-2014
%
% 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.txt.
% ----------------------------------------------------------------------
% scrlayer-notecolumn.tex
% Copyright (c) Markus Kohm, 2013-2014
%
% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz,
% Version 1.3c, verteilt und/oder veraendert werden.
% Die neuste Version dieser Lizenz ist
%   http://www.latex-project.org/lppl.txt
% und Version 1.3c ist Teil aller Verteilungen von LaTeX
% Version 2005/12/01 oder spaeter und dieses Werks.
%
% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained"
% (allein durch den Autor verwaltet).
%
% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm.
% 
% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien.
% ======================================================================
%
% Chapter about scrlayer-notecolumn of the KOMA-Script guide
% Maintained by Markus Kohm
%
% ----------------------------------------------------------------------
%
% Kapitel ueber scrlayer-notecolumn in der KOMA-Script-Anleitung
% Verwaltet von Markus Kohm
%
% ============================================================================

\KOMAProvidesFile{scrlayer-notecolumn.tex}
                 [$Date: 2014-03-07 09:40:24 +0100 (Fri, 07 Mar 2014) $
                  KOMA-Script guide (chapter:scrlayer-notecolumn)]

\translator{Markus Kohm\and Arndt Schubert}

% Date of the translated file: 2014-03-13

\chapter{Note Columns with \Package{scrlayer-notecolumn}}
\labelbase{scrlayer-notecolumn}

\BeginIndex{}{note>columns}%
\BeginIndex{Package}{scrlayer-notecolumn}%
Up to version~3.11b \KOMAScript{} supported note columns only by marginal
notes that get their contents from \Macro{marginpar} and \Macro{marginline}
(see  \autoref{sec:maincls.marginNotes},
\autopageref{desc:maincls.cmd.marginline}). This kind of note columns has
several disadvantages:
\begin{itemize}
\item Marginal notes can be output only completely on one page. Page
  breaks\textnote{page break} inside marginal notes are not
  possible. Sometimes this results in margin notes located close to the lower
  page margin.
\item Marginal notes near page breaks sometimes float to the next page and
  then in
  case of two-sided layout with alternating marginal notes can be output at
  the wrong margin.\textnote{put it into the correct margin}. This problem can
  be solved by additional packages like
  \Package{mparhack}\IndexPackage{mparhack} or usage of \Macro{marginnote}
  provided by package \Package{marginnote}\IndexPackage{marginnote}.
\item Marginal notes inside floating environments\textnote{floating
    environments} or footnotes\textnote{footnotes} are not possible. This
  problem can be solved using \Macro{marginnote} of package
  \Package{marginnote}\IndexPackage{marginnote}, too.
\item There is only one marginal note column\textnote{several note columns} or
  at most two, if you work with \Macro{reversemarginpar} and
  \Macro{normalmarginpar}. You should know, that \Macro{reversemarginpar} is
  of less usability on two-sided documents.
\end{itemize}
Usage of \Package{marginnote}\IndexPackage{marginnote} results in 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, usage of \Macro{marginnote} sometimes and depending on the
used settings can result in changes of the baseline distance of the normal
text.

Package \Package{scrlayer-notecolumn} should solve all these problems. To do
so, it uses the basic functionality of
\Package{scrlayer}\IndexPackage{scrlayer}. Nevertheless, there is a
disadvantage of using this package:\textnote{Attention!} Notes can be output
only on pages that use a \Package{scrlayer} based page style. This
disadvantage may be easily resolved and maybe changed into an advantage using
\Package{scrlayer-scrpage}\IndexPackage{scrlayer-scrpage}.

\section{Note about the State of Development}
\label{sec:scrlayer-notecolumn.draft}

Originally the package has been made as a so called \emph{proof of
  concept}\textnote{proof of concept} to demonstrate the potential of
\Package{scrlayer}. Despite the fact that it currently is in a very early
state of development, the stability of most parts is less a question of
\Package{scrlayer-notecolumn} but of \Package{scrlayer}. Nevertheless it is
assumed that there are still bugs in \Package{scrlayer-notecolumn}. You are
welcome to report such bugs whenever you find one. Some of the disabilities
are caused by minimisation of complexity. As an example note columns can break
to several pages, but there is not a new line break of the paragraphs. \TeX{}
itself does not provide this.

Because the package is more experimental\textnote{experimental}, the user
manual belongs to the second part of \iffree{the \KOMAScript{} manual}{this
  book}, recommended for experienced users. If you are a beginner or
a user on the way to become an expert\textnote{for experts}, some explanations
could be ambiguous or incomprehensible. \iffree{Please understand that I try
  to minimise the effort in time and work for the manual of an experimental
  package.}

\LoadCommon{0} % \section{Early or late options}

\section{Declaration of new Note Columns}
\label{sec:scrlayer-notecolumn.declaration}

Loading the package already declares a note column named \PValue{marginpar}
automatically. The name already adumbrates that this note column is placed in
the area of the normal marginal note column used by \Macro{marginpar} and
\Macro{marginline}. It even recognises the setting of \Macro{reversemarginpar}
and \Macro{normalmarginpar} page by page instead of note by note. So these
switches are irrelevant when the user defines a note but relevant when the
package outputs the note during \LaTeX's page building. If you want to use
notes at the left and at the right margin within one page, you should declare
at least one more note column.

The default settings for every newly declared note column is the same like
that of the predefined \PValue{marginpar}. But you can easily change them
during declaration.

You should note\textnote{Attention!} that note columns can be output only on
pages that use a page style made with package
\Package{scrlayer}\IndexPackage{scrlayer}. Package
\Package{scrlayer-notecolumn} automatically loads \Package{scrlayer}, which by
default provides only page style \Pagestyle{empty}\IndexPagestyle{empty}. If
you need additional page styles, the use of
\Package{scrlayer-scrpage}\IndexPackage{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}
\BeginIndex{Cmd}{DeclareNoteColumn}%
\BeginIndex{Cmd}{DeclareNewNoteColumn}%
\BeginIndex{Cmd}{ProvideNoteColumn}%
\BeginIndex{Cmd}{RedeclareNoteColumn}%
These commands can be used to declare note columns. \Macro{DeclareNoteColumn}
declares the note column independent of whether or not they already
exist. \Macro{DeclareNewNoteColumn} throws an error message if \PName{note
  column name} has already been used for another note
column. \Macro{ProvideNoteColumn} simply does nothing in the same
case. \Macro{RedeclareNoteColumn} can be used only to declare an already
existing note column again.

By the way: Already existing notes of a already existing note column are not
lost if you re-declare it using \Macro{DeclareNoteColumn} or
\Macro{RedeclareNoteColumn}.

\BeginIndex{FontElement}{notecolumn.\PName{note column name}}%
\BeginIndex{FontElement}{notecolumn.marginpar}%
Declaring a new note column does also define a new element of which you can
change the font attributes using \Macro{setkomafont} and \Macro{addtokomafont}
if such a element does not already exist. The name of the new element is
\PValue{notecolumn.}\PName{note column name}. Because of this the predefined
note column \PValue{marginnote} has a element
\FontElement{notecolumn.marginpar}. The initial setting of the element's font
can be done using option \Option{font} as part of the \PName{option list}.%
\EndIndex{FontElement}{notecolumn.\PName{note column name}}%
\EndIndex{FontElement}{notecolumn.marginpar}%

The \PName{option list} is a comma separated list of keys with or without
values, also known as options. The available options are shown in
\autoref{tab:scrlayer-notecolumn.note.column.options}. Option\textnote{default:
  option \Option{marginpar}} \Option{marginpar} is set by default. But you can
overwrite this default with your individual settings.

\begin{table}
  \caption[Options for the declaration of note columns]%
  {%
    Options for the declaration of note columns%
  }%
  \label{tab:scrlayer-notecolumn.note.column.options}%
  \begin{desctabular}
    \entry{\KOption{font}\PName{font declaration}}{%
      The initial font attributes to be used for the note column. Everything,
      that is allowed to be set by \Macro{setkomafont} or
      \Macro{addtokomafont} can be used as \PName{font declaration} (see
      \autoref{sec:maincls.textmarkup},
      \autopageref{desc:maincls.cmd.setkomafont}). Note that
      \Macro{normalfont}\Macro{normalsize} will be used before. So you don't
      need one of them at your own initialisation.\par%
      Default: \emph{empty}%
    }%
    \entry{\Option{marginpar}}{%
      Sets up \Option{position} and \Option{width} to use the marginal note
      column of \Macro{marginpar}. Note that this option does not expect or
      allow any value.\par%
      Default: \emph{yes}%
    }%
    \entry{\Option{normalmarginpar}}{%
      Sets up \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
      any value.\par%
      Default: \emph{no}%
    }%
    \entry{\KOption{position}\PName{offset}}{%
      Sets up the horizontal offset of the note column from the left edge of
      the paper. The \PName{horizontal offset} can be either a \LaTeX{}
      length, a \TeX{} dimension, a \TeX{} skip, a length value, or a
      dimensional expression using \texttt{+}, \texttt{-}, \texttt{*},
      \texttt{/} and parenthesis (see \cite[section~3.5]{manual:eTeX} for more
      information about dimensional expressions). The value will be calculated
      at usage time not at definition time.\par%
      Default: \emph{by option \Option{marginpar}}%
    }%
    \entry{\Option{reversemarginpar}}{%
      Sets up \Option{position} and \Option{width} to use the reverse marginal
      note column and ignore \Macro{reversemarginpar} and
      \Macro{normalmarginpar}. Note that this option does not expect or allow
      any value.\par%
      Default: \emph{no}%
    }%
    \entry{\KOption{width}\PName{length}}{%
      Sets up the horizontal size of the note column. You can use the same
      values for \PName{size} like for \PName{offset} of option
      \Option{position}.\par%
      Default: \emph{by option \Option{marginpar}}%
    }%
  \end{desctabular}
\end{table}

Because note columns are implemented using \Package{scrlayer}, each note
column also defines a layer\Index{layer}. The name\textnote{layer's name} of
the layer 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}, from
\autopageref{sec:scrlayer.layers}.
%
\begin{Example}
  Assuming, you are a German professor of weird rights and like to write a
  paper about the new ``Gesetz über die ausgelassene Verbreitung allgemeiner
  Späße e'', GüdaVaS. The main focus of the work should consist of comments to
  each section. So you use a two-columned layout. The comments would be the
  main text in the main column. The sections should be placed in a smaller
  note column on the right side of the main column using a smaller
  font\iffree{ and a different colour}{}.
\begin{lstcode}
  \documentclass{scrartcl}
  \usepackage[ngerman]{babel}
  \usepackage{selinput}
  \SelectInputMappings{
    adieresis={ä},
    germandbls={ß},
  }
  \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}
  The paper should be a single-sided article. The German language (new
  spelling) is selected with package \Package{babel}\IndexPackage{babel}. The
  input encoding is selected and detected with package
  \Package{selinput}\IndexPackage{selinput} automatically. The font is Latin
  Modern in 8-bit coding.\iffree{ The colour selection uses package
    \Package{xcolor}\IndexPackage{xcolor}.}{}

  For usage of package \Package{scrjura}\IndexPackage{scrjura} to typeset laws
  and contracts see \iffree{the German manual of that
    package}{\autoref{cha:scrjura}}.

  Next package \Package{scrlayer-notecolumn}\textnote{note columns with
    \Package{scrlayer-notecolumn}} is loaded. The required width of the note
  column is calculated within \Macro{AfterCalculatingTypearea} after package
  \Package{typearea}'s each new calculation of the typing area. It should be
  one third of the typing area minus the distance between the main text and
  the note column. %

  With all this information we define the new note column. For
  the positions we simply use a dimension expression. Doing so, we have to
  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.

  That is all of the declaration. But we have to note that currently the note
  column would be output inside the typing area. This means that the note
  column would overwrite the text.

\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}
  Because the text area has not been reduced\textnote{Attention!}, the
  preamble is output with the whole width of the typing area. To test this,
  you can temporarily add:
\begin{lstcode}
  \end{document}
\end{lstcode}
\end{Example}
%
Until now, the example does not give any answer to the question, how the text
of the comments will be printed with a smaller width. You will find this in
the continuation of the example below.%
\EndIndex{Cmd}{RedeclareNoteColumn}%
\EndIndex{Cmd}{ProvideNoteColumn}%
\EndIndex{Cmd}{DeclareNewNoteColumn}%
\EndIndex{Cmd}{DeclareNoteColumn}%

\section{Making a Note}
\label{sec:scrlayer-notecolumn.makenote}

After having declared a note column, we can make notes for this column. But
these notes will not be output immediately. Instead of this, they are written
into a helper file with extension ``\File{.slnc}''. If you want to know the
exactly workout: First they are written to the \File{aux}-file and while
reading the \File{aux}-file inside of \Macro{end}\PParameter{document} they
will be copied to the \File{slnc}-file. Thereby setting of
\Macro{nofiles}\IndexCmd{nofiles} will be respected. At the next \LaTeX{} run,
the helper file will be read step by step depending on the progress of the
document and at the end of the page the note will be output.

But you should note\textnote{Attention!} that note columns are output only in
pages with a page style of package
\Package{scrlayer}\IndexPackage{scrlayer}. This package will be loaded by
\Package{scrlayer-notecolumn} automatically and by default provides only one
page style, \Pagestyle{empty}\IndexPagestyle{empty}. Usage of additional
package \Package{scrlayer-scrpage}\IndexPackage{scrlayer-scrpage} is
recommended, if you need more page styles.

\begin{Declaration}
  \Macro{makenote}\OParameter{note column name}\Parameter{note}
\end{Declaration}
\BeginIndex{Cmd}{makenote}%
This command may be used to make a new \PName{note}. The current vertical
position is used as the vertical position of the start of the
\PName{note}. The horizontal position depends only on the defined position of
the note column. To work correct, the package needs
\Macro{pdfsavepos}\IndexCmd{pdfsavepos},
\Macro{pdflastypos}\IndexCmd{pdflastypos}, and
\Macro{pdfpageheight}\IndexLength{pdfpageheight}. Without these primitives
\Package{scrlayer-notecolumn} cannot be used. The primitives should act
exactly as they would using PDF\TeX.

However, if the package recognises a collision\textnote{collision avoidance}
with the output of a former \PName{note}, then the new \PName{note} will be
delayed until the end of the former \PName{note}. If the \PName{note} does not
fit into the page\textnote{page break}\Index{page>break}, it will be moved at
whole or only at part to the next page.

The optional argument \PName{note column name} determines which note column
should be used for the \PName{note}. The predefined note column
\PValue{marginpar} is used, if the optional argument is omitted.%
\begin{Example}
  Let's add a commented section into the example of the previous section. The
  section itself is put into the note column:
\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}
  Environment  \Environment{addmargin}\IndexEnv{addmargin}\textnote{column
    width by \Environment{addmargin}}, which is described in
  \autoref{sec:maincls.lists}, \autopageref{desc:maincls.env.addmargin}, is
  used to reduce the width of the main text by the width of the section column.

  Here you can see one of the few problems of using
  \Macro{makenote}. Because the mandatory argument will be written into a
  helper file, commands\textnote{fragile commands} inside this argument
  unfortunately can \emph{break}. To avoid this, it is recommended to use
  \Macro{protect} in front of all commands that should not expand while
  writing the helper file. Otherwise using a command inside this argument
  could result in an error message.

  In principle you could finish this example already with:
\begin{lstcode}
  \end{addmargin}
  \end{document}
\end{lstcode}
  to see a first result.
\end{Example}
If you'll test this example, you will see that the \PName{paragraphs} column
is longer than the comment. If you would\textnote{Attention!} add one more
paragraph with one more section and comment, you may have the problem, that
the new command will be put immediately after the comment above and not after
the section. So the new section would move away from the corresponding
comment. Next we will get a solution of this problem.%
\EndIndex{Cmd}{makenote}%


\begin{Declaration}
  \Macro{syncwithnotecolumn}\OParameter{note column name}
\end{Declaration}
\BeginIndex{Cmd}{syncwithnotecolumn}%
This command adds a
synchronisation\textnote{synchronisation}\Index{synchronisation} point into
the note column and into the main text of the document. Whenever a
synchronisation point is found while 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.

Together with the generation of synchronisation points it is recognised
whether a mark has been set into the note column or the main text while the
previous \LaTeX{} run. If so, the values will be compared. If the mark of the
note column is lower at the current page or on a later page, the main text
will be moved down to the position of the mark.

It is recommended to use synchronisation points\textnote{Note!} not inside
paragraphs of the main text but only between paragraphs. If you use
\Macro{syncwithnotecolumn} inside a paragraph, the synchronisation point will
be delayed until the current line has been output. This behaviour is similar
to the usage of, e.\,g., \Macro{vspace}\IndexCmd{vspace}.

Because recognition of synchronisation points can be done first at the next
\LaTeX{} run,\textnote{several \LaTeX{} runs}, the mechanism needs at least
three \LaTeX{} runs. Because of the new synchronisation later synchronisation
points may be moved. This would result in the need of additional \LaTeX{}
runs. You should have a look at the message: ``\LaTeX{} Warning: Label(s) may
have changed. Rerun to get cross-references right.''to find out whether or not
additional \LaTeX{} runs are needed.

If you do not use the optional argument, the predefined note column
\PValue{marginpar} will be used. Please note, an empty optional argument is
not the same as omitting the optional argument!

You must not use\textnote{Attention!} \Macro{syncwithnotecolumn} inside a note
itself, this means inside the mandatory Argument of
\Macro{makenote}\IndexCmd{makenote}! Currently the package cannot recognise
such a mistake and would result in synchronisation point movement at each
\LaTeX{} run. So the process will never terminate. So synchronise two or more
note columns, you have to synchronise each of them with the main text. The
recommended command for this will be described next.%
%
\begin{Example}
  Let's extend the example above, now by adding a synchronisation point
  and one more section with one more comment:
\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 trefflich 
    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}
  Beside the synchronisation point a vertical distance is added by
  \Macro{bigskip} to better separate the section and the corresponding
  comments.

  Again\textnote{Attention}, one more potential problem is shown. Because the
  note columns uses boxes, that are build and split, counters\textnote{counter
    in note column} inside note columns can sometimes jitter. In the example
  the first paragraph would be numbered 2 instead of 1. This can easily be
  fixed by a courageous reset of the counter.

  Now, the example is almost finished. You just have to finish the
  environments:
\begin{lstcode}
  \end{addmargin}
  \end{document}
\end{lstcode}
  In fact, all other section of the law should also be commented. But let us
  focus on the main purpose.
\end{Example}
But stop! What, if the section in the \PName{paragraphs}
note column wouldn't fit to the last page? Would it be output on the next
pages? We will answer this question in the next paragraph.%
\EndIndex{Cmd}{syncwithnotecolumn}%

\begin{Declaration}
  \Macro{syncwithnotecolumns}\OParameter{list of note column names}
\end{Declaration}
\BeginIndex{Cmd}{syncwithnotecolumns}%
This command will synchronise the main text with all note columns of the
comma-separated \PName{list of note column names}. To do so, the main text
will be synchronised with the note column, that have the mark 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.%
\EndIndex{Cmd}{syncwithnotecolumns}%


\section{Force Output of Note Columns}
\label{sec:scrlayer-notecolumn.clearnotes}

Sometimes it is necessary to have not only the normal note column output but
to be able to output all notes that haven't been output already. An example
for this effort could be that large notes result in moving lots of notes to
new pages. A good occasion to force the output\textnote{force output} could be
the end of a chapter or the end of the document.

\begin{Declaration}
  \Macro{clearnotecolumn}\OParameter{note column name}
\end{Declaration}
\BeginIndex{Cmd}{clearnotecolumn}%
This command can be used to force the output of all notes\textnote{delayed
  notes} of a selected note column that haven't been output until the end of
the current page, but has been made in this page or previous pages. To force
the output empty pages will be generated. During the output of the delayed
notes of the selected note column, notes of other note columns are also output,
but only as long as there are still delayed notes of the selected note column.

During the output of the delayed notes, notes may be output by mistake that
have been placed to one of the inserted empty pages in the previous \LaTeX{}
run. This will be solved automatically by one of the next \LaTeX{}
runs. You can realise such movement of notes by the message: ``\LaTeX{}
Warning: Label(s) may have changed. Rerun to get cross-references right.''

The note column related to the output, is given by the optional
argument, \PName{note column name}. If this argument is omitted, the notes of
the predefined note column \PValue{marginpar} will be output.

Attentive readers\textnote{forced output cs. synchronisation} will have noticed
that the forced output is something similar to the synchronisation. But if the
forced output really results in an output you will be at the start of a new
page and not just at the end of the output afterwards. Nevertheless, a
forced output terminates with less \LaTeX{} runs.%
\EndIndex{Cmd}{clearnotecolumn}%

\begin{Declaration}
  \Macro{clearnotecolumns}\OParameter{list of note column names}
\end{Declaration}
\BeginIndex{Cmd}{clearnotecolumns}%
This command is similar to \Macro{clearnotecolumns} with the difference that
the optional argument is not only the name of one note column but a
comma-separated \PName{list of note column names}. It forces the output of the
notes of all these note columns.

If you omit the optional argument, all delayed notes of all note columns will
be output.%
\EndIndex{Cmd}{clearnotecolumns}%

\begin{Declaration}
  \KOption{autoclearnotecolumns}\PName{simple switch}
\end{Declaration}
\BeginIndex{Option}{autoclearnotecolumns}%
Usually you would like to force the output of notes whenever a document
implicitly\,---\,e.\,g. because of a \Macro{chapter} command\,---\,or
explicitly executes \Macro{clearpage}. Note that this is also the case at the
end of the document inside \Macro{end}\PParameter{document}. Option
\Option{autoclearnotecolumns} manages whether or not \Macro{clearpage} should
also executes \Macro{clearnotecolumns} without any optional argument.

According to the author's preference the option is active by
default. But you can change this with proper values for simple switches (see
\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}) at any time.

You should note, that deactivation of the option can result in lost notes at
the end of the document. So you should insert \Macro{clearnotecolumns} before
\Macro{end}\PParameter{document} if you deactivate the option.

This should answer the question from the end of the last section. By default
the section would be output even if it would need the output of one more
page. But because this would be done after the end of the
\Environment{addmargin} environment, the forced output could overlap with main
text after that environment. So it would be useful to either add one more
synchronisation point or to force the output explicitly immediately at the
end of the \Environment{addmargin} environment.

The result of the example is shown in
\autoref{fig:scrlayer-notecolumn.example}.\iffree{}{ Only the colour has been
  changed from blue into grey.}

\begin{figure}
  \KOMAoptions{captions=bottombeside}%
  \setcapindent{0pt}%
  \begin{captionbeside}[{An example page to the example of
      \autoref{cha:scrlayer-notecolumn}}]{An example page to the example of
      this chapter\label{fig:scrlayer-notecolumn.example}}[l]
  \frame{\includegraphics[width=.5\textwidth,keepaspectratio]%
    {scrlayer-notecolumn-example}}
  \end{captionbeside}
\end{figure}
\EndIndex{Option}{autoclearnotecolumns}%
%
\EndIndex{Package}{scrlayer-notecolumn}%
\EndIndex{}{note>columns}%

%%% Local Variables:
%%% mode: latex
%%% mode: flyspell
%%% coding: iso-latin-1
%%% ispell-local-dictionary: "en_GB"
%%% TeX-master: "../guide"
%%% End: