summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/koma-script/doc/typearea-experts-en.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/koma-script/doc/typearea-experts-en.tex')
-rw-r--r--macros/latex/contrib/koma-script/doc/typearea-experts-en.tex266
1 files changed, 266 insertions, 0 deletions
diff --git a/macros/latex/contrib/koma-script/doc/typearea-experts-en.tex b/macros/latex/contrib/koma-script/doc/typearea-experts-en.tex
new file mode 100644
index 0000000000..3489136cc8
--- /dev/null
+++ b/macros/latex/contrib/koma-script/doc/typearea-experts-en.tex
@@ -0,0 +1,266 @@
+% ======================================================================
+% typearea-experts-en.tex
+% Copyright (c) Markus Kohm, 2001-2022
+%
+% 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.md.
+% ======================================================================
+%
+% Chapter about typearea for experts of the KOMA-Script guide
+% Maintained by Markus Kohm
+%
+% ======================================================================
+
+\KOMAProvidesFile{typearea-experts-en.tex}
+ [$Date: 2022-06-05 12:40:11 +0200 (So, 05. Jun 2022) $
+ KOMA-Script guide (chapter: typearea)]
+\translator{Markus Kohm\and Gernot Hassenpflug\and Karl Hagen}
+
+\chapter{Additional Information about the \Package{typearea} package}
+\labelbase{typearea-experts}
+\BeginIndexGroup
+\BeginIndex{Package}{typearea}
+
+This chapter provides additional information about the \Package{typearea}
+package. \iffree{Some parts of the chapter are found only in the German
+ \KOMAScript{} book \cite{book:komascript}. This should not be a problem,
+ because the}{The} average user, who only wants to use the package, will not
+normally need this information. Part of this material is intended for users
+who want to solve unusual problems or write their own packages using
+\Package{typearea}. Another part covers \Package{typearea} features that exist
+only for compatibility with earlier versions of \KOMAScript{} or with the
+standard classes. The features that exist only for compatibility with earlier
+versions of \KOMAScript{} are printed in a sans serif font. You should not use
+them any longer.
+
+
+\section{Experimental Features}
+\seclabel{experimental}
+
+This section describes experimental features. Experimental, in this context,
+means that correct functioning cannot be guaranteed. There can be two reasons
+for designating something experimental. First, the final function is not yet
+defined or its implementation is not yet finalised. Second, a feature may
+depend on internal functions of other packages and therefore the feature can
+not be guaranteed, if the other packages change.
+
+\begin{Declaration}
+ \OptionVName{usegeometry}{simple switch}
+\end{Declaration}
+Usually \Package{typearea} does not care much if you use it with the
+\Package{geometry}\IndexPackage{geometry} package (see
+\cite{package:geometry}) in any configuration. In particular, this means that
+\Package{geometry} does not recognise any changes to the page parameters done
+with \Package{typearea}, for example when it changes the paper size\,---\,a
+feature not provided by \Package{geometry} itself.
+
+Once\ChangedAt{v3.17}{\Package{typearea}} you set option \Option{usegeometry},
+\Package{typearea} tries to translate all of its options into options of
+\Package{geometry}. If you activate new parameters inside the document,
+\Package{typearea} even calls \Macro{newgeometry} (see
+\DescRef{\LabelBase.cmd.activateareas} in the following section). Since
+\Package{geometry} does not support changes of paper size or page orientation
+with \Macro{newgeometry}, \Package{typearea} uses internal commands and
+\Package{geometry} lengths to provide such changes as needed. This has been
+tested with \Package{geometry}~5.3 through 5.6.
+
+Note that using \Package{geometry} and changing page size or orientation with
+\Package{typearea} does not mean that \Package{geometry} will automatically
+use the new paper size in an expected manner. For convenience,
+\Package{geometry} provides far more options to adjust the page than are
+required to determine the type area, margins, header, footer, etc.\,---\,this
+is called \emph{overdetermination}\,---\, and at the same time
+\Macro{newgeometry} derives missing information from the known
+values\,---\,known as \emph{value preservation}\,---\,so you often must
+explicitly specify all new values completely when you call \Macro{newgeometry}
+on your own. Nevertheless, when \Package{typearea} takes \Package{geometry}
+into consideration, it opens up additional possibilities.%
+\EndIndexGroup
+
+
+\begin{Declaration}
+ \OptionVName{areasetadvanced}{simple switch}
+ \Macro{areaset}\OParameter{BCOR}\Parameter{width}\Parameter{height}
+\end{Declaration}
+Usually, \DescRef{typearea.cmd.areaset} does not handle options to define the
+height of the header or footer, or whether margin elements should count as
+part of the type area in the same way as \DescRef{typearea.cmd.typearea}. With
+the \Option{areasetadvanced}\ChangedAt{v3.11}{\Package{typearea}} option, you
+can make \DescRef{typearea.cmd.areaset} behave more like
+\DescRef{typearea.cmd.typearea} in this regard. Nevertheless, settings for the
+two commands that result in type areas of equal size still can differ because
+\DescRef{typearea.cmd.typearea} always adjusts the type area so that it
+contains an integer number of lines, potentially making the bottom margin up
+to one line smaller, whereas \DescRef{typearea.cmd.areaset} always sets the
+ratio between the top and bottom margins at 1:2. The type area can therefore
+be slightly shifted vertically depending on which command was used.%
+\EndIndexGroup
+
+
+\section{Expert Commands}
+\seclabel{experts}
+
+This section describes commands that are of little or no interest to average
+users. These commands give experts additional possibilities. Because this
+information is addressed to experts, it appears in condensed form.
+
+\begin{Declaration}
+ \Macro{activateareas}
+\end{Declaration}%
+The \Package{typearea} package uses this command convert the settings for the
+type area and margins to internal \LaTeX{} lengths whenever the type area has
+been recalculated inside of the document, that is after
+\Macro{begin}\PParameter{document}. If the \DescRef{typearea.option.pagesize}
+option has been used, it will be executed again with the same value. Thus, for
+example, the page size may actually vary within PDF documents.
+
+Experts can also use this command if they have manually changed lengths like
+\Length{textwidth} or \Length{textheight} inside a document for any reason. If
+you do so, however, you are responsible for any necessary page breaks before
+or after you call \Macro{activateareas}. Moreover, all changes made by
+\Macro{activateareas} are local.%
+%
+\EndIndexGroup
+
+
+\begin{Declaration}
+ \Macro{storeareas}\Parameter{\textMacro{command}}%
+ \Macro{BeforeRestoreareas}\Parameter{code}%
+ \Macro{BeforeRestoreareas*}\Parameter{code}%
+ \Macro{AfterRestoreareas}\Parameter{code}%
+ \Macro{AfterRestoreareas*}\Parameter{code}
+\end{Declaration}
+\Macro{storeareas} defines a \PName{\Macro{command}} which you can use to
+restore all current type-area settings. So you can save the current settings,
+change them, and then restore the previous settings afterwards.
+
+\begin{Example}
+ Time and again, users ask about the possibility of inserting an A3 page in
+ landscape format in an A4 document while retaining the margin settings. The
+ text area should therefore only be widened by the extra paper width. With
+ \Macro{storeareas}, \DescRef{\LabelBase.cmd.areaset} and the previously
+ explained option \DescRef{\LabelBase.option.areasetadvanced} this is very
+ easily possible:
+
+\begin{lstcode}
+ \documentclass[areasetadvanced]{scrartcl}
+ \areaset[current]{\textwidth}{\textheight}
+
+ \begin{document}
+ \noindent\rule{\textwidth}{\textheight}
+
+ \storeareas\MySavedTypingArea
+ \KOMAoption{paper}{a3,landscape}
+ \areaset[current]
+ {\dimexpr\textwidth+.5\paperwidth\relax}
+ {\textheight}
+ \noindent\rule{\textwidth}{\textheight}
+
+ \clearpage
+ \MySavedTypingArea
+ \noindent\rule{\textwidth}{\textheight}
+ \end{document}
+\end{lstcode}
+ The \DescRef{\LabelBase.cmd.areaset} command\IndexCmd{areaset} in the
+ document preamble is used together with the
+ \DescRef{\LabelBase.option.areasetadvanced}\IndexOption{areasetadvanced}
+ option to compensate for the differences between the
+ \DescRef{typearea.cmd.typearea} preset and the later use of
+ \DescRef{\LabelBase.cmd.areaset}, as already explained on
+ \DescPageRef{\LabelBase.option.areasetadvanced}. Without this, there could
+ be significant differences in margin settings, especially when using options
+ like \DescRef{typearea.option.headinclude} and
+ \DescRef{typearea.option.headheight}.
+
+ It's\textnote{Attention} important to call \DescRef{maincls.cmd.clearpage}
+ before \Macro{MySavedTypingArea} so that the saved values are restored on
+ the next page. With two-sided documents, changes to the paper format should
+ even use
+ \DescRef{maincls.cmd.cleardoubleoddpage}\IndexCmd{cleardoubleoddpage}
+ or\,---\,if you are not using a \KOMAScript{}
+ class\,---\,\DescRef{maincls.cmd.cleardoublepage}%
+ \IndexCmd{cleardoublepage}.%
+ \iffree{\par In addition, \Macro{noindent} is used to avoid paragraph
+ indents of the black boxes. Otherwise, you would not produce a correct
+ image of the type area.}{}%
+\end{Example}
+
+Note\textnote{Attention!} that neither \Macro{storeareas} nor the defined
+\PName{\Macro{command}} defined with it should be used inside a group.
+Internally,
+\Macro{newcommand}\IndexCmd{newcommand*}\important{\Macro{newcommand*}} is
+used to define the \PName{\Macro{command}}. So reusing a
+\PName{\Macro{command}} to store settings again would result in a
+corresponding error message.
+
+Often\ChangedAt{v3.18}{\Package{typearea}}, it is useful to automatically
+execute commands like \DescRef{maincls.cmd.cleardoubleoddpage} before
+restoring the settings of a \Macro{command} generated by \Macro{storeareas}.
+You can do so using \Macro{BeforeRestoreareas} or \Macro{BeforeRestoreareas*}.
+Similarly, you can use \Macro{AfterRestoreareas} or \Macro{AfterRestoreareas*}
+to automatically execute \PName{code} after restoring the settings. The
+variants with and without the star differ in that the starred variant only
+applies the \PName{code} to future \PName{command}s generated by
+\Macro{storeareas}, whereas the regular variant also adds the \PName{code} to
+previously defined \PName{command}s.%
+\EndIndexGroup
+
+
+\begin{Declaration}
+ \Macro{AfterCalculatingTypearea}\Parameter{code}%
+ \Macro{AfterCalculatingTypearea*}\Parameter{code}%
+ \Macro{AfterSettingArea}\Parameter{cod}%
+ \Macro{AfterSettingArea*}\Parameter{code}
+\end{Declaration}%
+These commands serve to manage two hooks\Index{hook}. The first two,
+\Macro{AfterCalculatingTypearea} and its starred variant let experts execute
+\PName{code} each time \Package{typearea} recalculates the type area and
+margins, that is after every implicitly or explicit invocation of
+\DescRef{typearea.cmd.typearea}. Similarly,
+\Macro{AfterSettingArea}\ChangedAt{v3.11}{\Package{typearea}} and its starred
+variant allow for executing \PName{code} every time
+\DescRef{typearea.cmd.areaset} has been used. The normal versions have a
+global scope, while changes made in the starred versions are only local. The
+\PName{code} is executed immediately before \Macro{activateareas}.\iffree{}{
+ In \autoref{cha:modernletters}, The letter-class-option file
+ \File{asymTypB.lco} uses it to change the distribution of the margins.}%
+%
+\EndIndexGroup
+
+
+\section{Local Settings with the \File{typearea.cfg} File}
+\seclabel{cfg}
+\BeginIndexGroup
+\BeginIndex{File}{typearea.cfg}
+
+\LoadNonFree{typearea-experts}{0}
+%
+\EndIndexGroup
+
+\section{More or Less Obsolete Options and Commands}
+\seclabel{obsolete}
+\LoadNonFree{typearea-experts}{1}
+%
+\EndIndexGroup
+
+\endinput
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: "scrguide-en.tex"
+%%% coding: utf-8
+%%% ispell-local-dictionary: "en_GB"
+%%% eval: (flyspell-mode 1)
+%%% End: