% ======================================================================
% 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:
