summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/koma-script/doc/english/typearea-experts.tex
blob: 62b95b60d4816c3e3d9671f2b571d42e1c9aa9cb (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
% ======================================================================
% typearea-experts.tex
% Copyright (c) Markus Kohm, 2001-2017
%
% 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-2017
%
% 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: 2017-04-13 09:47:38 +0200 (Thu, 13 Apr 2017) $
                  KOMA-Script guide (chapter: typearea)]
\translator{Markus Kohm\and Gernot Hassenpflug}

% Date of the translated German file: 2017-04-13

\chapter{Additional Information about package \Package{typearea}}
\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.


\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.

\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.

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.

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.%
\EndIndexGroup


\begin{Declaration}
  \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.%
\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.

\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!%
% 
\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}
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.

\begin{Example}
  You want a landscape page inside a document with portrait format. No problem
  using \Macro{storeareas}:
\begin{lstcode}
  \documentclass[pagesize]{scrartcl}

  \begin{document}
  \noindent\rule{\textwidth}{\textheight}

  \storeareas\MySavedValues
  \KOMAoptions{paper=landscape,DIV=current}
  \noindent\rule{\textwidth}{\textheight}

  \clearpage
  \MySavedValues
  \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.
\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
\Macro{newcommand}\IndexCmd{newcommand*}\important{\Macro{newcommand*}} is
used to define the \PName{\Macro{command}}. So re-usage of 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*}. 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.
%
\EndIndexGroup


\begin{Declaration}
  \Macro{AfterCalculatingTypearea}\Parameter{instructions}%
  \Macro{AfterCalculatingTypearea*}\Parameter{instructions}%
  \Macro{AfterSettingArea}\Parameter{instructions}%
  \Macro{AfterSettingArea*}\Parameter{instructions}
\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.}%
% 
\EndIndexGroup


\section{Local Settings with File \File{typearea.cfg}}
\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: