You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
723 lines
33 KiB
723 lines
33 KiB
% ======================================================================
|
|
% scrlayer-notecolumn.tex
|
|
% Copyright (c) Markus Kohm, 2013-2019
|
|
%
|
|
% 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-2019
|
|
%
|
|
% 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: 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}
|
|
|
|
% Date of the translated German file: 2019-12-03
|
|
|
|
\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}}
|
|
\end{captionbeside}
|
|
\end{figure}
|
|
\EndIndexGroup
|
|
%
|
|
\EndIndexGroup
|
|
|
|
%%% Local Variables:
|
|
%%% mode: latex
|
|
%%% mode: flyspell
|
|
%%% ispell-local-dictionary: "en_GB"
|
|
%%% TeX-master: "../guide"
|
|
%%% End:
|
|
|