summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/koma-script/source-doc/english/typearea-experts.tex
blob: 093b3f7a741ff4dbb35782eede114da60de5f4fa (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
% ======================================================================
% typearea-experts.tex
% Copyright (c) Markus Kohm, 2001-2021
%
% 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.
% ----------------------------------------------------------------------
% typearea-experts.tex
% Copyright (c) Markus Kohm, 2001-2021
%
% 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 typearea for experts of the KOMA-Script guide
% Maintained by Markus Kohm
%
% ----------------------------------------------------------------------
%
% Kapitel ueber typearea fuer Experten in der KOMA-Script-Anleitung
% Verwaltet von Markus Kohm
%
% ======================================================================

\KOMAProvidesFile{typearea-experts.tex}
                 [$Date: 2021-11-09 09:58:01 +0100 (Tue, 09 Nov 2021) $
                  KOMA-Script guide (chapter: typearea)]
\translator{Markus Kohm\and Gernot Hassenpflug\and Karl Hagen}

% Date of the translated German file: 2021-07-11

\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
%%% mode: flyspell
%%% ispell-local-dictionary: "english"
%%% coding: us-ascii
%%% TeX-master: "../guide"
%%% End: