summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/koma-script/doc/english/scrhack.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/koma-script/doc/english/scrhack.tex')
-rw-r--r--Master/texmf-dist/source/latex/koma-script/doc/english/scrhack.tex330
1 files changed, 172 insertions, 158 deletions
diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrhack.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrhack.tex
index c45340f6dd8..a7dfac605c5 100644
--- a/Master/texmf-dist/source/latex/koma-script/doc/english/scrhack.tex
+++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrhack.tex
@@ -1,6 +1,6 @@
% ======================================================================
% scrhack.tex
-% Copyright (c) Markus Kohm, 2001-2017
+% Copyright (c) Markus Kohm, 2001-2018
%
% This file is part of the LaTeX2e KOMA-Script bundle.
%
@@ -18,7 +18,7 @@
% This work consists of all files listed in manifest.txt.
% ----------------------------------------------------------------------
% scrhack.tex
-% Copyright (c) Markus Kohm, 2001-2017
+% Copyright (c) Markus Kohm, 2001-2018
%
% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz,
% Version 1.3c, verteilt und/oder veraendert werden.
@@ -46,197 +46,211 @@
% ============================================================================
\KOMAProvidesFile{scrhack.tex}
- [$Date: 2017-03-31 12:00:24 +0200 (Fri, 31 Mar 2017) $
+ [$Date: 2018-03-27 11:46:14 +0200 (Tue, 27 Mar 2018) $
KOMA-Script guide (chapter: scrhack)]
-\translator{Markus Kohm}
+\translator{Markus Kohm\and Karl Hagen}
-% Date of the translated German file: 2017-01-02
-\chapter{Hacks for Third-Party Packages by Package \Package{scrhack}}
+% Date of the translated German file: 2018-02-05
+\chapter{Improving Third-Party Packages with \Package{scrhack}}
\labelbase{scrhack}
\BeginIndexGroup
\BeginIndex{Package}{scrhack}
-Some packages from other authors could have problems with \KOMAScript{}. In my
-opinion some packages could be improved. With some packages this makes only
-sense, if \KOMAScript{} was used. With some other packages the package author
-has another opinion. Sometimes proposals was never answered. Package
-\Package{scrhack} contains all those improvement proposals for other
-packages. This means, \Package{scrhack} redefines macros of packages from
-other authors! The redefinitions are only activated, if those packages were
-loaded. Users can prevent \Package{scrhack} from redefining macros of
-individual packages.
-
-\section{State of Development Note}
+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.
+
+\section{Development Status}
\label{scr:scrhack.draft}
-Though this package is part of \KOMAScript{} for long time and though it has
-been used by lot of users, there's one problem with it. While redefinition of
-macros of foreign packages, it depend on the exact definition an usage of
-those macros. This means additionally, that it depends on dedicated releases
-of those packages. If a unknown release of such a package will be used,
-\Package{scrhack} eventually could not do the needed patch. Contrary, in
-extreme cases the patch can cause errors and fault.
+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.
-So \Package{scrhack} has to be continuously modified to fit new releases of
-foreign packages and will never be finished. Because of this \Package{scrhack}
-will stay in beta state forever. Though the usage will generally be a
-benefit, the correct function could not be guaranteed forever.
+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{Usage of \Package{tocbasic}}
+\section{Using \Package{tocbasic}}
\seclabel{improvement}
-In the early days of \KOMAScript{} users asked for handling lists of floats,
-that will be generated using package
-\Package{float}\IndexPackage{float}\important{\Package{float}}, like list of
-figures and list of tables, that are generated by \KOMAScript{} itself. At
-that time the \KOMAScript{} author contacted the author of \Package{float}, to
-submit a proposal of an interface with support for such an extention. A
-somehow modified version of that interface has been implemented with commands
+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}.
-
-Sometimes later it has appeared, that those two commands were not flexible
-enough to support all of the comprehensive features supported by
-\KOMAScript. Unfortunately the author of \Package{float} has finalized the
-development already, so nobody should expect furthor changes of this package.
-
-Other package authors have also inherited these commands. Thereby it appeared,
-that the implementation in some packages, even in package \Package{float},
-will need a certain package loading order, though all these packages are not
-related to each other. Wrong loading order could result in an error or break the
-functionality of the commands.
-
-To clear all these disadvantages and problems, \KOMAScript{} officially does not
-support this old interface any more. Instead, \KOMAScript{} warns if the old
-interface is used. At the same time package
-\Package{tocbasic}\IndexPackage{tocbasic}\important{\Package{tocbasic}} (see
-\autoref{cha:tocbasic}) has been designed and implemented as a central
-interface for management of table of contents, lists of floats and similar
-lists. Usage of this package provides much more advantages and features than
-the two old commands that have been mentioned above.
-
-Though the effort using that package is very small, the authors of most of the
-packages, that are using the old interface, have not done so
-currently. Because of this \Package{scrhack} contains appropriate
-modifications of packages
+\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}, \Package{listings}},
\Package{floatrow}\IndexPackage{floatrow}, and
-\Package{listings}\IndexPackage{listings}. Loading \Package{scrhack} is enough
-to make these packages recognize not only setting of \KOMAScript{} option
+\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
-language switching of package \Package{babel}\IndexPackage{babel}. More
-information about the features provided by the changeover to package
-\Package{tocbasic} can be found in \autoref{sec:tocbasic.toc}.
-
-If the modification for any of the packages is not wanted or causes problems,
-then it can be deactivated selectively with option
-\OptionValue{float}{false}\IndexOption[indexmain]{float~=\PValue{false}},
-\OptionValue{floatrow}{false}\IndexOption[indexmain]{floatrow~=\PValue{false}},
+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~=\PValue{false}}.
-Please note\textnote{Attention!} that changing these options after loading the
-corresponding package would not do it!
+\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 Expectations to \Macro{@ptsize}}
+\section{Incorrect Assumptions about \Macro{@ptsize}}
\seclabel{ptsize}
-Some packages always expect that the class-internal macro
-\Macro{@ptsize}\IndexCmd{@ptsize} is not only defined but also expands to an
-integer. For compatibility, \KOMAScript{} defines \Macro{@ptsize} even if the
-basic font size is neither 10\Unit{pt} nor 11\Unit{pt} nor
-12\Unit{pt}. \KOMAScript{} also provides non-integer font sizes. So
-\Macro{@ptsize} can expand to a non-integer number, too.
-
-Package\ChangedAt{v3.17}{\Package{scrhack}}
-\Package{setspace}\IndexPackage[indexmain]{setspace} is one of the packages
-that fail with non-integer number expansion of \Macro{@ptsize}. Additionally
-the line stretching of that package always depends on the basic font size even
-if setting is made in the context of another font size. Package
-\Package{scrhack} solves both problems by redefining \Macro{onehalfspacing}
-and \Macro{doublespacing} using always the current font size while setting the
-stretch.
-
-If the modification for the package is not wanted or causes problems,
-then it can be deactivated selectively with option
-\OptionValue{setspace}{false}\IndexOption[indexmain]{setspace~=\PValue{false}}.
-Please note\textnote{Attention!} that changing these option after loading
-\Package{setspace} would not do it! If you use \Package{setspace} with
-either option \Option{onehalfspacing} or \Option{doublespacing} you have to
-load \Package{scrhack} before it.
-
-
-\section{Special Case \Package{hyperref}}
+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}
-Before version~6.79h package \Package{hyperref} set the link anchors after
-instead of before the heading of star version commands like
-\DescRef{maincls.cmd.part*}, \DescRef{maincls.cmd.chapter*}, and so on. In
-the meantime this problem have been solved at the \KOMAScript{} author's
-suggestion. But because the \KOMAScript{} author was not patient enough to
-wait more than a year for the change of \Package{hyperref}, a corresponding
-patch has been added to \Package{scrhack}. This can be deactivated by
-\OptionValue{hyperref}{false}. Nevertheless, it is recommended to use the
-current \Package{hyperref} release. In this case \Package{scrhack} does
-automatically deactivate the not longer needed patch.%
+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}
-Package\ChangedAt{v3.18}{\Package{scrhack}}
-\Package{lscape}\IndexPackage[indexmain]{lscape} defines an environment
-\Environment{landscape}\IndexEnv{landscape} to set the page contents but not
-head and foot landscape. Inside this environment it changes
-\Length{textheight}\IndexLength{textheight} to the value of
-\Length{textwidth}, but it does not change \Length{textwidth} to the former
-value of \Length{textheight}. This is inconsistent. As far as I know,
-\Length{textwidth} is unchanged because setting it to \Length{textheight}
-could blame other packages or user commands. But changing \Length{textheight}
-could also blame other packages or user commands and indeed it breaks, e.\,g.,
-\Package{showframe}\IndexPackage{showframe} and
-\Package{scrlayer}\IndexPackage{scrlayer}. So best would be, not to change
-\Length{textheight}, too. \Package{scrhack} uses package \Package{xpatch} (see
-\cite{package:xpatch}) to modify the environment start macro \Macro{landscape}
-appropriately.
-
-If the modification for the package is not wanted or causes problems,
-then it can be deactivated selectively with option
-\OptionValue{lscape}{false}\IndexOption[indexmain]{lscape~=\PValue{false}}.
-Please note\textnote{Attention!} that changing this option after loading
-\Package{lscape} has an effect only, if it is not \PValue{false} while
-loading \Package{lscape} respectively \Package{scrhack}, if
-\Package{scrhack} is loaded after \Package{lscape}.
-
-Please note\textnote{Attention!},
-\Package{pdflscape}\IndexPackage[indexmain]{pdflscape} also uses
-\Package{lscape} and therefore is influenced by \Package{scrhack}, too.%
+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 \Package{nomencl}}
\label{sec:nomencl}
-The\ChangedAt{v3.23}{\Package{scrhack}} hack for package
-\Package{nomencl}\IndexPackage[indexmain]{nomencl} is a somehow special
-case. First of all it extends \Package{nomencl}'s option \Option{intoc} to
-respect \KOMAScript's option
-\OptionValueRef{maincls}{toc}{indentunnumbered}. As a sidestep it also
-reserves the file extensions \File{nlo} and \File{nls} for package
-\Package{tocbasic} (see \DescRef{tocbasic.cmd.addtotoclist},
-\autoref{sec:tocbasic.basics},
-\DescPageRef{tocbasic.cmd.addtotoclist}). Furthermore, you can use several
-features for the file extension \File{nls} using
-\DescRef{tocbasic.cmd.setuptoc}. For example, you can use
-\DescRef{tocbasic.cmd.setuptoc}\PParameter{nls}\PParameter{numbered} to not
-only add an entry to the table of contents but also number the headings of the
-nomenclature. As an side effect the nomenclature also gets a running head if
-automatic running heads are activated, e.\,g., using page style
-\DescRef{maincls.pagestyle.headings}. All these extension are done by a small
-patch of environment \Environment{thenomenclature}.
-%
+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.%
\EndIndexGroup
\endinput