summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer-notecolumn.tex
diff options
context:
space:
mode:
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.tex317
1 files changed, 317 insertions, 0 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
new file mode 100644
index 00000000000..63606d0b3a6
--- /dev/null
+++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer-notecolumn.tex
@@ -0,0 +1,317 @@
+\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}
+\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.
+
+\begin{Declaration}
+ \Macro{DeclareNoteColumn}%
+ \OParameter{option list}\Parameter{note column name}%
+ \\
+ \Macro{DeclareNewNoteColumn}%
+ \OParameter{option list}\Parameter{note column name}\\%^^A
+ \Macro{ProvideNoteColumn}%
+ \OParameter{option list}\Parameter{note column name}\\%^^A
+ \Macro{RedeclareNoteColumn}%
+ \OParameter{option list}\Parameter{note column name}%
+\end{Declaration}
+\BeginIndex{Cmd}{DeclareNoteColumn}%
+\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}''.
+
+\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}.%
+\EndIndex{FontElement}{notecolumn.\PName{note column name}}%
+
+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
+
+\begin{Declaration}
+ \Macro{makenote}%
+ \OParameter{note column name}\Parameter{note text}
+\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}
+
+\begin{Declaration}
+ \KOption{autoclearnotecolumns}\PName{simple switch}\\
+ \Macro{clearnotecolumn}\OParameter{name of a note column}%
+ \\
+ \Macro{clearnotecolumns}\OParameter{list of note column names}
+\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}%
+
+\begin{Declaration}
+ \Macro{syncwithnotecolumn}\OParameter{name of a note column}%
+ \\
+ \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'.