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 | 929 |
1 files changed, 643 insertions, 286 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 63606d0b3a6..877a555abea 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,90 +1,161 @@ -\immediate\write17{^^J% -+----------------------------------------------------------------------^^J% -| WARNING (`scrlayer-notecolumn.tex'):^^J% -+----------------------------------------------------------------------^^J% -| YOU SHOULD NOTE, THAT THIS IS NOT AN OFFICIAL RELEASE!^^J% -| THIS VERSION IS INTENDED TO BE USED FOR TESTING ONLY!^^J% -| USAGE FOR PURPOSES OTHER THAN INTENDED IS DANGEROUS!^^J% -| DON'T EXPECT ANY SUPPORT FOR THIS VERSION!^^J% -+----------------------------------------------------------------------^^J% -} -%% -%% This is file `scrlayer-notecolumn.tex', -%% generated with the docstrip utility, extended by scrdocstrip. -%% -%% The original source files were: -%% -%% scrlayer-notecolumn.dtx (with options: `doc') -%% -%% Copyright (c) 1994-2013 Markus Kohm [komascript at gmx info] -%% -%% This file was generated from file(s) of the KOMA-Script bundle. -%% --------------------------------------------------------------- -%% -%% It may be distributed under the conditions of the -%% LaTeX Project Public License in the version distributed together -%% with KOMA-Script, see file `lppl.txt' or `lppl-de.txt'. -%% -%% This file may only be distributed together with a copy of the -%% KOMA-Script bundle. You may however distribute the -%% KOMA-Script bundle without all such generated files. See also -%% `lppl.txt' or `lppl-de.txt' for additional information. -%% -%% The list of files belonging to KOMA-Script distribution is given in -%% the file `manifest.txt'. See also `lppl.txt' or `lppl-de.txt' for -%% additional information. -%% -%% If this file is a beta version, you may not be allowed to distribute -%% it. Look at the comments below to see if this is the case. -%% -%% English and German manuals are part of KOMA-Script bundle. -%% ---------------------------------------------------------- -%% -%% See `README'. -%% -%% The KOMA-Script bundle (but maybe not this file) was based upon the -%% LaTeX 2.09 Script family created by Frank Neukam 1993 and the LaTeX2e -%% standard classes created by The LaTeX3 Project 1994-1996. You may -%% find a complete unmodified copy of LaTeX2e at -%% <http://www.ctan.org/pub/tex-archive/macros/latex/base/>. -%% -\ProvidesFile{scrlayer-notecolumn.tex}[% - 15/11/2013 v0.1.1514 - (end user interface for scrlayer)] - -\chapter[{End User Interface \Package{scrlayer-notecolumn}}]{End User - Interface \Package{scrlayer-notecolumn}\footnote{This is not a translation - of the corresponding chapter of the German \KOMAScript{} manual but the - tentative and primary implementation manual of package - \Package{scrlayer-notecolumn}. As long as \Package{scrlayer-notecolumn} is - primary a proof of concept this doesn't matter. But nevertheless, a - German to English translator would still be welcome.}} -\label{sec:scrlayer.notecolumn} +% ====================================================================== +% scrlayer-notecolumn.tex +% Copyright (c) Markus Kohm, 2013-2014 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% scrlayer-notecolumn.tex +% Copyright (c) Markus Kohm, 2013-2014 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Chapter about scrlayer-notecolumn of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Kapitel ueber scrlayer-notecolumn in der KOMA-Script-Anleitung +% Verwaltet von Markus Kohm +% +% ============================================================================ + +\KOMAProvidesFile{scrlayer-notecolumn.tex} + [$Date: 2014-03-07 09:40:24 +0100 (Fri, 07 Mar 2014) $ + KOMA-Script guide (chapter:scrlayer-notecolumn)] + +\translator{Markus Kohm\and Arndt Schubert} + +% Date of the translated file: 2014-03-13 + +\chapter{Note Columns with \Package{scrlayer-notecolumn}} \labelbase{scrlayer-notecolumn} -Sometimes documents need an additional notes column beside the main text -column and maybe beside the marginal note column. Problematicly may be -having page breaks inside the notes column. This package provides a -solution based on the layer interface of \Package{scrlayer}. You may -define several notes columns, each of them with page breaks -inside. It supports automatic page break inside of notes and recognises -note collisions and solve them by moving notes. - -The idea of this package raised while an e-mail contact with Heiner -Richter from FH~Stralsund, who told me of a book project, and asked -whether or not such a functionality may be added to another package of -mine easily. It couldn't, but design and implementation of a first test -alpha of \Package{scrlayer-notecolumn} has been done in about three -hours. So maybe it was a really good idea to ask me the question. +\BeginIndex{}{note>columns}% +\BeginIndex{Package}{scrlayer-notecolumn}% +Up to version~3.11b \KOMAScript{} supported note columns only by marginal +notes that get their contents from \Macro{marginpar} and \Macro{marginline} +(see \autoref{sec:maincls.marginNotes}, +\autopageref{desc:maincls.cmd.marginline}). This kind of note columns has +several disadvantages: +\begin{itemize} +\item Marginal notes can be output only completely on one page. Page + breaks\textnote{page break} inside marginal notes are not + possible. Sometimes this results in margin notes located close to the lower + page margin. +\item Marginal notes near page breaks sometimes float to the next page and + then in + case of two-sided layout with alternating marginal notes can be output at + the wrong margin.\textnote{put it into the correct margin}. This problem can + be solved by additional packages like + \Package{mparhack}\IndexPackage{mparhack} or usage of \Macro{marginnote} + provided by package \Package{marginnote}\IndexPackage{marginnote}. +\item Marginal notes inside floating environments\textnote{floating + environments} or footnotes\textnote{footnotes} are not possible. This + problem can be solved using \Macro{marginnote} of package + \Package{marginnote}\IndexPackage{marginnote}, too. +\item There is only one marginal note column\textnote{several note columns} or + at most two, if you work with \Macro{reversemarginpar} and + \Macro{normalmarginpar}. You should know, that \Macro{reversemarginpar} is + of less usability on two-sided documents. +\end{itemize} +Usage of \Package{marginnote}\IndexPackage{marginnote} results in one more +problem. Because the package does not have any collision detection, marginal +notes that are set near to each other can partially or totally +overlap. Moreover, usage of \Macro{marginnote} sometimes and depending on the +used settings can result in changes of the baseline distance of the normal +text. + +Package \Package{scrlayer-notecolumn} should solve all these problems. To do +so, it uses the basic functionality of +\Package{scrlayer}\IndexPackage{scrlayer}. Nevertheless, there is a +disadvantage of using this package:\textnote{Attention!} Notes can be output +only on pages that use a \Package{scrlayer} based page style. This +disadvantage may be easily resolved and maybe changed into an advantage using +\Package{scrlayer-scrpage}\IndexPackage{scrlayer-scrpage}. + +\section{Note about the State of Development} +\label{sec:scrlayer-notecolumn.draft} + +Originally the package has been made as a so called \emph{proof of + concept}\textnote{proof of concept} to demonstrate the potential of +\Package{scrlayer}. Despite the fact that it currently is in a very early +state of development, the stability of most parts is less a question of +\Package{scrlayer-notecolumn} but of \Package{scrlayer}. Nevertheless it is +assumed that there are still bugs in \Package{scrlayer-notecolumn}. You are +welcome to report such bugs whenever you find one. Some of the disabilities +are caused by minimisation of complexity. As an example note columns can break +to several pages, but there is not a new line break of the paragraphs. \TeX{} +itself does not provide this. + +Because the package is more experimental\textnote{experimental}, the user +manual belongs to the second part of \iffree{the \KOMAScript{} manual}{this + book}, recommended for experienced users. If you are a beginner or +a user on the way to become an expert\textnote{for experts}, some explanations +could be ambiguous or incomprehensible. \iffree{Please understand that I try + to minimise the effort in time and work for the manual of an experimental + package.} + +\LoadCommon{0} % \section{Early or late options} + +\section{Declaration of new Note Columns} +\label{sec:scrlayer-notecolumn.declaration} + +Loading the package already declares a note column named \PValue{marginpar} +automatically. The name already adumbrates that this note column is placed in +the area of the normal marginal note column used by \Macro{marginpar} and +\Macro{marginline}. It even recognises the setting of \Macro{reversemarginpar} +and \Macro{normalmarginpar} page by page instead of note by note. So these +switches are irrelevant when the user defines a note but relevant when the +package outputs the note during \LaTeX's page building. If you want to use +notes at the left and at the right margin within one page, you should declare +at least one more note column. + +The default settings for every newly declared note column is the same like +that of the predefined \PValue{marginpar}. But you can easily change them +during declaration. + +You should note\textnote{Attention!} that note columns can be output only on +pages that use a page style made with package +\Package{scrlayer}\IndexPackage{scrlayer}. Package +\Package{scrlayer-notecolumn} automatically loads \Package{scrlayer}, which by +default provides only page style \Pagestyle{empty}\IndexPagestyle{empty}. If +you need additional page styles, the use of +\Package{scrlayer-scrpage}\IndexPackage{scrlayer-scrpage} is recommended. \begin{Declaration} \Macro{DeclareNoteColumn}% \OParameter{option list}\Parameter{note column name}% \\ \Macro{DeclareNewNoteColumn}% - \OParameter{option list}\Parameter{note column name}\\%^^A + \OParameter{option list}\Parameter{note column name}\\% \Macro{ProvideNoteColumn}% - \OParameter{option list}\Parameter{note column name}\\%^^A + \OParameter{option list}\Parameter{note column name}\\% \Macro{RedeclareNoteColumn}% \OParameter{option list}\Parameter{note column name}% \end{Declaration} @@ -92,226 +163,512 @@ hours. So maybe it was a really good idea to ask me the question. \BeginIndex{Cmd}{DeclareNewNoteColumn}% \BeginIndex{Cmd}{ProvideNoteColumn}% \BeginIndex{Cmd}{RedeclareNoteColumn}% -Command \Macro{DeclareNoteColumn} -may be used to declare a note column. Each note column is referenced by its -name, defined by the obligatory argument \PName{note column name}. A note -column vertically span the text area. - -By default its horizontal position is the current position of the marginal -note column. It also regards \Macro{reversemarginpar} and -\Macro{normalmarginpar}, while output of a note. Note that this is not the -same like making a margin note. The default width is -\Length{marginparwidth}. But you may use the optional argument \PName{option - list} to change this behaviour. - -The \PName{option list} is a comma-separated list of -\texttt{\PName{key}=\PName{value}} options. Currently the following -\PName{key}s are supported: -\begin{labeling}[\ --]{\KOption{position}\PName{horizontal offset}} -\item [\KOption{font}\PName{font declaration}] set the initial font attributes - to be used for the note column. Everything, that is allowed to be set by - \Macro{setkomafont} or \Macro{addtokomafont} can be used as - \PName{font declaration}. Note, that - \Macro{normalfont}\Macro{normalsize} will be used - before. So you don't need one of them at your own initialisation. -\item [\Option{marginpar}] set up \Option{position} and \Option{width} to use - the marginal note column of \Macro{marginpar}. -\item [\Option{normalmarginpar}] set up \Option{position} and \Option{width} - to use the normal marginal note column and ignore \Macro{reversemarginpar} - and \Macro{normalmarginpar}. -\item [\KOption{position}\PName{horizontal offset}] set 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. So you may even use more complex constructs like: -\begin{lstcode} - \ifodd\value{page} - \oddsidemargin+1in - +\textwidth+\marginparsep - \else - \evensidemargin+1in - -\marginparsep - -\marginparwidth - \fi -\end{lstcode} -\item [\Option{reversemarginpar}] set up \Option{position} and \Option{width} - to use the reverse marginal note column and ignore \Macro{reversemarginpar} - and \Macro{normalmarginpar}. -\item [\KOption{width}\PName{size}] set up the horizontal size of the note - column. You can use the same values for \PName{size} like for - \PName{horizontal offset} of option \Option{position}. -\end{labeling} - -You may use as much note columns as \LaTeX{} provides free box registers, -because every note column needs one box register. You may use package -\Package{etex} to increase the normal amount of box registers from 256 to -32768. This should be enough to avoid the ``\texttt{no room for - \Macro{newbox}}'' error. - -The implementation of note columns uses foreground layers from package -\Package{scrlayer}. Every \Macro{DeclareNoteColumn} generates a layer and adds -this layer to the pseudo page style \Pagestyle{@everystyle@}. Theoretically -you may modify the generated layer, but it is recommended not to modify them. - -Overlapping of different note columns is allowed. There's one predefined note -column named ``\texttt{marginpar}''. +These commands can be used to declare note columns. \Macro{DeclareNoteColumn} +declares the note column independent of whether or not they already +exist. \Macro{DeclareNewNoteColumn} throws an error message if \PName{note + column name} has already been used for another note +column. \Macro{ProvideNoteColumn} simply does nothing in the same +case. \Macro{RedeclareNoteColumn} can be used only to declare an already +existing note column again. + +By the way: Already existing notes of a already existing note column are not +lost if you re-declare it using \Macro{DeclareNoteColumn} or +\Macro{RedeclareNoteColumn}. \BeginIndex{FontElement}{notecolumn.\PName{note column name}}% -Note, that if you change the initial font using -\begin{quote} - \Macro{setkomafont}\linebreak[1]\PParameter{marginnote.\PName{note column - name}}\Parameter{font declaration} -\end{quote} -or -\begin{quote} - \Macro{addtokomafont}\linebreak[1]\PParameter{marginnote.\PName{note column - name}}\Parameter{font declaration} -\end{quote} -the font of all succeeding note column outputs would change. This could make it -hard to find out, which notes will be affected by the change. -See \autoref{sec:maincls.textmarkup}, -\autopageref{desc:maincls.cmd.setkomafont} for more information about -\Macro{setkomafont} and \Macro{addtokomafont}.% +\BeginIndex{FontElement}{notecolumn.marginpar}% +Declaring a new note column does also define a new element of which you can +change the font attributes using \Macro{setkomafont} and \Macro{addtokomafont} +if such a element does not already exist. The name of the new element is +\PValue{notecolumn.}\PName{note column name}. Because of this the predefined +note column \PValue{marginnote} has a element +\FontElement{notecolumn.marginpar}. The initial setting of the element's font +can be done using option \Option{font} as part of the \PName{option list}.% \EndIndex{FontElement}{notecolumn.\PName{note column name}}% +\EndIndex{FontElement}{notecolumn.marginpar}% + +The \PName{option list} is a comma separated list of keys with or without +values, also known as options. The available options are shown in +\autoref{tab:scrlayer-notecolumn.note.column.options}. Option\textnote{default: + option \Option{marginpar}} \Option{marginpar} is set by default. But you can +overwrite this default with your individual settings. + +\begin{table} + \caption[Options for the declaration of note columns]% + {% + Options for the declaration of note columns% + }% + \label{tab:scrlayer-notecolumn.note.column.options}% + \begin{desctabular} + \entry{\KOption{font}\PName{font declaration}}{% + The initial font attributes to be used for the note column. Everything, + that is allowed to be set by \Macro{setkomafont} or + \Macro{addtokomafont} can be used as \PName{font declaration} (see + \autoref{sec:maincls.textmarkup}, + \autopageref{desc:maincls.cmd.setkomafont}). Note that + \Macro{normalfont}\Macro{normalsize} will be used before. So you don't + need one of them at your own initialisation.\par% + Default: \emph{empty}% + }% + \entry{\Option{marginpar}}{% + Sets up \Option{position} and \Option{width} to use the marginal note + column of \Macro{marginpar}. Note that this option does not expect or + allow any value.\par% + Default: \emph{yes}% + }% + \entry{\Option{normalmarginpar}}{% + Sets up \Option{position} and \Option{width} to use the normal marginal + note column and ignore \Macro{reversemarginpar} and + \Macro{normalmarginpar}. Note that this option does not expect or allow + any value.\par% + Default: \emph{no}% + }% + \entry{\KOption{position}\PName{offset}}{% + Sets up the horizontal offset of the note column from the left edge of + the paper. The \PName{horizontal offset} can be either a \LaTeX{} + length, a \TeX{} dimension, a \TeX{} skip, a length value, or a + dimensional expression using \texttt{+}, \texttt{-}, \texttt{*}, + \texttt{/} and parenthesis (see \cite[section~3.5]{manual:eTeX} for more + information about dimensional expressions). The value will be calculated + at usage time not at definition time.\par% + Default: \emph{by option \Option{marginpar}}% + }% + \entry{\Option{reversemarginpar}}{% + Sets up \Option{position} and \Option{width} to use the reverse marginal + note column and ignore \Macro{reversemarginpar} and + \Macro{normalmarginpar}. Note that this option does not expect or allow + any value.\par% + Default: \emph{no}% + }% + \entry{\KOption{width}\PName{length}}{% + Sets up the horizontal size of the note column. You can use the same + values for \PName{size} like for \PName{offset} of option + \Option{position}.\par% + Default: \emph{by option \Option{marginpar}}% + }% + \end{desctabular} +\end{table} + +Because note columns are implemented using \Package{scrlayer}, each note +column also defines a layer\Index{layer}. The name\textnote{layer's name} of +the layer is the same as the name of the element, +\PValue{notecolumn.}\PName{note column name}. For more information about +layers see \autoref{sec:scrlayer.layers}, from +\autopageref{sec:scrlayer.layers}. +% +\begin{Example} + Assuming, you are a German professor of weird rights and like to write a + paper about the new ``Gesetz über die ausgelassene Verbreitung allgemeiner + Späße e'', GüdaVaS. The main focus of the work should consist of comments to + each section. So you use a two-columned layout. The comments would be the + main text in the main column. The sections should be placed in a smaller + note column on the right side of the main column using a smaller + font\iffree{ and a different colour}{}. +\begin{lstcode} + \documentclass{scrartcl} + \usepackage[ngerman]{babel} + \usepackage{selinput} + \SelectInputMappings{ + adieresis={ä}, + germandbls={ß}, + } + \usepackage[T1]{fontenc} + \usepackage{lmodern} + \usepackage{xcolor} + + \usepackage{scrjura} + \setkomafont{contract.Paragraph}{\bfseries} + \setkeys{contract}{preskip=-\dp\strutbox} -The difference between \Macro{DeclareNoteColumn} and the other commands is, -that \Macro{DeclareNoteColumn} defines the note column independent whether a -note column with the same name has already been defined or -not. \Macro{DeclareNewNoteColumn} defined only note columns which names are -not yet used for another note column. It's an error to use it with an already -used \PName{note column name}. \Macro{ProvideNoteColumn} is like -\Macro{DeclareNewNoteColumn}, but if the \PName{note column name} is already -used for a note column nothing happens. \Macro{RedeclareNoteColumn} may be -used to declare a note column with a name, that is already used. Using it with -a new name is an error. -\EndIndex{Cmd}{RedeclareNoteColumn}%^^A -\EndIndex{Cmd}{ProvideNoteColumn}%^^A -\EndIndex{Cmd}{DeclareNewNoteColumn}%^^A -\EndIndex{Cmd}{DeclareNoteColumn}%^^A + \usepackage{scrlayer-scrpage} + \usepackage{scrlayer-notecolumn} + + \newlength{\paragraphscolwidth} + \AfterCalculatingTypearea{% + \setlength{\paragraphscolwidth}{% + .333\textwidth}% + \addtolength{\paragraphscolwidth}{% + -\marginparsep}% + } + \recalctypearea + \DeclareNewNoteColumn[% + position=\oddsidemargin+1in + +.667\textwidth + +\marginparsep, + width=\paragraphscolwidth, + font=\raggedright\footnotesize + \color{blue} + ]{paragraphs} +\end{lstcode} + The paper should be a single-sided article. The German language (new + spelling) is selected with package \Package{babel}\IndexPackage{babel}. The + input encoding is selected and detected with package + \Package{selinput}\IndexPackage{selinput} automatically. The font is Latin + Modern in 8-bit coding.\iffree{ The colour selection uses package + \Package{xcolor}\IndexPackage{xcolor}.}{} + + For usage of package \Package{scrjura}\IndexPackage{scrjura} to typeset laws + and contracts see \iffree{the German manual of that + package}{\autoref{cha:scrjura}}. + + Next package \Package{scrlayer-notecolumn}\textnote{note columns with + \Package{scrlayer-notecolumn}} is loaded. The required width of the note + column is calculated within \Macro{AfterCalculatingTypearea} after package + \Package{typearea}'s each new calculation of the typing area. It should be + one third of the typing area minus the distance between the main text and + the note column. % + + With all this information we define the new note column. For + the positions we simply use a dimension expression. Doing so, we have to + note that \Length{oddsidemargin} is not the total left margin but for + historical reasons the left margin minus 1\Unit{inch}. So we have to add + this value. + + That is all of the declaration. But we have to note that currently the note + column would be output inside the typing area. This means that the note + column would overwrite the text. + +\begin{lstcode} + \begin{document} + + \title{Kommentar zum GüdaVaS} + \author{Professor R. O. Tenase} + \date{11.\,11.~2011} + \maketitle + \tableofcontents + + \section{Vormerkung} + Das GüdaVaS ist ohne jeden Zweifel das wichtigste + Gesetz, das in Spaßmanien in den letzten eintausend + Jahren verabschiedet wurde. Die erste Lesung fand + bereits am 11.\,11.~1111 im obersten spaßmanischen + Kongress statt, wurde aber vom damaligen Spaßvesier + abgelehnt. Erst nach Umwandlung der spaßmanischen, + aberwitzigen Monarchie in eine repräsentative, + witzige Monarchie durch W. Itzbold, + den Urkomischen, am 9.\,9.~1999 war der Weg für + dieses Gesetz endlich frei. +\end{lstcode} + Because the text area has not been reduced\textnote{Attention!}, the + preamble is output with the whole width of the typing area. To test this, + you can temporarily add: +\begin{lstcode} + \end{document} +\end{lstcode} +\end{Example} +% +Until now, the example does not give any answer to the question, how the text +of the comments will be printed with a smaller width. You will find this in +the continuation of the example below.% +\EndIndex{Cmd}{RedeclareNoteColumn}% +\EndIndex{Cmd}{ProvideNoteColumn}% +\EndIndex{Cmd}{DeclareNewNoteColumn}% +\EndIndex{Cmd}{DeclareNoteColumn}% + +\section{Making a Note} +\label{sec:scrlayer-notecolumn.makenote} + +After having declared a note column, we can make notes for this column. But +these notes will not be output immediately. Instead of this, they are written +into a helper file with extension ``\File{.slnc}''. If you want to know the +exactly workout: First they are written to the \File{aux}-file and while +reading the \File{aux}-file inside of \Macro{end}\PParameter{document} they +will be copied to the \File{slnc}-file. Thereby setting of +\Macro{nofiles}\IndexCmd{nofiles} will be respected. At the next \LaTeX{} run, +the helper file will be read step by step depending on the progress of the +document and at the end of the page the note will be output. + +But you should note\textnote{Attention!} that note columns are output only in +pages with a page style of package +\Package{scrlayer}\IndexPackage{scrlayer}. This package will be loaded by +\Package{scrlayer-notecolumn} automatically and by default provides only one +page style, \Pagestyle{empty}\IndexPagestyle{empty}. Usage of additional +package \Package{scrlayer-scrpage}\IndexPackage{scrlayer-scrpage} is +recommended, if you need more page styles. \begin{Declaration} - \Macro{makenote}% - \OParameter{note column name}\Parameter{note text} + \Macro{makenote}\OParameter{note column name}\Parameter{note} \end{Declaration} \BeginIndex{Cmd}{makenote}% -This command -may be used to make a new note. The note will be written to a helper file with -extension \File{.slnc} in this run. In the next run, it will be -typeset. Normally it will be typeset with the same vertical position, that -would be used for a \Macro{parbox[t]}, but horizontally moved to the note -column. Collisions at this position of this note column (but not of other note -columns) will be recognised. In such a case the note may be moved down and -even to another page. Automatic page breaks at the note columns are -supported. This is something different to \Macro{marginpar}, -\Macro{marginline} (\KOMAScript{} classes), or \Macro{marginnote} (package -\Package{marginnote}). - -Note, that after changing the document, at least two \LaTeX{} runs are needed -to move the note to its final position. - -Note, that fragile commands should be protected to avoid error messages while -writing or reading the helper file. - -Note, that \Package{scrlayer-notecolumn} needs only one helper file for all -note columns together. You should not edit or change that helper file, because -the syntax is fragile. It won't be read using \Macro{input} but -\Macro{read}. Because of this, line breaks, empty lines and \Macro{par} should -be avoided. - -Currently it is unknown where you may use \Macro{makenote} and where not. But -you must not use \Macro{makenote} inside of \Macro{makenote}! - -The default for the optional argument \PName{makenote} is \PValue{marginpar}, -that is the \PName{note column name} of the pre-defined note column. -\EndIndex{Cmd}{makenote} +This command may be used to make a new \PName{note}. The current vertical +position is used as the vertical position of the start of the +\PName{note}. The horizontal position depends only on the defined position of +the note column. To work correct, the package needs +\Macro{pdfsavepos}\IndexCmd{pdfsavepos}, +\Macro{pdflastypos}\IndexCmd{pdflastypos}, and +\Macro{pdfpageheight}\IndexLength{pdfpageheight}. Without these primitives +\Package{scrlayer-notecolumn} cannot be used. The primitives should act +exactly as they would using PDF\TeX. + +However, if the package recognises a collision\textnote{collision avoidance} +with the output of a former \PName{note}, then the new \PName{note} will be +delayed until the end of the former \PName{note}. If the \PName{note} does not +fit into the page\textnote{page break}\Index{page>break}, it will be moved at +whole or only at part to the next page. + +The optional argument \PName{note column name} determines which note column +should be used for the \PName{note}. The predefined note column +\PValue{marginpar} is used, if the optional argument is omitted.% +\begin{Example} + Let's add a commented section into the example of the previous section. The + section itself is put into the note column: +\begin{lstcode} + \section{Analyse} + \begin{addmargin}[0pt]{.333\textwidth} + \makenote[paragraphs]{% + \protect\begin{contract} + \protect\Paragraph{% + title={Kein Witz ohne Publikum}% + } + Ein Witz kann nur dort witzig sein, wo er + auf ein Publikum trifft. + \protect\end{contract}% + } + Dies ist eine der zentralsten Aussagen des + Gesetzes. Sie ist derart elementar, dass es + durchaus angebracht ist, sich vor der Weisheit + der Verfasser zu verbeugen. +\end{lstcode} + Environment \Environment{addmargin}\IndexEnv{addmargin}\textnote{column + width by \Environment{addmargin}}, which is described in + \autoref{sec:maincls.lists}, \autopageref{desc:maincls.env.addmargin}, is + used to reduce the width of the main text by the width of the section column. + + Here you can see one of the few problems of using + \Macro{makenote}. Because the mandatory argument will be written into a + helper file, commands\textnote{fragile commands} inside this argument + unfortunately can \emph{break}. To avoid this, it is recommended to use + \Macro{protect} in front of all commands that should not expand while + writing the helper file. Otherwise using a command inside this argument + could result in an error message. + + In principle you could finish this example already with: +\begin{lstcode} + \end{addmargin} + \end{document} +\end{lstcode} + to see a first result. +\end{Example} +If you'll test this example, you will see that the \PName{paragraphs} column +is longer than the comment. If you would\textnote{Attention!} add one more +paragraph with one more section and comment, you may have the problem, that +the new command will be put immediately after the comment above and not after +the section. So the new section would move away from the corresponding +comment. Next we will get a solution of this problem.% +\EndIndex{Cmd}{makenote}% + \begin{Declaration} - \KOption{autoclearnotecolumns}\PName{simple switch}\\ - \Macro{clearnotecolumn}\OParameter{name of a note column}% - \\ - \Macro{clearnotecolumns}\OParameter{list of note column names} + \Macro{syncwithnotecolumn}\OParameter{note column name} \end{Declaration} -\BeginIndex{Cmd}{clearnotcolumn}% -\BeginIndex{Cmd}{clearnotcolumns}% -The commands -may be used to output all hanging notes for either one or several note -columns. With \Macro{clearnotecolumn} only the notes of the note column with -the given \PName{name of a note column} will be output. If you omit the -optional argument (this is not the same like using an empty value!) note -column \PValue{marginnote} will be used. - -With \Macro{clearnotecolumns} the notes of all note columns of the comma -separated \PName{list of note column names} will be output. If you omit the -optional Argument or if the optional Argument is empty (or start with -\Macro{relax}) the notes of all note columns will be output. - -Macro \Macro{clearpage} will be used to output hanging notes and several -\LaTeX{} runs may be needed to terminate with the correct number of -\Macro{clearpage} for the whole document. You will get the message ``\LaTeX{} -Warning: Label(s) may have changed. Rerun to get cross-references right.'' as -long as the process hasn't been terminated. - -But normally you don't need to us \Macro{clearnotecolum} or -\Macro{clearnotecolumns} yourself. Because by default option -\Option{autoclearnotecolumns} is switched on, which means, that -\Macro{clearnotecolumns} will be done at every \Macro{clearpage}. You may -change this, switching off \Macro{autoclearnotecolumns} using one of the -values for simple switches. - -Note, that it is not allowed to use \Macro{clearnotecolumn} or -\Macro{clearnotecolumns} inside a note. You can use these commands only inside -the main text of the document.% -\EndIndex{Cmd}{clearnotcolumns}% -\EndIndex{Cmd}{clearnotcolumn}% +\BeginIndex{Cmd}{syncwithnotecolumn}% +This command adds a +synchronisation\textnote{synchronisation}\Index{synchronisation} point into +the note column and into the main text of the document. Whenever a +synchronisation point is found while output of a note column or the main text, +a mark will be generated that consists of the current page and the current +vertical position. + +Together with the generation of synchronisation points it is recognised +whether a mark has been set into the note column or the main text while the +previous \LaTeX{} run. If so, the values will be compared. If the mark of the +note column is lower at the current page or on a later page, the main text +will be moved down to the position of the mark. + +It is recommended to use synchronisation points\textnote{Note!} not inside +paragraphs of the main text but only between paragraphs. If you use +\Macro{syncwithnotecolumn} inside a paragraph, the synchronisation point will +be delayed until the current line has been output. This behaviour is similar +to the usage of, e.\,g., \Macro{vspace}\IndexCmd{vspace}. + +Because recognition of synchronisation points can be done first at the next +\LaTeX{} run,\textnote{several \LaTeX{} runs}, the mechanism needs at least +three \LaTeX{} runs. Because of the new synchronisation later synchronisation +points may be moved. This would result in the need of additional \LaTeX{} +runs. You should have a look at the message: ``\LaTeX{} Warning: Label(s) may +have changed. Rerun to get cross-references right.''to find out whether or not +additional \LaTeX{} runs are needed. + +If you do not use the optional argument, the predefined note column +\PValue{marginpar} will be used. Please note, an empty optional argument is +not the same as omitting the optional argument! + +You must not use\textnote{Attention!} \Macro{syncwithnotecolumn} inside a note +itself, this means inside the mandatory Argument of +\Macro{makenote}\IndexCmd{makenote}! Currently the package cannot recognise +such a mistake and would result in synchronisation point movement at each +\LaTeX{} run. So the process will never terminate. So synchronise two or more +note columns, you have to synchronise each of them with the main text. The +recommended command for this will be described next.% +% +\begin{Example} + Let's extend the example above, now by adding a synchronisation point + and one more section with one more comment: +\begin{lstcode} + \syncwithnotecolumn[paragraphs]\bigskip + \makenote[paragraphs]{% + \protect\begin{contract} + \protect\Paragraph{title={Komik der Kultur}} + \setcounter{par}{0}% + Die Komik eines Witzes kann durch das + kulturelle Umfeld, in dem er erzählt wird, + bestimmt sein. + + Die Komik eines Witzes kann durch das + kulturelle Umfeld, in dem er spielt, + bestimmt sein. + \protect\end{contract} + } + Die kulturelle Komponente eines Witzes ist + tatsächlich nicht zu vernachlässigen. Über die + politische Korrektheit der Nutzung des + kulturellen Umfeldes kann zwar trefflich + gestritten werden, nichtsdestotrotz ist die + Treffsicherheit einer solchen Komik im + entsprechenden Umfeld frappierend. Auf der + anderen Seite kann ein vermeintlicher Witz im + falschen kulturellen Umfeld auch zu einer + echten Gefahr für den Witzeerzähler werden. +\end{lstcode} + Beside the synchronisation point a vertical distance is added by + \Macro{bigskip} to better separate the section and the corresponding + comments. + + Again\textnote{Attention}, one more potential problem is shown. Because the + note columns uses boxes, that are build and split, counters\textnote{counter + in note column} inside note columns can sometimes jitter. In the example + the first paragraph would be numbered 2 instead of 1. This can easily be + fixed by a courageous reset of the counter. + + Now, the example is almost finished. You just have to finish the + environments: +\begin{lstcode} + \end{addmargin} + \end{document} +\end{lstcode} + In fact, all other section of the law should also be commented. But let us + focus on the main purpose. +\end{Example} +But stop! What, if the section in the \PName{paragraphs} +note column wouldn't fit to the last page? Would it be output on the next +pages? We will answer this question in the next paragraph.% +\EndIndex{Cmd}{syncwithnotecolumn}% \begin{Declaration} - \Macro{syncwithnotecolumn}\OParameter{name of a note column}% - \\ - \Macro{syncwithnotecolumns}\OParameter{list of note column names}% + \Macro{syncwithnotecolumns}\OParameter{list of note column names} \end{Declaration} -\BeginIndex{Cmd}{syncwithnotecolumn}% \BeginIndex{Cmd}{syncwithnotecolumns}% -These commands -may be used to synchronise the vertical position of the main text with one or -several note columns. If you use the optional argument of -\Macro{syncwithnotecolumn} it should be one \PName{name of a note column}. If -you omit it, \PValue{marginpar} will be used as the \PName{name of a note - column}. Usage of \Macro{syncwithnotecolumn} is exactly the same like usage -of \Macro{syncwithnotecolumns} with exactly one \PName{name of a note column}. - -The optional argument of \Macro{syncwithnotecolumns} is a comma-separated list -of names of note columns. If you omit this optional argument or if you use an -empty argument or if the argument starts with \Macro{relax} synchronisation -will be done with all declared note columns. - -Synchronisation with a note column means, that the current position of the -main text will be changed to be the current vertical position of the note -column after cleaning the note column. This differs in several point from -cleaning a note column: -\begin{itemize} -\item After cleaning a note column the text position would change to be at a - new page, even if the note column doesn't fill the whole page - before. Synchronisation will change the vertical position just after the - last vertical position of the note column. -\item Cleaning a note column needs less \LaTeX{} runs than synchronising a - note column. -\end{itemize} -Both, cleaning an synchronising a note column, uses the label mechanism of -\LaTeX{} without using \Macro{label}, \Macro{ref}, or \Macro{pageref} itself -(but \Macro{newlabel}). So you should have a look at \LaTeX{} rerun messages, -because of undefined or changed labels. - -Note, that it is not allowed to use \Macro{syncwithnotecolumn} or -\Macro{syncwithnotecolumns} inside a note. If you do so, you need endless -\LaTeX{} runs without reaching a final state. But synchronisation of several -note columns in the main text of a document will also synchronise the notes -columns with each others.% -\EndIndex{Cmd}{syncwithnotecolumns} -\EndIndex{Cmd}{syncwithnotecolumn} - -\endinput -%% -%% End of file `scrlayer-notecolumn.tex'. +This command will synchronise the main text with all note columns of the +comma-separated \PName{list of note column names}. To do so, the main text +will be synchronised with the note column, that have the mark closest to the +end of the document. As a side effect the note columns will be synchronised +with each other. + +If the optional argument is omitted or empty (or begins with \Macro{relax}), +synchronisation will be done with all currently declared note columns.% +\EndIndex{Cmd}{syncwithnotecolumns}% + + +\section{Force Output of Note Columns} +\label{sec:scrlayer-notecolumn.clearnotes} + +Sometimes it is necessary to have not only the normal note column output but +to be able to output all notes that haven't been output already. An example +for this effort could be that large notes result in moving lots of notes to +new pages. A good occasion to force the output\textnote{force output} could be +the end of a chapter or the end of the document. + +\begin{Declaration} + \Macro{clearnotecolumn}\OParameter{note column name} +\end{Declaration} +\BeginIndex{Cmd}{clearnotecolumn}% +This command can be used to force the output of all notes\textnote{delayed + notes} of a selected note column that haven't been output until the end of +the current page, but has been made in this page or previous pages. To force +the output empty pages will be generated. During the output of the delayed +notes of the selected note column, notes of other note columns are also output, +but only as long as there are still delayed notes of the selected note column. + +During the output of the delayed notes, notes may be output by mistake that +have been placed to one of the inserted empty pages in the previous \LaTeX{} +run. This will be solved automatically by one of the next \LaTeX{} +runs. You can realise such movement of notes by the message: ``\LaTeX{} +Warning: Label(s) may have changed. Rerun to get cross-references right.'' + +The note column related to the output, is given by the optional +argument, \PName{note column name}. If this argument is omitted, the notes of +the predefined note column \PValue{marginpar} will be output. + +Attentive readers\textnote{forced output cs. synchronisation} will have noticed +that the forced output is something similar to the synchronisation. But if the +forced output really results in an output you will be at the start of a new +page and not just at the end of the output afterwards. Nevertheless, a +forced output terminates with less \LaTeX{} runs.% +\EndIndex{Cmd}{clearnotecolumn}% + +\begin{Declaration} + \Macro{clearnotecolumns}\OParameter{list of note column names} +\end{Declaration} +\BeginIndex{Cmd}{clearnotecolumns}% +This command is similar to \Macro{clearnotecolumns} with the difference that +the optional argument is not only the name of one note column but a +comma-separated \PName{list of note column names}. It forces the output of the +notes of all these note columns. + +If you omit the optional argument, all delayed notes of all note columns will +be output.% +\EndIndex{Cmd}{clearnotecolumns}% + +\begin{Declaration} + \KOption{autoclearnotecolumns}\PName{simple switch} +\end{Declaration} +\BeginIndex{Option}{autoclearnotecolumns}% +Usually you would like to force the output of notes whenever a document +implicitly\,---\,e.\,g. because of a \Macro{chapter} command\,---\,or +explicitly executes \Macro{clearpage}. Note that this is also the case at the +end of the document inside \Macro{end}\PParameter{document}. Option +\Option{autoclearnotecolumns} manages whether or not \Macro{clearpage} should +also executes \Macro{clearnotecolumns} without any optional argument. + +According to the author's preference the option is active by +default. But you can change this with proper values for simple switches (see +\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}) at any time. + +You should note, that deactivation of the option can result in lost notes at +the end of the document. So you should insert \Macro{clearnotecolumns} before +\Macro{end}\PParameter{document} if you deactivate the option. + +This should answer the question from the end of the last section. By default +the section would be output even if it would need the output of one more +page. But because this would be done after the end of the +\Environment{addmargin} environment, the forced output could overlap with main +text after that environment. So it would be useful to either add one more +synchronisation point or to force the output explicitly immediately at the +end of the \Environment{addmargin} environment. + +The result of the example is shown in +\autoref{fig:scrlayer-notecolumn.example}.\iffree{}{ Only the colour has been + changed from blue into grey.} + +\begin{figure} + \KOMAoptions{captions=bottombeside}% + \setcapindent{0pt}% + \begin{captionbeside}[{An example page to the example of + \autoref{cha:scrlayer-notecolumn}}]{An example page to the example of + this chapter\label{fig:scrlayer-notecolumn.example}}[l] + \frame{\includegraphics[width=.5\textwidth,keepaspectratio]% + {scrlayer-notecolumn-example}} + \end{captionbeside} +\end{figure} +\EndIndex{Option}{autoclearnotecolumns}% +% +\EndIndex{Package}{scrlayer-notecolumn}% +\EndIndex{}{note>columns}% + +%%% Local Variables: +%%% mode: latex +%%% mode: flyspell +%%% coding: iso-latin-1 +%%% ispell-local-dictionary: "en_GB" +%%% TeX-master: "../guide" +%%% End: |