% ====================================================================== % 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-10-09 \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: