diff options
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.tex | 330 |
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 |