diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer-notecolumn.tex')
-rw-r--r-- | Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer-notecolumn.tex | 904 |
1 files changed, 463 insertions, 441 deletions
diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer-notecolumn.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer-notecolumn.tex index a181dd5780d..47cc29a8aa8 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer-notecolumn.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer-notecolumn.tex @@ -1,6 +1,6 @@ % ====================================================================== % scrlayer-notecolumn.tex -% Copyright (c) Markus Kohm, 2013-2017 +% Copyright (c) Markus Kohm, 2013-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % scrlayer-notecolumn.tex -% Copyright (c) Markus Kohm, 2013-2017 +% Copyright (c) Markus Kohm, 2013-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,233 +46,190 @@ % ============================================================================ \KOMAProvidesFile{scrlayer-notecolumn.tex} - [$Date: 2014-03-07 09:40:24 +0100 (Fri, 07 Mar 2014) $ + [$Date: 2018-02-05 01:50:56 -0800 (Mon, 05 Feb 2018) $ KOMA-Script guide (chapter:scrlayer-notecolumn)] -\translator{Markus Kohm\and Arndt Schubert} +\translator{Markus Kohm\and Arndt Schubert\and Karl Hagen} -% Date of the translated German file: 2017-02-08 +% Date of the translated German file: 2018-02-05 \chapter{Note Columns with \Package{scrlayer-notecolumn}} \labelbase{scrlayer-notecolumn} + \BeginIndexGroup -\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 \DescRef{maincls.cmd.marginpar} and \DescRef{maincls.cmd.marginline} -(see \autoref{sec:maincls.marginNotes}, -\DescPageRef{maincls.cmd.marginline}). This kind of note columns has -several disadvantages: +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 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 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 - 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}. + 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 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. + 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} -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}. +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} -Originally the package has been made as a so called \emph{proof of +This package was originally developed 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.} +\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{Declaration of new Note Columns} +\section{Declaring New Note Columns} \seclabel{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 \DescRef{maincls.cmd.marginpar} and -\DescRef{maincls.cmd.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. +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}% + \OParameter{option~list}\Parameter{note~column~name}% \Macro{DeclareNewNoteColumn}% - \OParameter{option list}\Parameter{note column name}% + \OParameter{option~list}\Parameter{note~column~name}% \Macro{ProvideNoteColumn}% - \OParameter{option list}\Parameter{note column name}% + \OParameter{option~list}\Parameter{note~column~name}% \Macro{RedeclareNoteColumn}% - \OParameter{option list}\Parameter{note column name}% + \OParameter{option~list}\Parameter{note~column~name}% \end{Declaration} -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}. +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. -\BeginIndexGroup \BeginIndex{FontElement}{notecolumn.\PName{note column name}}% \BeginIndex{FontElement}{notecolumn.marginpar}% -\LabelFontElement{notecolumn.marginpar}% -Declaring a new note column does also define a new element of which you can -change the font attributes using \DescRef{\LabelBase.cmd.setkomafont} and -\DescRef{\LabelBase.cmd.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}.% -\EndIndexGroup - - -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{\OptionVName{font}{font declaration}}{% - The initial font attributes to be used for the note column. Everything, - that is allowed to be set by \DescRef{\LabelBase.cmd.setkomafont} or - \DescRef{\LabelBase.cmd.addtokomafont} can be used as \PName{font - declaration} (see \autoref{sec:maincls.textmarkup}, - \DescPageRef{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 \DescRef{maincls.cmd.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{\OptionVName{position}{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{\OptionVName{width}{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, +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}, from +layers see \autoref{sec:scrlayer.layers}, starting on \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}{}. + 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[ngerman]{babel} - \usepackage{selinput} - \SelectInputMappings{ - adieresis={ä}, - germandbls={ß}, - } - \usepackage[T1]{fontenc} \usepackage{lmodern} \usepackage{xcolor} @@ -300,168 +257,232 @@ layers see \autoref{sec:scrlayer.layers}, from \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 - \DescRef{typearea-experts.cmd.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. + 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{Kommentar zum GüdaVaS} + \title{Commentary on the SCRACH} \author{Professor R. O. Tenase} - \date{11.\,11.~2011} + \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. + \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 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: + 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} % -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.% +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 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. +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}\\ + \Macro{makenote}\OParameter{note-column name}\Parameter{note}\\ + \Macro{makenote*}\OParameter{note-column name}\Parameter{note}\\ \end{Declaration} -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 +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}. Without these primitives -\Package{scrlayer-notecolumn} cannot be used. The primitives should act -exactly as they would using PDF\TeX. +\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 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. +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}. The predefined note column -\PValue{marginpar} is used, if the optional argument is omitted.% +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 section into the example of the previous section. The - section itself is put into the note column: + 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{Analyse} + \section{Analysis} \begin{addmargin}[0pt]{.333\textwidth} \makenote[paragraphs]{% \protect\begin{contract} \protect\Clause{% - title={Kein Witz ohne Publikum}% + title={No Joke without an Audience}% } - Ein Witz kann nur dort witzig sein, wo er - auf ein Publikum trifft. + A joke can only be funny if is has an + audience. \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. + 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} - Environment - \DescRef{maincls.env.addmargin}\IndexEnv{addmargin}\textnote{column - width by \DescRef{maincls.env.addmargin}}, 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 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: + 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 first result. + to see a preliminary 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. - -The\ChangedAt{v0.1.2583}{\Package{scrlayer-notecolumn}} problem with breaking -commands, that has been mentioned in the example above, does not occur with -the star variant \Macro{makenote*}. Is uses \Macro{detokenize} to avoid -expansion of commands. But this means also that you should not use commands, -which change their definition inside the document, in the \PName{note}.% +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.% \EndIndexGroup @@ -469,105 +490,102 @@ which change their definition inside the document, in the \PName{note}.% \Macro{syncwithnotecolumn}\OParameter{note column name} \end{Declaration} 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 +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 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 +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 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.% +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, now by adding a synchronisation point - and one more section with one more comment: + 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={Komik der Kultur}} + \protect\Clause{title={Humor of a Culture}} \setcounter{par}{0}% - Die Komik eines Witzes kann durch das - kulturelle Umfeld, in dem er erzählt wird, - bestimmt sein. + The humour of a joke can be determined by the + cultural environment in which it is told. - Die Komik eines Witzes kann durch das - kulturelle Umfeld, in dem er spielt, - bestimmt sein. + The humour of a joke can be determined by the + cultural environment in which it acts. \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. + 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} - 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: + 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 fact, all other section of the law should also be commented. But let us - focus on the main purpose. + 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 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.% +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 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 +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}), @@ -575,93 +593,97 @@ synchronisation will be done with all currently declared note columns.% \EndIndexGroup -\section{Force Output of Note Columns} +\section{Forced Output of Note Columns} \seclabel{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. +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 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.% +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} 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. +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, all delayed notes of all note columns will -be output.% +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} -Usually you would like to force the output of notes whenever a document +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}. 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 \DescRef{maincls.cmd.clearpage} should also executes -\DescRef{\LabelBase.cmd.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 -\DescRef{\LabelBase.cmd.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 -\DescRef{maincls.env.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 \DescRef{maincls.env.addmargin} environment. +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 into grey.} +changed from blue to 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 + \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}} |