diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/koma-script/source-doc/english/scrlayer-notecolumn.tex |
Initial commit
Diffstat (limited to 'macros/latex/contrib/koma-script/source-doc/english/scrlayer-notecolumn.tex')
-rw-r--r-- | macros/latex/contrib/koma-script/source-doc/english/scrlayer-notecolumn.tex | 702 |
1 files changed, 702 insertions, 0 deletions
diff --git a/macros/latex/contrib/koma-script/source-doc/english/scrlayer-notecolumn.tex b/macros/latex/contrib/koma-script/source-doc/english/scrlayer-notecolumn.tex new file mode 100644 index 0000000000..47cc29a8aa --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/scrlayer-notecolumn.tex @@ -0,0 +1,702 @@ +% ====================================================================== +% scrlayer-notecolumn.tex +% Copyright (c) Markus Kohm, 2013-2018 +% +% 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-2018 +% +% 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: 2018-02-05 + +\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.% +\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 +%%% coding: iso-latin-1 +%%% ispell-local-dictionary: "en_GB" +%%% TeX-master: "../guide" +%%% End: |