summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/koma-script/doc/scrhack-en.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/koma-script/doc/scrhack-en.tex')
-rw-r--r--macros/latex/contrib/koma-script/doc/scrhack-en.tex285
1 files changed, 285 insertions, 0 deletions
diff --git a/macros/latex/contrib/koma-script/doc/scrhack-en.tex b/macros/latex/contrib/koma-script/doc/scrhack-en.tex
new file mode 100644
index 0000000000..74b1999c00
--- /dev/null
+++ b/macros/latex/contrib/koma-script/doc/scrhack-en.tex
@@ -0,0 +1,285 @@
+% ======================================================================
+% 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: