% ====================================================================== % scrhack.tex % Copyright (c) Markus Kohm, 2001-2021 % % 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. % ---------------------------------------------------------------------- % scrhack.tex % Copyright (c) Markus Kohm, 2001-2021 % % 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 scrhack of the KOMA-Script guide % Maintained by Markus Kohm % % ---------------------------------------------------------------------------- % % Kapitel ueber scrhack in der KOMA-Script-Anleitung % Verwaltet von Markus Kohm % % ============================================================================ \KOMAProvidesFile{scrhack.tex} [$Date: 2021-06-03 19:56:49 +0200 (Do, 03. Jun 2021) $ KOMA-Script guide (chapter: scrhack)] \translator{Markus Kohm\and Karl Hagen} % Date of the translated German file: 2021-06-03 \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 %%% mode: flyspell %%% ispell-local-dictionary: "english" %%% coding: us-ascii %%% TeX-master: "../guide" %%% End: