% ======================================================================
% 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-01-02 13:27:16 +0100 (Mon, 02 Jan 2017) $
                  KOMA-Script guide (chapter: typearea)]
\translator{Markus Kohm\and Gernot Hassenpflug}

% Date of the translated German file: 2017-01-02

\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 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} 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: 
