path: root/macros/latex/contrib/koma-script/doc/scrhack-en.tex

% ======================================================================
% scrhack-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 scrhack of the KOMA-Script guide
% Maintained by Markus Kohm
%
% ============================================================================

\KOMAProvidesFile{scrhack-en.tex}
                 [$Date: 2022-06-05 12:40:11 +0200 (So, 05. Jun 2022) $
                  KOMA-Script guide (chapter: scrhack)]
\translator{Markus Kohm\and Karl Hagen}

\chapter{Improving Third-Party Packages with \Package{scrhack}}
\labelbase{scrhack}

\BeginIndexGroup
\BeginIndex{Package}{scrhack}
Some packages from other authors do not work well with \KOMAScript{}. It is
often very tedious for the author of \KOMAScript{} to convince the authors of
these packages to make specific improvements. This also applies to packages
whose development has been discontinued. That's why the \Package{scrhack} was
created. This package alters the commands and definitions of other to work
better with \KOMAScript{}. Some changes are also useful when using other
classes.

It is recommended to load the \Package{scrhack} package as early as
possible. In particular, loading should be done before the affected packages.

\section{Development Status}
\label{scr:scrhack.draft}

Although this package has been part of \KOMAScript{} for long time and is used
by many users, there's one problem with it. Redefining macros from third-party
packages depends on knowing the exact definition and use of those macros. This
also means that it depends on specific versions of those packages. If you use
a unknown version of such a package, \Package{scrhack} may not be able to
execute the required patch. In extreme cases, patching an unknown version can
lead to an error.

Because \Package{scrhack} must be continuously modified to accommodate new
releases of third-party packages, it can never be considered complete.
Therefore \Package{scrhack} will remain permanently in a beta version.
Although its use will generally be a benefit, its correct functioning cannot
be permanently guaranteed.

\LoadCommonFile{options}% \section{Early or late Selection of Options}

\section{Using \Package{tocbasic}}
\seclabel{improvement}

In the early days of \KOMAScript{}, users wanted to handle lists of floating
environments created with the
\Package{float}\IndexPackage{float}\important{\Package{float}} package in the
same way as the list of figures and list of tables created by \KOMAScript{}
itself. At that time the author of \KOMAScript{} contacted the author of
\Package{float} to propose an interface to support such an extension. A
somewhat modified form of that interface was implemented with the
\Macro{float@listhead}\IndexCmd[indexmain]{float@listhead} and
\Macro{float@addtolists}\IndexCmd[indexmain]{float@addtolists} commands.

Later it became apparent that these two commands were not flexible enough to
fully support all of \KOMAScript's capabilities. Unfortunately, the author of
\Package{float} had already ceased development by that point, so further
changes to this package cannot be expected.

Other package authors have also adopted these two commands, and it became
apparent that the implementation in some packages, including \Package{float},
means that all these packages can only be loaded in a specific order, even
though they are otherwise unrelated to each other.

To overcome all these disadvantages and problems, \KOMAScript{} no longer
officially supports this old interface. Instead, \KOMAScript{} warns if the
old interface is used. At the same time, the
\Package{tocbasic}\IndexPackage{tocbasic}\important{\Package{tocbasic}}
package (see \autoref{cha:tocbasic}) has been designed and implemented as a
central interface for managing of table of contents and similar content lists.
This package provides many more advantages and features than the two old
commands.

Although the effort to use this package is very small, so far the authors of
most of the packages that use the old interface have not made any adjustments.
Therefore \Package{scrhack} contains appropriate modifications of the
\Package{float}\IndexPackage{float}\important{\Package{float},
\Package{floatrow}, \Package{listings}},
\Package{floatrow}\IndexPackage{floatrow}, and
\Package{listings}\IndexPackage{listings} packages. Merely loading
\Package{scrhack} is sufficient to make these packages recognize not only the
setting of the \KOMAScript{} option
\DescRef{maincls.option.listof}\IndexOption{listof~=\PName{setting}}, but also
to react to the language switching features of the
\Package{babel}\IndexPackage{babel} package. You can find more information
about the features available by switching packages to \Package{tocbasic} in
\autoref{sec:tocbasic.toc}.

If you do not want this modification for any of the packages, or if it causes
problems, you can deactivate it selectively with the
\OptionValue{float}{false}\IndexOption[indexmain]{float~=\textKValue{false}},
\OptionValue{floatrow}{false}\IndexOption[indexmain]{floatrow~=\textKValue{false}},
or
\OptionValue{listings}{false}\IndexOption[indexmain]{listings~=\textKValue{false}}
option. Note\textnote{Attention!} that changing these options after loading
the associated package has no effect!


\section{Incorrect Assumptions about \Macro{@ptsize}}
\seclabel{ptsize}

Some packages assume that the class-internal macro
\Macro{@ptsize}\IndexCmd{@ptsize} both is defined and expands to an integer.
For compatibility, \KOMAScript{} defines \Macro{@ptsize} even if the basic
font size is something other than 10\Unit{pt}, 11\Unit{pt}, or 12\Unit{pt}.
\KOMAScript{} also allows non-integer font sizes. So \Macro{@ptsize} can, of
course, also expand to a non-integer number.

One\ChangedAt{v3.17}{\Package{scrhack}} of the packages that cannot cope with
a non-integer \Macro{@ptsize} is
\Package{setspace}\IndexPackage[indexmain]{setspace}. Additionally, the values
set by this package are always dependent on the basic font size, even if the
setting is made in the context of another font size. The \Package{scrhack}
package solves both problems by redefining \Macro{onehalfspacing} and
\Macro{doublespacing} to set the spacing relative to the actual font size.

If you do not want this modification for the package, or if it causes
problems, you can deactivate it selectively with the
\OptionValue{setspace}{false}\IndexOption[indexmain]{setspace~=\textKValue{false}}
option. Note\textnote{Attention!} that changing this option after loading
\Package{setspace} has no effect! Likewise, if you use \Package{setspace} with
either the \Option{onehalfspacing} or \Option{doublespacing} option, you must
load \Package{scrhack} first.


\section{Older Versions of \Package{hyperref}}
\seclabel{hyperref}

Versions of \Package{hyperref} before 6.79h set the link
anchors after the heading of the starred versions of commands like
\DescRef{maincls.cmd.part*}, \DescRef{maincls.cmd.chapter*}, etc. instead of
before them. Since then, this problem has been resolved at the suggestion of
\KOMAScript{}'s author. But because the change took more than a year, a patch
was added to \Package{scrhack}. Although this can also be deactivated with
\OptionValue{hyperref}{false}, you should instead use the current
\Package{hyperref} release. In this case \Package{scrhack} automatically
deactivates this unnecessary patch.%


\section{Inconsistent Handling of \Length{textwidth} and \Length{textheight}}
\seclabel{lscape}

The\ChangedAt{v3.18}{\Package{scrhack}}
\Package{lscape}\IndexPackage[indexmain]{lscape} package defines a
\Environment{landscape}\IndexEnv{landscape} environment to set the page
contents, but not the header or footer in landscape mode. Inside this
environment, \Length{textheight}\IndexLength{textheight} is set to the value
of \Length{textwidth}, but \Length{textwidth} is not set to the former value
of \Length{textheight}. This is inconsistent. As far as I know,
\Length{textwidth} is left unchanged because setting it to \Length{textheight}
could interfere with other packages or user commands. But changing
\Length{textheight} also has this potential, and indeed it breaks, for
example, \Package{showframe}\IndexPackage{showframe} and
\Package{scrlayer}\IndexPackage{scrlayer}. Thus it would be best if
\Length{textheight} too remained unchanged. \Package{scrhack} uses the
\Package{xpatch} package (see \cite{package:xpatch}) to modify the
\Macro{landscape} environment's start macro appropriately.

If you do not want this modification, or if it causes problems, you can
deactivate it with the
\OptionValue{lscape}{false}\IndexOption[indexmain]{lscape~=\textKValue{false}}
option. Note\textnote{Attention!} that changing \Option{lscape} subsequently
with \DescRef{\LabelBase.cmd.KOMAoption}\IndexCmd{KOMAoption} or
\DescRef{\LabelBase.cmd.KOMAoptions}\IndexCmd{KOMAoptions} has an effect only
if it was not \PValue{false} while loading \Package{lscape}.

Incidentally, the \Package{pdflscape}\IndexPackage[indexmain]{pdflscape}
package also uses \Package{lscape}, so \Package{scrhack} affects the
functioning of this package too.%


\section{Special Case for \Package{nomencl}}
\label{sec:nomencl}

The\ChangedAt{v3.23}{\Package{scrhack}} hack for the
\Package{nomencl}\IndexPackage[indexmain]{nomencl} represents a somewhat
special case. First, it ensures that the optional table of contents entry for
the nomenclature observes the \OptionValueRef{maincls}{toc}{indentunnumbered}
option. Somewhat incidentally, it also reserves the file extensions \File{nlo}
and \File{nls} for the owner \PValue{nomencl} (see
\DescRef{tocbasic.cmd.addtotoclist}, \autoref{sec:tocbasic.basics},
\DescPageRef{tocbasic.cmd.addtotoclist}).

It also changes the \Environment{thenomenclature}\IndexEnv{thenomenclature}
environment to use
\DescRef{tocbasic.cmd.tocbasic@listhead}\IndexCmd{tocbasic@listhead} for the
heading (see \autoref{sec:tocbasic.internals},
\DescPageRef{tocbasic.cmd.tocbasic@listhead}). In this way, the hack lets you
set various attribute for the \File{nls} extension using
\DescRef{tocbasic.cmd.setuptoc}\IndexCmd{setuptoc}%
\important{\DescRef{tocbasic.cmd.setuptoc}}. For example, not only can you
enter the nomenclature in the table of contents with
\DescRef{tocbasic.cmd.setuptoc}\PParameter{nls}\PParameter{numbered}, but you
can also number it immediately. You can find more about
\DescRef{tocbasic.cmd.setuptoc} and its available settings in
\autoref{sec:tocbasic.toc}, starting on \DescPageRef{tocbasic.cmd.setuptoc}. 
As a small but important side effect, this patch also gives the nomenclature
also matching running head, if automatic running heads are activated, for
example by using the \DescRef{maincls.pagestyle.headings} page style.

This rather simple patch is an example of how packages that do not define
floating environments can still benefit from \Package{tocbasic}. However, you
do not want this change, or if it causes problems, you can deactivate it with
the \OptionValue{nomencl}{false}%
\IndexOption[indexmain]{nomencl~=\textKValue{false}} option.
The\textnote{Achtung!} setting of the option when \Package{nomencl} is loaded
is crucial! Later changes to the option with
\DescRef{\LabelBase.cmd.KOMAoption} or \DescRef{\LabelBase.cmd.KOMAoptions}
have no influence and will lead to a corresponding warning.%


\section{Special Case for Section Headings}
\seclabel{sections}

Various\ChangedAt{v3.27}{\Package{scrhack}} packages assume that the
sectioning commands are defined in a specific way, corresponding to the
definitions in the standard classes. But for some classes this is not the
case. For example, the \KOMAScript{} classes use a completely different
implementation to provide many additional features. But this can cause
problems for packages that depend on the definition of the standard classes.
As of version~3.27, \Package{scrhack} offers the option to force the
sectioning commands \DescRef{maincls.cmd.part}\IndexCmd{part},
\DescRef{maincls.cmd.chapter}\IndexCmd{chapter},
\DescRef{maincls.cmd.section}\IndexCmd{section},
\DescRef{maincls.cmd.subsection}\IndexCmd{subsection},
\DescRef{maincls.cmd.subsubsection}\IndexCmd{subsubsection},
\DescRef{maincls.cmd.paragraph}\IndexCmd{paragraph}, and
\DescRef{maincls.cmd.subparagraph}\IndexCmd{subparagraph} to be compatible
with those in the standard classes. When \DescRef{maincls.cmd.chapter} is
defined, the definitions are based on those in \Class{book}. When
\DescRef{maincls.cmd.chapter} is undefined, the definitions of
\Class{article} are used.

If you are using a \KOMAScript{} class, several features of these classes are
also deactivated as side effect. For example, the commands to define or
modify sectioning commands described in
\autoref{sec:maincls-experts.sections} or option
\DescRef{maincls.option.headings} are no longer available, and commands like
\DescRef{maincls.cmd.partformat} have different defaults.

Because this hack has the potential to do more harm than good, it issues
several warnings. Also it is not activated simply by loading the
\Package{scrhack} package. If you want to use it, you must explicitly activate
it with the \Option{standardsections}\IndexOption[indexmain]{standardsections}
option when you load the package. Late activation or deactivation is not
supported.

Since there are often less invasive solutions to fix the problem of package
incompatibilities, using this hack is not recommended. It is provided only as
a last resort for emergencies.%
\EndIndexGroup

\endinput

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "scrguide-en.tex"
%%% coding: utf-8
%%% ispell-local-dictionary: "en_GB"
%%% eval: (flyspell-mode 1)
%%% End: