diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/koma-script/doc/english/typearea-experts.tex')
-rw-r--r-- | Master/texmf-dist/source/latex/koma-script/doc/english/typearea-experts.tex | 232 |
1 files changed, 118 insertions, 114 deletions
diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/typearea-experts.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/typearea-experts.tex index 62b95b60d48..da2679cc7de 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/typearea-experts.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/typearea-experts.tex @@ -1,6 +1,6 @@ % ====================================================================== % typearea-experts.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % typearea-experts.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,70 +46,71 @@ % ====================================================================== \KOMAProvidesFile{typearea-experts.tex} - [$Date: 2017-04-13 09:47:38 +0200 (Thu, 13 Apr 2017) $ + [$Date: 2018-03-30 11:57:25 +0200 (Fri, 30 Mar 2018) $ KOMA-Script guide (chapter: typearea)] -\translator{Markus Kohm\and Gernot Hassenpflug} +\translator{Markus Kohm\and Gernot Hassenpflug\and Karl Hagen} -% Date of the translated German file: 2017-04-13 +% Date of the translated German file: 2018-01-31 -\chapter{Additional Information about package \Package{typearea}} +\chapter{Additional Information about the \Package{typearea} package} \labelbase{typearea-experts} \BeginIndexGroup \BeginIndex{Package}{typearea} - -This chapter gives additional information about package -\Package{typearea}. \iffree{Some parts of the chapter are subject to the - \KOMAScript{} book \cite{book:komascript} only. This should not be a - problem, because the}{The} average user, who only want to use the package, -does not need the information that is addressed to users with non-standard -requirements or who want to write their own packages using -\Package{typearea}. Another part of the information describes features of -\Package{typearea} that exist only because of compatibility to former releases -of \KOMAScript{} or the standard classes. The features, that exist only -because of compatibility to former \KOMAScript{} releases, are printed with a -sans serif font. You should not use them any longer. +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, the function of a feature is not guarantied. There are two reasons for -this. First of all the final function is not yet defined or implementation is -not yet established. Second reason is, that a feature may depend on internal -functions of other packages and therefore the feature can not be guarantied, -if the other package changes. +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} simply ignores whether or not it is used in any -constellation with package \Package{geometry}\IndexPackage{geometry} (see -\cite{package:geometry}). This means, \Package{geometry} does not recognize -any page parameter change done with \Package{typearea}, especially if you -change the page size or page orientation\,---\,a feature not provided by -\Package{geometry} itself. +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 use \Package{typearea} inside the document, it even -calls \Macro{newgeometry}. But since \Package{geometry} does not provide -changes of page size or page orientation with \Macro{newgeometry}, -\Package{typearea} uses internal macros and lengths of \Package{geometry} to, -nevertheless, provide such changes. This has been tested with -\Package{geometry}~5.3 up to 5.6. +\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} and active \Option{usegeometry} does not mean, that -\Package{geometry} will automatically use the new paper size in an expected -manner. \Package{geometry} has an over estimated amount of options. So you -often need to set up the margins and size of typing area newly using -\Macro{newgeometry}, because otherwise the typing area may be to large or to -small. Nevertheless the combination of \Package{typearea} with option -\Option{usegeometry} and package \Package{geometry} can offer additional -features or at least option \Option{usegeometry} can improve the co-existence -of both packages.% +\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 @@ -117,42 +118,43 @@ of both packages.% \OptionVName{areasetadvanced}{simple switch} \Macro{areaset}\OParameter{BCOR}\Parameter{width}\Parameter{height} \end{Declaration} -Usually \DescRef{typearea.cmd.areaset} does not care for options to define -height of page header or page footer or whether or not margin elements should -be part of the typing area same like \DescRef{typearea.cmd.typearea}. With -option \Option{areasetadvance}\ChangedAt{v3.11}{\Package{typearea}} you can -change this at most. Nevertheless, settings that result in same size of typing -area still need not result in same top margin and bottom margin. This is, -because \DescRef{typearea.cmd.typearea} only changes the bottom margin to have -a integer number of lines in the typing area and -\DescRef{typearea.cmd.areaset} always sets the ratio 1:2 for top margin to -bottom margin. So the identical sizes of typing areas my be shifted vertically -a little bit depending on which command has been used.% +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 not of interest for average -users. Nevertheless these commands provide additional features for -experts. Because the information is addressed to experts it's condensed. +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}% -Package \Package{typearea} uses this command to assign settings of typing area -and margins to internal \LaTeX{} lengths, whenever the type area is newly -calculated inside of the document, i\.e., after -\Macro{begin}\PParameter{document}. If option -\DescRef{typearea.option.pagesize} has been used, it will be executed again -afterward. With this, e.\,g., the page size may vary inside of a PDF document. - -Experts may use this command, if they change lengths like \Length{textwidth} -or \Length{textheight} inside a document manually for any reason. Nevertheless -the expert himself is responsible for eventually needed page breaks before or -after usage of \Macro{activateareas}. Moreover all changes of -\Macro{activateareas} are local!% +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 @@ -164,14 +166,13 @@ after usage of \Macro{activateareas}. Moreover all changes of \Macro{AfterRestoreareas}\Parameter{code}% \Macro{AfterRestoreareas*}\Parameter{code} \end{Declaration} -With \Macro{storeareas} a \PName{\Macro{command}} will be defined that may be -used to restore all current settings of typing area and margins. This provides -to store the current settings, change them, do anything with valid changed -settings and restore the previous settings afterwards. +\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} - You want a landscape page inside a document with portrait format. No problem - using \Macro{storeareas}: + You want a landscape page inside a document with portrait format. That's + no problem using \Macro{storeareas}: \begin{lstcode} \documentclass[pagesize]{scrartcl} @@ -187,59 +188,62 @@ settings and restore the previous settings afterwards. \noindent\rule{\textwidth}{\textheight} \end{document} \end{lstcode} - Command \DescRef{maincls.cmd.clearpage}\textnote{Attention} before calling - \Macro{MySavedValues} is important to restore the saved values at the next - page. + It's\textnote{Attention} important to call \DescRef{maincls.cmd.clearpage} + before \Macro{MySavedValues} 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} -In the example \Macro{noindent} has been used to avoid the paragraph indent of -the black boxes. Without these commands the boxes would not show the -typing area correctly. -Please note\textnote{Attention!} that neither \Macro{storeareas} nor the -defined \PName{\Macro{command}} should be used inside a group. Internally +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 re-usage of a +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 +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*}. Analogously you can use \Macro{AfterRestoreareas} -or \Macro{AfterRestoreareas*} to automatically execute \PName{code} after -restoring the settings. The variants with and without star differs so that the -star variant changes only the auto-execution \PName{code} of future -\PName{command}s and the variant without star also changes the auto-execution -\PName{code} of already defined \PName{command}s. -% +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{instructions}% - \Macro{AfterCalculatingTypearea*}\Parameter{instructions}% - \Macro{AfterSettingArea}\Parameter{instructions}% - \Macro{AfterSettingArea*}\Parameter{instructions} + \Macro{AfterCalculatingTypearea}\Parameter{code}% + \Macro{AfterCalculatingTypearea*}\Parameter{code}% + \Macro{AfterSettingArea}\Parameter{cod}% + \Macro{AfterSettingArea*}\Parameter{code} \end{Declaration}% -These commands manage \emph{hooks}. \Macro{AfterCalculatingTypearea} and it's -star version provide experts to execute \PName{instructions} every time -\Package{typearea} has recalculated the typing area and margins either -implicitly or because of an explicit usage of -\DescRef{typearea.cmd.typearea}. Similar -\Macro{AfterSettingArea}\ChangedAt{v3.11}{\Package{typearea}} and it's star -version provide execution of \PName{instructions} every time -\DescRef{typearea.cmd.areaset} has been used. While normal versions work -globally the influence of the star versions is only local. The -\PName{instructions} will be executed instantly before execution of -\Macro{activateareas}.\iffree{}{ In \autoref{cha:modernletters} - \Macro{AfterCalculatingTypearea} will be used in letter class option - \File{asymTypB.lco} to change the division of the margins.}% +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 File \File{typearea.cfg}} +\section{Local Settings with the \File{typearea.cfg} File} \seclabel{cfg} \BeginIndexGroup \BeginIndex{File}{typearea.cfg} |