diff options
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.tex | 266 |
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: |