summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer-notecolumn.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2014-12-06 23:18:10 +0000
committerKarl Berry <karl@freefriends.org>2014-12-06 23:18:10 +0000
commit4832d732052d6e2b43b5e3ff45aa31bfbc0cbdc2 (patch)
tree968a3b4cdf4631c0272fc725330ea28a554c8471 /Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer-notecolumn.tex
parent59d9a998c6236de39603cb2ea077c5371e06b842 (diff)
koma-script (6dec14)
git-svn-id: svn://tug.org/texlive/trunk@35754 c570f23f-e606-0410-a88d-b1316a301751
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.tex929
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: