diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/koma-script/doc/english/tocbasic.tex')
-rw-r--r-- | Master/texmf-dist/source/latex/koma-script/doc/english/tocbasic.tex | 2479 |
1 files changed, 1288 insertions, 1191 deletions
diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/tocbasic.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/tocbasic.tex index 729122fa94c..446e8fedd1a 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/tocbasic.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/tocbasic.tex @@ -1,6 +1,6 @@ % ====================================================================== % tocbasic.tex -% Copyright (c) Markus Kohm, 2002-2017 +% Copyright (c) Markus Kohm, 2002-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. % ---------------------------------------------------------------------- % tocbasic.tex -% Copyright (c) Markus Kohm, 2002-2017 +% Copyright (c) Markus Kohm, 2002-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,75 +46,75 @@ % ====================================================================== \KOMAProvidesFile{tocbasic.tex} - [$Date: 2017-08-08 11:57:30 +0200 (Tue, 08 Aug 2017) $ + [$Date: 2018-03-30 11:57:25 +0200 (Fri, 30 Mar 2018) $ KOMA-Script guide (package tocbasic)] -% Date of the translated German file: 2017-08-08 +% Date of the translated German file: 2018-03-27 -\translator{Markus Kohm\and Arndt Schubert} +\translator{Markus Kohm\and Arndt Schubert\and Karl Hagen} -\chapter[{Management of Tables and Lists of Contents Using - \Package{tocbasic}}] - {Management of Tables and Lists of Contents Using - \Package{tocbasic}\protect\footnote{Translation of this chapter has been - made by the package author and needs editing!}} +\chapter{Managing Content Lists with \Package{tocbasic}} \labelbase{tocbasic} \BeginIndexGroup% \BeginIndex{Package}{tocbasic}% \BeginIndex{}{table of contents}% -\BeginIndex{}{list>of contents}% +\BeginIndex{}{content list}% \BeginIndex{}{file>extension}% -The main purpose of package \Package{tocbasic} is to provide features for -authors of classes and packages to create own tables or lists of contents like -the list of figures and the list of tables and thereby allow other classes or -packages some types of control over these. For examples package -\Package{tocbasic} delegates language control of all these tables and lists of -contents to package \Package{babel}\IndexPackage{babel} (see -\cite{package:babel}). So automatic change of language will be provided -inside all these tables and lists of contents. Using \Package{tocbasic} will -exculpate authors of classes and packages from implementation of such -features. +The main purpose of the \Package{tocbasic} package is to give authors of +packages and classes the ability to create their own tables or lists of +content, content lists for short, similar to the list of figures and the list +of tables, allowing classes and other packages some control over these lists. +The \Package{tocbasic} package also delegates control of the +language-dependent parts of these content lists to the +\Package{babel}\IndexPackage{babel} package (see \cite{package:babel}). Using +\Package{tocbasic} relieves package and class authors from the burden of +implementing such features themselves. + +As a minor side effect, the package can also be used to define new floating +environments, or floating environments like non-floating environments for +reference objects. For more details, after you read about the basic commands +in the next four sections, see the example in \autoref{sec:tocbasic.example}, +which is compactly summarized in \autoref{sec:tocbasic.declarenewtoc}. \KOMAScript{} itself uses \Package{tocbasic} not only for the table of -contents but also for the already mentioned lists of figures and -tables. In\textnote{TOC} this chapter we call all kinds of tables of contents -or lists of contents simply TOC\Index[indexmain]{TOC}. +contents but also for the already mentioned lists of figures and tables. \section{Basic Commands} \label{sec:tocbasic.basics} -Basic commands are used to handle a list of all file name -extensions\textnote{file name extension, table or list of contents} known for -files representing a table or list of contents. We call these auxiliary -files\Index{auxiliary file}\footnote{Here we do not talk about the - \File{aux}-file but the auxiliary files used indirect via the - \File{aux}-file, e.\,g., the \File{toc}-file, the \File{lof}-file, or the - \File{lot}-file.} TOC-files\textnote{TOC-file}\Index[indexmain]{TOC-file} -independent from the file name extension that is used. Entries to such files -are typically written using +The basic commands are primarily used to handle a list of all known file +extensions\textnote{file extension, content lists} that +represent a table or list of contents. We call these auxiliary +files\Index{auxiliary file}\footnote{The term \emph{auxiliary file} here + refers not to the main \File{aux} file but to the other internal files used + indirectly via the \File{aux} file, e.\,g. the \File{toc} file, the + \File{lof} file, or the \File{lot} file.} TOC files\textnote{TOC + file}\Index[indexmain]{TOC file} regardless of the file extension that is +actually used. Entries to such files are typically written using \Macro{addtocontents}\important{\Macro{addtocontents}, - \Macro{addcontentsline}} or \Macro{addcontentsline}. Later in this chapter -you will learn to know recommended, additional commands. There are also -commands to do something for all known extensions. Additionally, there are -commands to set or unset features of a file name extension or the file -represented by the extension. Typically an extension also has an -owner\textnote{file owner}. This owner may be a class or package or a term -decided by the author of the class or package using \Package{tocbasic}, -e.\,g., \KOMAScript{} uses the owner \texttt{float} for list of figures and -list of tables, and the file name of the class file as owner for the table of -contents. +\DescRef{\LabelBase.cmd.addxcontentsline}}, or +\DescRef{\LabelBase.cmd.addxcontentsline}. There are also commands to perform +actions on all of these file extensions. Additionally, there are commands to +set or unset features for the file associated with a given extension. +Typically an file extension also has an owner\textnote{file owner}. This owner +may be a class or package, or an identifier that the author of the class or +package using \Package{tocbasic} has chosen independently. For example, +\KOMAScript{} uses the owner \texttt{float} for the \File{lof} and \File{lot} +file extensions that are associated with the list of figures and list of +tables, respectively. For the table of contents, \KOMAScript{} uses the file +name of the class. \begin{Declaration} - \Macro{ifattoclist}\Parameter{extension}\Parameter{true - part}\Parameter{false part} + \Macro{ifattoclist}\Parameter{extension}\Parameter{then code}% + \Parameter{else code} \end{Declaration} -This command may be used to ask, whether or not a file name \PName{extension} -is already a known extension. If the \PName{extension} is already known the -\PName{true instructions} will be used, otherwise the \PName{false - instructions} will be used. +This command tests whether or not the \PName{extension} already exists in the +list of known file extensions. If the \PName{extension} is already known, the +\PName{then code} will be executed. Otherwise, the \PName{else code} will be +executed. \begin{Example} - Maybe you want to know if the file name extension ``\File{foo}'' is already - in use to report an error, if you can not use it: + Suppose you want to know if the file name extension ``\File{foo}'' is + already in use in order to report an error because it cannot be used: \begin{lstcode} \ifattoclist{foo}{% \PackageError{bar}{% @@ -138,39 +138,40 @@ is already a known extension. If the \PName{extension} is already known the \Macro{addtotoclist}\OParameter{owner}\Parameter{extension} \end{Declaration} This command adds the \PName{extension} to the list of known extensions. But -if the \PName{extension} is a known one already, then an error will be -reported to avoid double usage of the same \PName{extension}. - -If the optional argument, \OParameter{owner}, was given, this \PName{owner} -will be stored to be the owner of the \PName{extension}. If the optional -argument has been omitted, \Package{tocbasic} tries to find out the file name -of the current processed class or package and stores this as owner. -This\textnote{Attention!} will fail if \Macro{addtotoclist} was not used, -loading a class or package but using a command of a class or package after -loading this class or package. In this case the owner will be set to +if the \PName{extension} is known already, an error is reported to prevent +duplicate use of the same \PName{extension}. + +If you specify the optional \OParameter{owner} argument, the given +\PName{owner} for this file extension is also saved. If you omit the optional +argument, \Package{tocbasic} tries to determine the file name of the class or +package currently being processed and saves it as the owner. +This\textnote{Attention!} procedure only works if you call +\Macro{addtotoclist} while loading a class or package. It will fail if a user +calls \Macro{addtotoclist} afterwards. In this case, the owner is set to ``\PValue{.}''. -Please note\textnote{Attention!} that an empty \PName{owner} is not the same -like omitting the optional argument with the braces. An empty argument would -result in an empty owner. +Note\textnote{Attention!} that passing an empty \PName{owner} argument is not +the same as completely omitting the optional argument, including the square +brackets. An empty argument would also result in an empty owner. \begin{Example} - You want to add the extension ``\File{foo}'' to the list of known extension, - while loading your package with file name ``\File{bar.sty}'': + Suppose you want to add the extension ``\File{foo}'' to the list of known + file extensions while loading your package with the file name + ``\File{bar.sty}'': \begin{lstcode} \addtotoclist{foo} \end{lstcode}% - This will add the extension ``\PValue{foo}'' with owner ``\PValue{bar.sty}'' - to the list of known extensions, if it was not already in the list of known - extensions. If the class or another package already added the extension you - will get the error: + This will add the extension ``\PValue{foo}'' with the owner + ``\PValue{bar.sty}'' to the list of known extensions if this extension was + not already in the list. If the class or another package has already added + the extension, you will get the error: \begin{lstoutput} Package tocbasic Error: file extension `foo' cannot be used twice See the tocbasic package documentation for explanation. Type H <return> for immediate help. \end{lstoutput} - and after typing \texttt{h} and pressing the return key you will get the - help: + If you press the ``\texttt{h}'' key followed by return, you will get the + following help: \begin{lstoutput} File extension `foo' is already used by a toc-file, while bar.sty tried to use it again for a toc-file. @@ -178,49 +179,60 @@ result in an empty owner. or a mistake by the user. \end{lstoutput} - Maybe your package has a command, that creates list of files dynamically. In - this case you should use the optional argument of \Macro{addtotoclist} to - set the owner. + Perhaps your package also provides a command that dynamically generates a + content list. In this case, you should use the optional argument of + \Macro{addtotoclist} to specify the owner. \begin{lstcode} \newcommand*{\createnewlistofsomething}[1]{% \addtotoclist[bar.sty]{#1}% - % Do something more to make this list of something available + % Do something more to make this content list available } \end{lstcode} - If the user calls now, e.\,g., + Now if the user calls this command, for example with \begin{lstcode} \createnewlistofsomething{foo} \end{lstcode} - this would add the extension ``\PValue{foo}'' with the owner + this will add the extension ``\PValue{foo}'' with the owner ``\PValue{bar.sty}'' to the list of known extension or report an error, if the extension is already in use. \end{Example} -You may use any owner you want. But it should be unique! So, if you would -be, e.\,g., the author of package \Package{float} you could use for example -owner ``\PValue{float}'' instead of owner ``\PValue{float.sty}'', so the -\KOMAScript{} options for the list of figures and the list of tables will also -handle the lists of this package. Those are already added to the known -extensions when the option is used. This is because \KOMAScript{} already -registers file name extension ``\PValue{lof}'' for the list of figures and -file name extension ``\PValue{lot}'' for the list of tables with owner -``\PValue{float}'' and sets options for this owner. Package \Package{scrhack} -redefines some of package \Package{float}'s commands to do this.% +You can specify any \PName{owner} you want, but it must be unique. For +example, if you were the author of the \Package{float} package, you could +specify ``\PValue{float}'' instead of ``\PValue{float.sty}'' as the +\PName{owner}. In this case, the \KOMAScript{} +options\important{\DescRef{maincls.option.listof}}% +\IndexOption{listof~=\PName{setting}} for the list of figures and the list of +tables would also affect your content lists because these lists are already +added to the list of known file extensions at the time the option is set, and +\KOMAScript{} associates the file extensions ``\PValue{lof}'' for the list of +figures and ``\PValue{lot}'' for the list of tables with the owner +``\PValue{float}'' and sets the options for this owner. + +By the way, the \hyperref[cha:scrhack]{\Package{scrhack}}% +\IndexPackage{scrhack}\important{\hyperref[cha:scrhack]{\Package{scrhack}}} +package contains patches for several packages, such as \Package{float} or +\Package{listings}, which provide their own content lists. If you use +\hyperref[cha:scrhack]{\Package{scrhack}}, among other things, the respective +file extensions will be added to the list of known file extensions. Their +\PName{owner} is also ``\PValue{float}''. This is the basic building block, so +to speak, allowing you to use the features of \Package{tocbasic} and the +\KOMAScript{} classes with these content lists as well.% \EndIndexGroup \begin{Declaration} - \Macro{AtAddToTocList}\OParameter{owner}\Parameter{instructions} + \Macro{AtAddToTocList}\OParameter{owner}\Parameter{commands} \end{Declaration} -This command adds the \PName{instructions} to an internal list of instructions -that will be processed whenever a file name extension with the given -\PName{owner} will be added to the list of known extensions using -\DescRef{\LabelBase.cmd.addtotoclist}. The optional argument is handled in the same way as -with the command \DescRef{\LabelBase.cmd.addtotoclist}. With an empty \PName{owner} you may -add \Parameter{instructions}, that will be processed at every successful -\DescRef{\LabelBase.cmd.addtotoclist}, after processing the instructions for the individual -owner. While processing the \PValue{instructions}, -\Macro{@currext}\IndexCmd{@currext}\important{\Macro{@currext}} will be set to -the extension of the currently added extension. +This command adds the \PName{commands} to an internal list of commands that +will be processed whenever a file extension with the specified \PName{owner} +is added to the list of known extensions with +\DescRef{\LabelBase.cmd.addtotoclist}. The optional argument is handled in the +same way as in the \DescRef{\LabelBase.cmd.addtotoclist} command. If you leave +the optional argument blank, the commands will always be executed, regardless +of the owner, every time a new file extension is added to the list of known +file extensions. Furthermore, while processing the \PValue{commands}, +\Macro{@currext}\IndexCmd{@currext}\important{\Macro{@currext}} is set to the +extension of the extension currently being added. \begin{Example} \Package{tocbasic} itself uses \begin{lstcode} @@ -229,14 +241,15 @@ the extension of the currently added extension. \expandafter{\@currext}% } \end{lstcode} - to add every extension to the \Package{tocbasic}-internal babel handling of - files. + to add every file extension to the existing \Package{tocbasic} integration + with the \Package{babel} package. \end{Example} -The two \Macro{expandafter} commands are needed, because the argument of -\DescRef{\LabelBase.cmd.tocbasic@extend@babel} has to be expanded! See the description of -\DescRef{\LabelBase.cmd.tocbasic@extend@babel} at \autoref{sec:tocbasic.internals}% -, \DescPageRef{\LabelBase.cmd.tocbasic@extend@babel} for more information.% +The two \Macro{expandafter} commands in the example are needed because the +argument of \DescRef{\LabelBase.cmd.tocbasic@extend@babel} has to be expanded. +See the description of \DescRef{\LabelBase.cmd.tocbasic@extend@babel} in +\autoref{sec:tocbasic.internals}, +\DescPageRef{\LabelBase.cmd.tocbasic@extend@babel} for more information.% \EndIndexGroup @@ -244,296 +257,316 @@ The two \Macro{expandafter} commands are needed, because the argument of \Macro{removefromtoclist}\OParameter{owner}\Parameter{extension} \end{Declaration} This command removes the \PName{extension} from the list of known extensions. -If the optional argument, \OParameter{owner}, was given, the \PName{extension} -will only be removed if it was added by this \PName{owner}. See description of -\DescRef{\LabelBase.cmd.addtotoclist} for information of omitting optional argument. Note that -an empty \PName{owner} is not the same like omitting the optional argument, -but removes the \PName{extension} without any owner test.% +If the optional argument, \OParameter{owner}, is given, the \PName{extension} +will only be removed if it was added by this \PName{owner}. See +\DescRef{\LabelBase.cmd.addtotoclist} for an explanation of how the list owner +is determined if the optional argument is omitted. If you specify an empty +\PName{owner}, the owner is not tested and the \PName{extension} is removed +regardless of the owner.% \EndIndexGroup \begin{Declaration} - \Macro{doforeachtocfile}\OParameter{owner}\Parameter{instructions} + \Macro{doforeachtocfile}\OParameter{owner}\Parameter{commands} \end{Declaration} -Until now you've learned to know commands that result in more safety in -handling file name extensions, but also needs some additional effort. With -\Macro{doforeachtocfile} you will win for this. The command provides to -processes \PName{instructions} for every known file name extension of the -given \PName{owner}. While processing the \PName{instructions} -\Macro{@currext} is the extension of the current file. If you omit the -optional argument, \OParameter{owner}, every known file name extension -independent from the owner will be used. If the optional argument is empty, -only file name extensions with an empty owner will be processed. +To this point, we've introduced commands provide additional security for class +and package authors, but also more overhead. With \Macro{doforeachtocfile}, +you can reap the first benefit for this. This command lets you execute the +specified \PName{commands} for each file extension associated with an +\PName{owner}. While processing the \PName{commands}, \Macro{@currext} is the +extension of the current file. If you omit the optional \OParameter{owner} +argument, all file extensions are processed regardless of the owner. If the +optional argument is empty, on the other hand, only extensions with an empty +owner will be processed. \begin{Example} - If you want to type out all known extensions, you may simply write: + If you want to output a list of all known file extensions to the terminal + and to the \File{log} file, you can easily accomplish this: \begin{lstcode} \doforeachtocfile{\typeout{\@currext}} \end{lstcode} - and if only the extensions of owner ``\PValue{foo}'' should be typed out: + If, on the other hand, you only want to output the extensions owned by + ``\PValue{foo}'', this too is easy: \begin{lstcode} \doforeachtocfile[foo]{\typeout{\@currext}} \end{lstcode} \end{Example} +The \KOMAScript{} classes \Class{scrbook} and \Class{scrreprt} use this +command to optionally put a vertical skip or the chapter heading in content +lists using the \PValue{chapteratlist} feature. You can learn how to set this +feature in \autoref{sec:tocbasic.toc} on +\DescPageRef{\LabelBase.cmd.setuptoc}.% \EndIndexGroup \begin{Declaration} \Macro{tocbasicautomode} \end{Declaration} -This command redefines \LaTeX{} kernel macro \Macro{@starttoc} to add all not -yet added extensions to the list of known extensions and use -\DescRef{\LabelBase.cmd.tocbasic@starttoc} instead of \Macro{@starttoc}. See -\autoref{sec:tocbasic.internals}, +This command redefines \LaTeX{} kernel macro \Macro{@starttoc} for class and +package authors so that every time \Macro{@starttoc} is called, the specified +file extension is added to the list of known extensions, if it has not already +been added. It also uses \DescRef{\LabelBase.cmd.tocbasic@starttoc} instead of +\Macro{@starttoc}. See \autoref{sec:tocbasic.internals}, \DescPageRef{\LabelBase.cmd.tocbasic@starttoc} for more information about \DescRef{\LabelBase.cmd.tocbasic@starttoc} and \Macro{@starttoc}. -This means that after using \Macro{tocbasicautomode} every table of contents -or list of something, that will be generated using \Macro{@starttoc} will be -at least partially under control of \Package{tocbasic}. Whether or not this -will make the wanted result, depends on the individual TOC. At least the -\Package{babel} control extension for all those TOCs will work. Nevertheless, -it would be better if the author of the corresponding class or package will -use \Package{tocbasic} explicitly. In that case additional advantages of -\Package{tocbasic} may be used that will be described at the following -sections.% +After you use \Macro{tocbasicautomode}, every content list created with +\Macro{@starttoc} is automatically put under the control of +\Package{tocbasic}. Whether or not this leads to the desired result, however, +depends very much on the individual content list. The \Package{babel} package +extensions, at least, will work for all those content lists. Nevertheless, it +is preferable for the class or package authors to use \Package{tocbasic} +explicitly. That way they can also take advantage of the other features of +\Package{tocbasic}, which are described in the following sections.% \EndIndexGroup -\section{Creating a Table or List of Contents} +\section{Creating a Content List} \label{sec:tocbasic.toc} -In the previous section you've seen commands to handle a list of known file -name extensions and to trigger commands while adding a new extension to this -list. You've also seen a command to do something for all known extensions or -all known extensions of one owner. In this section you will learn to know -commands to handle the file corresponding with an extension or the list of -known extensions. +In the previous section, you learned how to maintain a list of known file +extensions and how to automatically execute commands when adding new +extensions to this list. You also saw a command that can be used to execute +instructions for all known extensions or all extensions belonging to one +owner. In this section, you will learn commands that apply to the files +associated with these file extensions. \begin{Declaration} \Macro{addtoeachtocfile}\OParameter{owner}\Parameter{content} \end{Declaration} -This command writes \PName{content} to the TOC-files\Index{TOC} of every known -file name extension of \PName{owner} using \LaTeX{} kernel command -\Macro{addtocontents}. If you omit the optional argument, \PName{content} is -written to the files of every known file name extension. Furthermore, the -practical file name is built from \Macro{jobname} and the file name -extension. While writing the \PName{content}, +The \Macro{addtoeachtocfile} command uses the \LaTeX{} kernel command +\Macro{addtocontents} to write the \PName{content} to every TOC file\Index{TOC +file} in the list of known file extensions that has the specified +\PName{owner}. If you omit the optional argument, the \PName{content} is +written to each file in the list of known file extensions. Incidentally, the +actual file name is constructed from \Macro{jobname} and the file extension. +While writing the \PName{content}, \Macro{@currext}\IndexCmd{@currext}\important{\Macro{@currext}} is the -extension of the currently handled file. +extension of the file currently being processed. \begin{Example} - You may add a vertical space of one text line to all toc-files. + You want to add a vertical space of one line to all TOC files. \begin{lstcode} \addtoeachtocfile{% \protect\addvspace{\protect\baselineskip}% } \end{lstcode} - And if you want to do this, only for the TOC-files of owner - ``\PValue{foo}'': + If, on the other hand, you want to do this only for the files that have the + owner ``\PValue{foo}'', use: \begin{lstcode} \addtoeachtocfile[foo]{% \protect\addvspace{\protect\baselineskip}% } \end{lstcode} \end{Example} -Commands, that shouldn't be expanded while writing, should be prefixed by -\Macro{protect} in the same way like they should be in the argument of +You should protect commands that should not be expanded when they are written +by prefixing them with \Macro{protect}, in the same way as you would in \Macro{addtocontents}. \EndIndexGroup \begin{Declaration} \Macro{addxcontentsline}% - \Parameter{extension}\Parameter{level}\OParameter{number}% + \Parameter{extension}\Parameter{level}\OParameter{section number}% \Parameter{text} \end{Declaration} -The command \Macro{addxcontentsline} adds an entry of given \PName{level} to -TOC-file with file name \PName{extension}. If the \Parameter{number} is empty -or omitted the entry will not have number for the entry with the given -\PName{text}. Entries without number may be left aligned to the number of the -numbered entries of the same \PName{level} or indented like the text of the -numbered entries of the same \PName{level}, depending on the -\PValue{numberline} feature. - -\begin{Example} - Maybe you are not using a \KOMAScript{} class but need a not numbered - chapter with entry to the table of contents. This may be done using -\begin{lstcode} - \cleardoublepage - \csname phantomsection\endcsname - \addxcontentsline{toc}{chapter} - {Chapters without Numbers} - \chapter*{Chapters without Numbers} - \markboth{Chapters without Numbers}{} -\end{lstcode} - As you can see, you simply have to replace usual \Macro{addcontentsline} by - \Macro{addxcontentsline} to support the \Package{tocbasic} feature - \PValue{numberline}. -\end{Example} - -Note that \Macro{addxcontentsline} uses -\Macro{add\PName{level}\PName{extension}entry} if such a macro exists and -\DescRef{\LabelBase.cmd.tocbasic@addxcontentsline} otherwise. Therefore you cannot define -a macro \Macro{add\PName{level}\PName{extension}entry} using -\Macro{addxcontentsline} but \DescRef{\LabelBase.cmd.tocbasic@addxcontentsline}. +This command is very similar to +\Macro{addcontentsline}\IndexCmd{addcontentsline} from the \LaTeX{} kernel. +However, it has an additional optional argument for the \PName{section number} +of the entry, whereas for \Macro{addcontentsline}, it is specified in the +\PName{text} argument. It is used to include numbered or unnumbered entries in +the content list specified by the file \PName{extension}, where \PName{level} +is the sectioning level and \PName{text} is the content of the corresponding +entry. The page number is determined automatically. + +In contrast to \Macro{addcontentsline}, \Macro{addxcontentsline} first tests +whether the \Macro{add\PName{level}\PName{extension}entry} command is defined. +If so, it will be used for the entry, passing the \PName{section number} as an +optional argument and \PName{text} as a mandatory argument. You can find an +example of such a command provided by the \KOMAScript{} classes in +\DescRef{maincls-experts.cmd.addparttocentry} (see +\autoref{sec:maincls-experts.experts}, +\DescPageRef{maincls-experts.cmd.addparttocentry}). If the corresponding +command is undefined, the internal command +\DescRef{\LabelBase.cmd.tocbasic@addxcontentsline} is used instead. This takes +all four arguments as mandatory arguments and then uses +\Macro{addcontentsline} to create the desired entry. You can find more about +\DescRef{\LabelBase.cmd.tocbasic@addxcontentsline} in +\autoref{sec:tocbasic.internals}, +\DescPageRef{\LabelBase.cmd.tocbasic@addxcontentsline}. -It is recommended to use \Macro{addxcontentsline} instead of -\Macro{addcontentsline} whenever possible.% +One advantage of using \Macro{addxcontentsline} rather than +\Macro{addcontentsline} is that the \PValue{numberline} feature is respected +(see \DescPageRef{\LabelBase.cmd.setuptoc}). Furthermore, you can configure +the form of the entries by defining the appropriate commands specific to the +\PName{level} and file \PName{extension}.% +% \EndIndexGroup \begin{Declaration} - \Macro{addcontentslinetoeachtocfile}\OParameter{owner}\Parameter{level}% - \Parameter{contentsline}% - \Macro{addxcontentslinetoeachtocfile}\OParameter{owner}% - \Parameter{level}\OParameter{number}\Parameter{text} + \Macro{addxcontentslinetoeachtocfile}\OParameter{owner} + \Parameter{level} + \OParameter{section number}% + \Parameter{text} + \Macro{addcontentslinetoeachtocfile}\OParameter{owner} + \Parameter{level}\Parameter{text}% \end{Declaration} -The first command is something like \Macro{addcontentsline} from \LaTeX{} -kernel. In difference to that it writes the \PName{contentsline} not only into -one file, but into all files of all known file name extensions or of all known -file name extensions of a given owner. - -The command \Macro{addxcontentslinetoeachtocfile} is similar but uses -\DescRef{\LabelBase.cmd.addxcontentsline} instead of \Macro{addcontentsline} and -therefore supports \Package{tocbasic} feature \PValue{numberline}. +These two commands are directly related to +\DescRef{\LabelBase.cmd.addxcontentsline}\ChangedAt{v3.12}{\Package{tocbasic}} +explained above, or to \Macro{addcontentsline} from the \LaTeX kernel. The +difference is that these statements write \PName{text} not just to a single +file but to all the files of a given \PName{owner} and, if the first optional +argument is omitted, to all files in the list of known file extensions. \begin{Example} - You are a class author and want to write the chapter entry not only to the - table of contents TOC-file but to all TOC-files, while \texttt{\#1} is the - title, that should be written to the files. + Suppose you are a class author and you want to write the chapter entry not + just in the table of contents but in all content-list files. Suppose further + that \PValue{\#1} currently contains the text to be written. \begin{lstcode} - \addxcontentslinetoeachtocfile - {chapter}[\thechapter]{#1}% + \addxcontentslinetoeachtocfile{chapter}% + [\thechapter]{#1} \end{lstcode} - In this case the current chapter number should be expanded while writing - into the file. So it isn't protected from expansion using \Macro{protect}. + In this case, of course, the current chapter number should be expanded + directly when writing to the TOC file, which is why it was not protected + from expansion with \Macro{protect}. \end{Example} -While writing \Macro{@currext}\IndexCmd{@currext}\important{\Macro{@currext}} -is the file name extension of the file into which \PName{contentsline} will be -written. - -It is recommended to use \Macro{addxcontentslinetoeachtocfile} instead -of \Macro{addcontentslinetoeachtocfile} whenever possible. +While writing the \PName{content}, +\Macro{@currext}\IndexCmd{@currext}\important{\Macro{@currext}} here is also +the extension of the file being written to, as it is with +\DescRef{\LabelBase.cmd.addtoeachtocfile}.% + +Whenever\ChangedAt{v3.12}{\Package{tocbasic}} possible, the +\Macro{addxcontentslinetoeachtocfile} command is preferable to +\Macro{addcontentslinetoeachtocfile} because only the former offers the +enhancements of \DescRef{\LabelBase.cmd.addxcontentsline}. You can find more +about these enhancements and benefits in the explanation of +\DescRef{\LabelBase.cmd.addxcontentsline} above.% +% \EndIndexGroup \begin{Declaration} - \Macro{listoftoc}\OParameter{list of title}\Parameter{extension}% + \Macro{listoftoc}\OParameter{list-of title}\Parameter{extension}% \Macro{listoftoc*}\Parameter{extension}% \Macro{listofeachtoc}\OParameter{owner}% \Macro{listof\PName{extension}name} \end{Declaration} -These commands may be used to print the TOC corresponding to file name -\PName{extension}. The\important{\Macro{listoftoc*}} star version -\Macro{listoftoc*} needs only one argument, the \PName{extension} of the -file. It does setup the vertical and horizontal spacing of paragraphs, calls -before hooks, reads the file, and last but not least calls the after hooks. -You may interpret it as direct replacement of the \LaTeX{} kernel macro +You can use these commands to print the content lists. +The\important{\Macro{listoftoc*}} stared version \Macro{listoftoc*} needs only +one argument, the \PName{extension} of the file. The command first initializes +the vertical and horizontal spacing of paragraphs, calls the hook to execute +commands before reading the file, then reads the file, and finally executes +the hook to execute commands after reading the file. Thus you can think of +\Macro{listoftoc*} as a direct replacement for the \LaTeX{} kernel macro \Macro{@starttoc}\IndexCmd{@starttoc}\important{\Macro{@starttoc}}. -The\important{\Macro{listoftoc}} version without star, prints the whole file -with title, optional table of contents entry, and running heads. If the -optional argument \OParameter{list of title} was given, it will be used as -title term, optional table of contents entry and running head. Please -note\textnote{Attention!}: If the optional argument is empty, this term will -be empty, too! If you omit the optional argument, but -\Macro{listof\PName{extension}name} was defined, that will be used. If that is -also not defined, a standard replacement name will be used and reported by a -warning message. - -The\important{\Macro{listofeachtoc}} command \Macro{listofeachtoc} outputs all -lists of something of the given \PName{owner} or of all known file -extensions. Thereby\textnote{Attention!} -\Macro{listof\PName{extension}name} should be defined to get the correct -titles. - -It\textnote{Hint!} is recommended to define -\Macro{listof\PName{extension}name} for all used file name extensions, because -the user itself may use \Macro{listofeachtoc}. +The\important{\Macro{listoftoc}} version of \Macro{listoftoc} without the star +prints the complete content list and also creates an optional entry in the +table of contents and the running heads. If you provide the optional +\OParameter{list-of title} argument, it is used both as the title for the list +and as an optional entry in the table of contents and the running head. +If\textnote{Attention!} the \OParameter{list-of title} argument is empty, the +title will be empty too. If, on the other hand, you completely omit the +optional argument, including the square brackets, the +\Macro{listof\PName{extension}name} command will be used if it is defined. If +it is undefined, a default replacement name is used and a warning is issued. + +The\important{\Macro{listofeachtoc}} \Macro{listofeachtoc} command outputs all +content lists associated with the given \PName{owner}, or of all known file +extensions if the optional argument is omitted. To\textnote{Attention!} output +the correct titles, \Macro{listof\PName{extension}name} should be defined. + +You\textnote{Hint!} should define \Macro{listof\PName{extension}name} +appropriately for all file extensions because users may use \Macro{listoftoc} +without the optional argument, or \Macro{listofeachtoc}, themselves. \begin{Example} - Assumed, you have a new ``list of algorithms'' with extension \PValue{loa} - and want to show it: + Suppose you have a new ``list of algorithms'' with the file extension + \PValue{loa} and want to output it. The command \begin{lstcode} \listoftoc[List of Algorithms]{loa} \end{lstcode} - will do it for you. But maybe the ``list of algorithms'' should not be set - with a title. So you may use + will do it for you. If, however, you want to output this list without a + title, you could use \begin{lstcode} \listof*{loa} \end{lstcode} - Note that in this case no entry at the table of contents will be created, - even if you'd used the setup command above. - See command \DescRef{\LabelBase.cmd.setuptoc} - at \DescPageRef{\LabelBase.cmd.setuptoc} - for more information about the - attribute of generating entries into the table of contents using - \DescRef{\LabelBase.cmd.setuptoc}. - - If you've defined + In the second case, of course, there will be no entry in the table of + contents. For more information about creating entries in the table of + contents, see the \DescRef{\LabelBase.cmd.setuptoc} command on + \DescPageRef{\LabelBase.cmd.setuptoc}. + + If you have defined \begin{lstcode} \newcommand*{\listofloaname}{% List of Algorithms% } \end{lstcode} - before, then + already, then \begin{lstcode} \listoftoc{loa} \end{lstcode} - would be enough to print the list of algorithms with the wanted heading. For - the user it may be easier to operate, if you'd define + will suffice to print the content list with the desired heading. It may be + easier for users to remember if you also define a simple list-of command: \begin{lstcode} \newcommand*{\listofalgorithms}{\listoftoc{loa}} \end{lstcode} - additionally. \end{Example} Because\textnote{Attention!} \LaTeX{} normally opens a new file for each of -those lists of something immediately, the call of each of those commands may +these content lists, calling each of these commands may result in an error like: \begin{lstoutput} ! No room for a new \write . \ch@ck ...\else \errmessage {No room for a new #3} \fi \end{lstoutput} -if there are no more write handles left. Loading package +if there are no more write handles left. Loading the \Package{scrwfile}\important{\Package{scrwfile}}\IndexPackage{scrwfile} -(see \autoref{cha:scrwfile}) -may solve this problem. +package (see \autoref{cha:scrwfile}) can solve this problem. + +Also, the \hyperref[cha:scrhack]{\Package{scrhack}}\IndexPackage{scrhack}% +\important{\hyperref[cha:scrhack]{\Package{scrhack}}} package contains patches +for several packages, such as \Package{float} or \Package{listings}, so that +their content-list commands can use \Macro{listoftoc}. As a result, many +features of \Package{tocbasic} and the \KOMAScript{} classes are also +available for their content lists.% \EndIndexGroup \begin{Declaration} - \Macro{BeforeStartingTOC}\OParameter{extension}\Parameter{instructions}% - \Macro{AfterStartingTOC}\OParameter{extension}\Parameter{instructions} + \Macro{BeforeStartingTOC}\OParameter{extension}\Parameter{commands}% + \Macro{AfterStartingTOC}\OParameter{extension}\Parameter{commands} \end{Declaration} -Sometimes it's useful, to process \PName{instructions} immediately before -reading the auxiliary file of a TOC. These commands may be used to process -\PName{instructions} before or after loading the file with given -\PName{extension} using \DescRef{\LabelBase.cmd.listoftoc*}, \DescRef{\LabelBase.cmd.listoftoc}, or -\DescRef{\LabelBase.cmd.listofeachtoc}. If you omit the optional argument (or set an empty -one) the general hooks will be set. The general before hook will be called -before the individuel one and the general after hook will be called after the -individuel one. While calling the hooks +Sometimes it's useful to be able to execute \PName{commands} immediately +before reading the auxiliary TOC file. With \Macro{BeforeStartingTOC} you can +do so either for a single file \PName{extension} or for all files that are +read using \DescRef{\LabelBase.cmd.listoftoc*}, +\DescRef{\LabelBase.cmd.listoftoc}, or \DescRef{\LabelBase.cmd.listofeachtoc}. +You can also execute \PName{commands} after reading the file if you define +them with \Macro{AfterStartingTOC}. If you omit the optional argument (or set +an empty one) a general hook will be set and the commands will be applied to +all content lists. The general before-hook is called before the individual +one, and the general after-hook is called after the individual one. While +executing the commands in these hooks, \Macro{@currext}\IndexCmd{@currext}\important{\Macro{@currext}} is the -extension of the TOC-file and should not be changed. +extension of the TOC file which is about to be or has just been read. -An example\textnote{Example} for usage of \Macro{BeforeStartingTOC} may be -found in \autoref{sec:scrwfile.clonefilefeature} at +You can find an example\textnote{Example} using \Macro{BeforeStartingTOC} in +\autoref{sec:scrwfile.clonefilefeature} on \PageRefxmpl{scrwfile.cmd.BeforeStartingTOC}. +% \EndIndexGroup \begin{Declaration} - \Macro{BeforeTOCHead}\OParameter{extension}\Parameter{instructions}% - \Macro{AfterTOCHead}\OParameter{extension}\Parameter{instructions} + \Macro{BeforeTOCHead}\OParameter{extension}\Parameter{commands}% + \Macro{AfterTOCHead}\OParameter{extension}\Parameter{commands} \end{Declaration} -This commands may be used to process \PName{instructions} before or after -setting the title of a TOC corresponding to given file name \PName{extension} -using \DescRef{\LabelBase.cmd.listoftoc*} or -\DescRef{\LabelBase.cmd.listoftoc}. If you omit the optional argument (or set -an empty one) the general hooks will be set. The general before hook will be -called before the individuel one and the general after hook will be called -after the individuel one. While calling the hooks -\Macro{@currext}\IndexCmd{@currext}\important{\Macro{@currext}} is the -extension of the corresponding file and should not be changed. +You can also define \PName{commands} that will be executed immediately before +or after setting the title of a content list using +\DescRef{\LabelBase.cmd.listoftoc*} or \DescRef{\LabelBase.cmd.listoftoc}. The +treatment of the optional parameter and the meaning of +\Macro{@currext}\IndexCmd{@currext}\important{\Macro{@currext}} is the same as +described for \DescRef{\LabelBase.cmd.BeforeStartingTOC} and +\DescRef{\LabelBase.cmd.AfterStartingTOC}.% \EndIndexGroup @@ -541,56 +574,56 @@ extension of the corresponding file and should not be changed. \Macro{MakeMarkcase}\Parameter{text} \end{Declaration} Whenever \Package{tocbasic} sets a mark for a running head, The text of the -mark will be an argument of \Macro{MakeMarkcase}. This command may be used, to -change the case of the letters at the running head if wanted. The default is, -to use -\Macro{@firstofone}\IndexCmd{@firstofone}\important{\Macro{@firstofone}} for -\KOMAScript{} classes. This means the text of the running head will be set -without change of case. -\Macro{MakeUppercase}\IndexCmd{MakeUppercase}\important{\Macro{MakeUppercase}} -will be used for all other classes. If you are the class author you may define -\Macro{MakeMarkcase} on your own. If \Package{scrlayer} or another package, -that defines \Macro{MakeMarkcase} will be used, \Package{tocbasic} will not -overwrite that definition. +mark will be an argument of \Macro{MakeMarkcase}. You can use this command to +change the case of the running head if necessary. The \KOMAScript{} classes +use \Macro{@firstofone}\IndexCmd{@firstofone}\important{\Macro{@firstofone}} +by default. This means the text of the running head will be set without +changing the capitalisation. If you use a different class, +\Macro{MakeMarkcase} will be set to +\Macro{MakeUppercase}\IndexCmd{MakeUppercase}% +\important{\Macro{MakeUppercase}}. However, \Package{tocbasic} only defines +this command if it is not already defined. It can therefore be predefined by +another class or package and \Package{tocbasic} will use that definition +rather than overwriting it. \begin{Example} - For incomprehensible reasons, you want to set the running heads in lower - case letters only. To make this automatically for all running heads, that - will be set by \Package{tocbasic}, you define: + For some strange reason, you want to set the running heads entirely in + lower-case letters. To apply this change automatically for all running heads + set by \Package{tocbasic}, you define: \begin{lstcode} \let\MakeMarkcase\MakeLowercase \end{lstcode} \end{Example} -Please\textnote{Hint!} allow me some words about -\Macro{MakeUppercase}\IndexCmd{MakeUppercase}, First of all this command isn't -fully expandable. This means, that problems may occur using it in the context -of other commands. Beyond that typographers accord, that whenever setting -whole words or phrases in capitals, letter spacing is absolutely -necessary. But correct letter spacing of capitals should not be done with a -fix white space between all letters. Different pairs of letters need different -space between each other. Additional some letters build holes in the text, -that have to be taken into account. Packages like \Package{ulem} or -\Package{soul} doesn't provide this and \Macro{MakeUppercase} does not do -anything like this. Also automatic letter spacing using package -\Package{microtype} is only one step to a less-than-ideal solution, because it -cannot recognize and take into account the glyphs of the letters. Because of -this\textnote{Attention!} typesetting whole words and phrases is expert work -and almost ever must be hand made. So average users are recommended to not do -that or to use it only spare and not at exposed places like running heads.% +Let\textnote{Hint!} me give you some advice about +\Macro{MakeUppercase}\IndexCmd{MakeUppercase}. First of all, this command is +not fully expandable. This means that it can cause problems interacting with +other commands. Beyond that, typographers agree that whenever you set whole +words or phrases in capital letters, additional spacing is absolutely +necessary. However, adding a fixed spacing between all letters is not an +adequate solution. Different pairs of letters require different spaces between +them. Additionally, some letters already create gaps in the text that must be +taken into account. Packages like \Package{ulem} or \Package{soul} can +scarcely achieve this, nor can \Macro{MakeUppercase}. The automatic letter +spacing using the \Package{microtype} package is in this respect only an +approximate solution, because it does not take into account the concrete, +font-dependent glyphs. Because\textnote{Attention!} typesetting all-capital +text is expert work and almost always requires manual adjustment, ordinary +users are recommended avoid using it, or to use it only sparingly and not in +such an exposed place as the running head.% \EndIndexGroup \begin{Declaration} \Macro{deftocheading}\Parameter{extension}\Parameter{definition} \end{Declaration} -The package \Package{tocbasic} contains a standard definition for typesetting -headings of TOCs. This standard definition is configurable by several -features, described at \DescRef{\LabelBase.cmd.setuptoc} next. But if all those features are -not enough, an alternative heading command may be defined using -\Macro{deftocheading}. Thereby \PName{extension} is the file name extension of -the corresponding TOC-file. The \PName{definition} of the heading command may -use one single parameter \PValue{\#1}. While calling the newly defined command -inside of \DescRef{\LabelBase.cmd.listoftoc} or \DescRef{\LabelBase.cmd.listofeachtoc} that \PValue{\#1} will be -replaced by the corresponding heading term.% +The \Package{tocbasic} package contains a default definition for typesetting +the titles of content lists. You can configure this default definition through +various features discussed in the \DescRef{\LabelBase.cmd.setuptoc} comand +below. If those features are not enough, you can use \Macro{deftocheading} +to define your own title for the content list with the given file +\PName{extension}. The \PName{definition} of the title can use a single +parameter, \PValue{\#1}. When the command is called inside +\DescRef{\LabelBase.cmd.listoftoc} or \DescRef{\LabelBase.cmd.listofeachtoc}, +that \PValue{\#1} will be replaced by the title of this content list.% \EndIndexGroup @@ -598,203 +631,207 @@ replaced by the corresponding heading term.% \Macro{setuptoc}\Parameter{extension}\Parameter{feature list}% \Macro{unsettoc}\Parameter{extension}\Parameter{feature list} \end{Declaration} -This commands set up and unset features bound to a file name -\PName{extension}. The \PName{feature list} is a comma separated list of -single features. \Package{tocbasic} does know following features: +You can use these two commands to set and clear features for a TOC file +\PName{extension} or the content list associated with it. The \PName{feature +list} is a comma-separated list of features. The \Package{tocbasic} package +recognizes following features: \begin{description} -\item[\texttt{leveldown}] uses not the top level heading below +\item[\texttt{leveldown}] means that the content list's heading is created not + with the highest sectioning level below \DescRef{maincls.cmd.part}\,---\,\DescRef{maincls.cmd.chapter} if available, - \DescRef{maincls.cmd.section} otherwise\,---\,but the first sub level. This - feature will be evaluated by the internal heading command. On the other - hand, if an user defined heading command has been made with - \DescRef{\LabelBase.cmd.deftocheading}, that user is responsible for the evaluation of the - feature. The \KOMAScript{} classes set this feature using option - \OptionValueRef{maincls}{listof}{leveldown}% + \DescRef{maincls.cmd.section} otherwise\,---\,but with a heading of the next + level below that. This feature is evaluated by the internal heading command. + On the other hand, if a user-defined heading command has been created with + \DescRef{\LabelBase.cmd.deftocheading}, the person defining that command is + responsible for evaluating the feature. The \KOMAScript{} classes set this + feature using the \OptionValueRef{maincls}{listof}{leveldown}% important{\OptionValueRef{maincls}{listof}{leveldown}}% - \IndexOption{listof~=\PValue{leveldown}} for all file name extensions of the - owner \PValue{float}. -\item[\texttt{nobabel}] prevents usage of the language switch of - \Package{babel}\IndexPackage{babel} at the TOC-file with the corresponding - file name \PName{extension}. This feature should be used only for auxiliary - files, that contain text in one language only. Changes of the language - inside of the document will not longer regarded at the TOC-file. Package - \Package{scrwfile}\important{\Package{scrwfile}}\IndexPackage{scrwfile} uses - this feature also for clone destinations, because those will get the - language change from the clone source already. - - Please note\textnote{Attention!}, the feature is executed while adding a - file extension to the list of known file extension. Changing the feature - afterwards would not have any effect. + \IndexOption{listof~=\textKValue{leveldown}} option for all file extensions + with the owner \PValue{float}. +\item[\texttt{nobabel}] prevents using the language-switching features of + \Package{babel}\IndexPackage{babel} for the TOC file associated with the + this file \PName{extension}. This feature should be used only for content + lists that are created in a fixed language, which means that changes of the + language inside of the document will no longer affect the content list. The + \Package{scrwfile}\important{\Package{scrwfile}}\IndexPackage{scrwfile} + package also uses this feature for cloned destinations, as because those + files already inherit any language changes from the cloning source. + + Note\textnote{Attention!} that you must set this feature before you add a + file extension to the list of known extensions. Changing the feature + afterwards will have no effect. \item[\texttt{noparskipfake}] prevents\ChangedAt{v3.17}{\Package{tocbasic}} - usage of an extra \Length{parskip} before switching \Length{parskip} off. In - general, the consequence of this feature for documents using paragraph - distance is less vertical space between heading and first entry than between - normal headings and normal text. + the insertion of a final \Length{parskip} before switched off paragraph + spacing for content lists. In general, this will cause documents that use + spacing between paragraphs to have less vertical space between the list + heading and first entry than between normal headings and normal text. + Normally, therefore, you will obtain a more uniform formatting without this + feature. \item[\texttt{noprotrusion}] prevents\ChangedAt{v3.10}{\Package{tocbasic}} - disabling character protrusion at the TOC. Character protrusion at the TOCs - will be disabled by default if package - \Package{microtype}\IndexPackage{microtype} or another package, that - supports \Macro{microtypesetup}\IndexCmd{microtypesetup}, was loaded. So if - you want protrusion at a TOC, you have to set this feature. But - note\textnote{Attention!}, with character protrusion TOC-entries may be - printed wrong. This is a known issue of character protrusion. -\item[\texttt{numbered}] uses a numbered heading for the TOC and because of - this also generates an entry to the table of contents. This feature will be - evaluated by the internal heading command. On the other hand, if an user - defined heading command has been made with \DescRef{\LabelBase.cmd.deftocheading}, that user - is responsible for the evaluation of the feature. The \KOMAScript{} classes - set this feature using option \OptionValueRef{maincls}{listof}{numbered}% + character protrusion, which allows optical margin alignment, from being + disabled in the content lists. By default, character protrusion is disabled + when the \Package{microtype}\IndexPackage{microtype} package, or another + package that supports \Macro{microtypesetup}\IndexCmd{microtypesetup}, is + loaded. So if you want optical margin alignment in the content lists, you + must set this feature. Note\textnote{Attention!}, however, that character + protrusion in content lists often results in incorrect results. This is a + known issue with character protrusion. +\item[\texttt{numbered}] means that the heading for the content list should + be numbered and included in the table of contents. This feature is evaluated + by the internal heading command. However, if a user-defined heading command + has been created with \DescRef{\LabelBase.cmd.deftocheading}, the person + creating that definition is responsible evaluating the feature. The + \KOMAScript{} classes set this feature using the + \OptionValueRef{maincls}{listof}{numbered}% \important{\OptionValueRef{maincls}{listof}{numbered}}% - \IndexOption{listof~=\PValue{numbered}} for all file name extensions of the - owner \PValue{float}. + \IndexOption{listof~=\textKValue{numbered}} option for all file extensions + with the owner \PValue{float}. \item[\texttt{numberline}] \leavevmode\ChangedAt{v3.12}{\Package{tocbasic}}% - redefines \Macro{nonumberline} to use \DescRef{\LabelBase.cmd.numberline}. With this the not - numbered entries generated by \KOMAScript{} or using \Macro{nonumberline} at - the very beginning of the last argument of \Macro{addcontentline} will also - be indented like numbered entries of the same - type. Using\ChangedAt{v3.20}{\Package{tocbasic}} \DescRef{\LabelBase.cmd.numberline} for - entries without number\ChangedAt{v3.20}{\Package{tocbasic}} can have - additional side effects if you use entry style \PValue{tocline}. See style - attribute \Option{breakafternumber} and \Option{entrynumberformat} in - \autoref{tab:tocbasic.tocstyle.attributes} from - \autopageref{tab:tocbasic.tocstyle.attributes} downwards. - - \KOMAScript{} classes set this feature for the file name extensions of the - owner \PValue{float} if you use option + means that any entries made using \DescRef{\LabelBase.cmd.addxcontentsline} + or \DescRef{\LabelBase.cmd.addxcontentslinetoeachtocfile}, where the + optional argument for the number is missing or empty, will be provided with + an empty \DescRef{\LabelBase.cmd.numberline} command. This usually results + in these entries being left-aligned not with the number but with the text of + the numbered entries of the same level. + Using\ChangedAt{v3.20}{\Package{tocbasic}} the \PValue{tocline} entry style + can have additional side effects. See the style attribute + \Option{breakafternumber} and \Option{entrynumberformat} in + \autoref{tab:tocbasic.tocstyle.attributes} starting on + \autopageref{tab:tocbasic.tocstyle.attributes}. + + \KOMAScript{} classes set this feature for the file extensions with the + owner \PValue{float} if you use the \OptionValueRef{maincls}{listof}{numberline}% \important{\OptionValueRef{maincls}{listof}{numberline}}% - \IndexOption{listof~=\PValue{numberline}} and for file name extension - \PValue{toc} if you use option \OptionValueRef{maincls}{toc}{numberline}% + \IndexOption{listof~=\textKValue{numberline}} option and for the file + extension \PValue{toc} if you use the + \OptionValueRef{maincls}{toc}{numberline}% \important{\OptionValueRef{maincls}{toc}{numberline}}% - \IndexOption{toc~=\PValue{numberline}}. Analogous they reset this feature if - you use \OptionValueRef{maincls}{listof}{nonumberline}% + \IndexOption{toc~=\textKValue{numberline}} option. Similarly, this feature + is reset if you use \OptionValueRef{maincls}{listof}{nonumberline}% \important{\OptionValueRef{maincls}{listof}{nonumberline}}% - \IndexOption{listof~=\PValue{nonumberline}} or + \IndexOption{listof~=\textKValue{nonumberline}} or \OptionValueRef{maincls}{toc}{nonumberline}% \important{\OptionValueRef{maincls}{toc}{nonumberline}}% - \IndexOption{toc~=\PValue{nonumberline}}. + \IndexOption{toc~=\textKValue{nonumberline}}. \item[\texttt{onecolumn}] \leavevmode\ChangedAt{v3.01}{\Package{tocbasic}}% - typesets the corresponding TOC with internal one column mode of - \Macro{onecolumn}\IndexCmd{onecolumn}. This\textnote{Attention!} will be - done only, if the corresponding table of contents or list of something does - not use feature \PValue{leveldown}\important{\PValue{leveldown}}. The + means that this content list will automatically use \LaTeX's internal + one-column mode with \Macro{onecolumn}\IndexCmd{onecolumn}. + However\textnote{Attention!}, this applies only if this content list does + not use the \PValue{leveldown}\important{\PValue{leveldown}} feature. The \KOMAScript{} classes \Class{scrbook} and \Class{scrreprt} activate this feature with \DescRef{\LabelBase.cmd.AtAddToTocList} (see \autoref{sec:tocbasic.basics}, \DescPageRef{\LabelBase.cmd.AtAddToTocList}) - for all TOCs with owner \PValue{float} or with themselves as owner. With - this, e.\,g., the table of contents, the list of figures and the list of - tables of both classes will be single columned automatically. The - multiple-column-mode of package \Package{multicol}\IndexPackage{multicol} - will not be recognised or changed by this option. -\item[\texttt{totoc}] writes the title of the corresponding TOC to the table - of contents. This feature will be evaluated by the internal heading - command. On the other hand, if an user defined heading command has been made - with \DescRef{\LabelBase.cmd.deftocheading}, that user is responsible for the evaluation of - the feature. The \KOMAScript{} classes set this feature using option - \OptionValueRef{maincls}{listof}{totoc}% + for all content lists with the owner \PValue{float} or with themselves as + owner. Thus, for example, the table of contents, the list of figures, and + the list of tables are automatically printed in a single column for both + these classes. The multicolumn mode of the + \Package{multicol}\IndexPackage{multicol} package is expressly unaffected by + this option. +\item[\texttt{totoc}] means that the title of content list should be included + in the table of contents. This feature will be evaluated by the internal + heading command. However, if an user-defined heading command has been + created with \DescRef{\LabelBase.cmd.deftocheading}, the person defining + that command is responsible for evaluating this feature. The \KOMAScript{} + classes set this feature using the \OptionValueRef{maincls}{listof}{totoc}% \important{\OptionValueRef{maincls}{listof}{totoc}}% - \IndexOption{listof~=\PValue{totoc}} for all file name extensions of the - owner \PValue{float}. + \IndexOption{listof~=\textKValue{totoc}} option for all file extensions with + the owner \PValue{float}. \end{description} -Classes and packages may know features, too, e.\,g, the \KOMAScript{} classes -know following additional features: +The \KOMAScript{} classes recognize an additional feature: \begin{description} -\item[\texttt{chapteratlist}] activates special code to be put into the TOC at - start of a new chapter. This code may either be vertical space or the - heading of the chapter. See \DescRef{maincls.option.listof}% +\item[\texttt{chapteratlist}] ensures that an optional subdivision is added + to the content list for each new chapter. By default, this subdivision is a + vertical space. See \DescRef{maincls.option.listof}% \IndexOption{listof}\important{\DescRef{maincls.option.listof}} in \autoref{sec:maincls.floats}, \DescPageRef{maincls.option.listof} for more - information about such features. + information about this option. \end{description} \begin{Example} Because \KOMAScript{} classes use \Package{tocbasic} for the list of figures - and list of tables, there's one more way to remove chapter structuring at - those: + and list of tables, there is another way to prevent chapter subdivisions in + these lists: \begin{lstcode} \unsettoc{lof}{chapteratlist} \unsettoc{lot}{chapteratlist} \end{lstcode} - And if you want to have the chapter structuring of the \KOMAScript{} classes - at your own list of algorithms with file name \PName{extension} - ``\PValue{loa}'' from the previous examples, you may use + If you want the chapter subdivisions for your own list that you have defined + with the file \PName{extension} ``\PValue{loa}'' to use the same subdivision + format used by the \KOMAScript{} classes, you can use \begin{lstcode} \setuptoc{loa}{chapteratlist} \end{lstcode} - And if classes with \DescRef{maincls.cmd.chapter} should also force single - column mode for the list of algorithms you may use + And if you also want classes that use \DescRef{maincls.cmd.chapter} as the + top-level structure to use the one-column mode automatically, you can + use \begin{lstcode} \ifundefinedorrelax{chapter}{}{% \setuptoc{loa}{onecolumn}% } \end{lstcode} - Usage of \DescRef{scrbase.cmd.ifundefinedorrelax} presumes package - \Package{scrbase} (see \autoref{sec:scrbase.if}, + Using \DescRef{scrbase.cmd.ifundefinedorrelax} requires the + \Package{scrbase} package (see \autoref{sec:scrbase.if}, \DescPageRef{scrbase.cmd.ifundefinedorrelax}). - It\textnote{Hint!} doesn't matter if you're package would be used with - another class. You should never the less set this feature. And if the other - class would also recognise the feature your package would automatically use - the feature of that class. + Even\textnote{Hint!} if your package will be used with another class, it + does not hurt to set these features. To the contrary, if another class also + evaluates these features, then your package would automatically use the + features of that class. \end{Example} -As you may see, packages that use \Package{tocbasic}, already provide several -interesting features, without the need of a lot of implementation effort. Such -an effort would be needed only without \Package{tocbasic} and because of this, -most packages currently lack of such features.% +As you can see, packages that use \Package{tocbasic} already support a wide +range of options for content lists that would otherwise require a great deal +of effort to implement and which are therefore missing in many packages.% \EndIndexGroup \begin{Declaration} \Macro{iftocfeature}\Parameter{extension}\Parameter{feature}% - \Parameter{true-instructions}\Parameter{false-instructions} + \Parameter{then code}\Parameter{else code} \end{Declaration} -This command may be used, to test, if a \PName{feature} was set for file name -\PName{extension}. If so the \PName{true-instructions} will be processed, -otherwise the \PName{false-instruction} will be. This may be useful, e.\,g., -if you define your own heading command using +You can use this command to test if a \PName{feature} was set for the given +file \PName{extension}. If so the \PName{then code} will be executed, +otherwise the \PName{else code} will be. This can be useful, for example, if +you define your own heading command using \DescRef{\LabelBase.cmd.deftocheading} but want to support the features \PValue{totoc}, \PValue{numbered} or \PValue{leveldown}.% \EndIndexGroup -\section{Configuration of Entries to a Table or List of Contents} +\section{Configuring Content-List Entries} \seclabel{tocstyle}% \BeginIndexGroup \BeginIndex{}{table of contents>entry}% \Index{list of contents|\see{table of contents}} - -Since\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} version~3.20 package -\Package{tocbasic} can not only configure the tables or lists of contents and -their auxiliary files but also influence their entries. To do so, you can -define new styles or you can use and configure one of the predefined -styles. In the medium term \Package{tocbasic} will replace the experimental -package \Package{tocstyle} that never became an official part of the -\KOMAScript{} bundle. The \KOMAScript{} classes intensively use the TOC-entry -styles of \Package{tocbasic} since version~3.20. - +Since\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} version~3.20, the +\Package{tocbasic} package has been able not only to configure the tables or +lists of contents and their auxiliary files but also to influence their +entries. To do so, you can define new styles or you can use and configure one +of the predefined styles. In the medium term, \Package{tocbasic} will replace +the experimental \Package{tocstyle} package that never became an official part +of the \KOMAScript{} bundle. The \KOMAScript{} classes themselves have relied +completely on the \Package{tocbasic} entry styles since version~3.20. \begin{Declaration} \Counter{tocdepth} \end{Declaration} -Entries to tables or lists of contents are in hierarchical order. Therefore -each entry level has a numerical value. Higher values correspond with deeper -levels. Within the standard classes, e.\,g., parts have the numerical entry -level -1 in the table of contents and chapter entries have value 0. Counter -\Counter{tocdepth} defines the deepest level that should be shown in the -tables and lists of any contents. - -Class \Class{book} sets \Counter{tocdepth} to 2, so entries of the levels -\PValue{part}, \PValue{chapter}, \PValue{section}, and \PValue{subsection} are -printed. Deeper levels like \PValue{subsubsection}, which has the numerical -value 3, are not printed. Nevertheless the entries are part of the auxiliary -file for the table of contents. - -Most entry styles of \Package{tocbasic} also cares about -\Counter{tocdepth}. Only style \PValue{gobble} (see -\DescRef{\LabelBase.cmd.DeclareTOCStyleEntry}\iffree{}{, later in this - section}) ignores \Counter{tocdepth}. -% +Entries to content lists are usually hierarchical. For this purpose, each +entry level has a numerical value. The higher this value, the lower in the +hierarchy is this level. In the standard classes, for example, parts have the +level -1 and chapters have the value 0. The \LaTeX{} counter +\Counter{tocdepth} determines the deepest level that should be shown in the +table of contents and other content lists. + +For example, the \Class{book} class sets \Counter{tocdepth} to 2, so entries +of the levels \PValue{part}, \PValue{chapter}, \PValue{section}, and +\PValue{subsection} are printed. Deeper levels like \PValue{subsubsection}, +which has the numerical value 3, are not printed. Nevertheless the entries are +part of the auxiliary file for the table of contents. + +Note that most \Package{tocbasic} entry styles, with the exception of +\PValue{gobble} (see \DescRef{\LabelBase.cmd.DeclareTOCStyleEntry}\iffree{}{, +later in this section}) observe \Counter{tocdepth}.% \EndIndexGroup @@ -802,26 +839,24 @@ Most entry styles of \Package{tocbasic} also cares about \Macro{numberline}\Parameter{entry number}% \Macro{usetocbasicnumberline}\OParameter{code} \end{Declaration} -Though\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} the \LaTeX{} kernel -already defines command \Macro{numberline}, the kernel definition is not -sufficient for \Package{tocbasic}. Therefore \Package{tocbasic} has its own -definition of \Macro{numberline}. The package uses -\Macro{usetocbasicnumberline} to activate this definition whenever a TOC-entry -needs it. Because of this, re-defining \Macro{numberline} often does not work -and even may result in warnings if you use \Package{tocbasic}. - -You can use the definition of \Package{tocbasic} putting +Although\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} the \LaTeX{} kernel +already defines a \Macro{numberline} command, the definition is not sufficient +for \Package{tocbasic}. Therefore \Package{tocbasic} defines its own commands +and sets \Macro{numberline} as needed using \Macro{usetocbasicnumberline} for +each content-list entry. Redefining \Macro{numberline}, therefore, is often +ineffective and may result in warnings if you use \Package{tocbasic}. + +You can use the definition of \Package{tocbasic} by putting \Macro{usetocbasicnumberline} into your document's preamble. The command first -of all checks, whether or not the current definition of \Macro{numberline} -uses essential, internal commands of \Package{tocbasic}. Only if this is not -the case \Macro{usetocbasicnumberline} redefines \Macro{numberline} and -executes \PName{code}. If you omit the optional argument, a -\Macro{PackageInfo} outputs a message about the successful re-definition. If +checks if the current definition of \Macro{numberline} +uses certain important, internal commands of \Package{tocbasic}. If this is not +the case, \Macro{usetocbasicnumberline} redefines \Macro{numberline} and +executes \PName{code}. If you omit the optional argument, it issues +a message about the redefinition with \Macro{PackageInfo}. If you just do not want such a message, use an empty optional argument. -Please note\textnote{Attention!}, as a side effect -\Macro{usetocbasicnumberline} can globally change the internal switch -\Macro{@tempswa}!% +Note\textnote{Attention!} that \Macro{usetocbasicnumberline} can change the +internal switch \Macro{@tempswa} globally!% \EndIndexGroup @@ -829,34 +864,34 @@ Please note\textnote{Attention!}, as a side effect \Macro{DeclareTOCStyleEntry}\OParameter{option list}\Parameter{style}% \Parameter{entry level} \end{Declaration} -This\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} command is used to define -or configure the TOC-entries of a given \PName{entry level}. Argument -\PName{entry level} is a symbolic name, e.\,g., \PValue{section} for the entry -to the table of contents of the section level with the same name or +This\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} command defines or +configures the content-list entries of a given \PName{entry level}. The +\PName{entry level} argument is a symbolic name, e.\,g. \PValue{section}, for +the entry to the table of contents of the section level with the same name or \PValue{figure} for an entry of a figure to the list of figures. A \PName{style} is assigned to each \PName{entry level}. The \PName{style} has -to be defined before using it as an argument of -\Macro{DeclareTOCStyleEntry}. The \PName{option list} is used to configure -several \PName{style}-dependent attributes of the \PName{entry level}. +to be defined before using it as an argument of \Macro{DeclareTOCStyleEntry}. +You can use the \PName{option list} to configure the various, usually +\PName{style}-dependent, attributes of the entries. Currently, \Package{tocbasic} defines the following entry styles: \begin{description} -\item[\PValue{default}] defaults to a clone of style - \PValue{dottedtocline}. It is recommended to class authors, who use - \Package{tocbasic}, to change this style into the default style of the class - using \Macro{CloneTOCStyle}. For example the \KOMAScript{} classes change +\item[\PValue{default}] defaults to a clone of the \PValue{dottedtocline} + style. Class authors who use \Package{tocbasic} are encouraged to change + this style to the default content-list style of the class using + \Macro{CloneTOCStyle}. For example the \KOMAScript{} classes change \PValue{default} into a clone of \PValue{tocline}. \item[\PValue{dottedtocline}] is similar to the style used by the standard classes \Class{book} and \Class{report} for the \PValue{section} down to \PValue{subparagraph} entry levels of the table of contents and for the entries at the list of figures or list of tables. It supports the attributes - \PValue{level}, \PValue{indent}, and \PValue{numwidth}. The entries will be + \PValue{level}, \PValue{indent}, and \PValue{numwidth}. The entries are indented by the value of \PValue{indent} from the left. The width of the - entry number is given by the value of \PValue{numwidth}. For multiline - entries the indent will be increased by the value of \PValue{numwidth} for + entry number is given by the value of \PValue{numwidth}. For multi-line + entries, the indent will be increased by the value of \PValue{numwidth} for the second and following lines. The page number is printed using - \Macro{normalfont}\IndexCmd{normalfont}. Entry text and page number are - connected by a dotted line. \hyperref[fig:tocbasic.dottedtocline]% + \Macro{normalfont}\IndexCmd{normalfont}. The entry text and the page number + are connected by a dotted line. \hyperref[fig:tocbasic.dottedtocline]% {Figure~\ref*{fig:tocbasic.dottedtocline}} illustrates the attributes of this style. \begin{figure} @@ -873,8 +908,8 @@ Currently, \Package{tocbasic} defines the following entry styles: \setlength{\parindent}{-3.2em}% \addtolength{\parfillskip}{-2.55em}% \makebox[3.2em][l]{1.1.10}% - Text of an entry to the table of contents with style - \PValue{dottedtocline} and more than one line% + Text of an entry in the table of contents with the + \PValue{dottedtocline} style and more than one line% \leaders\hbox{$\csname m@th\endcsname \mkern 4.5mu\hbox{.}\mkern 4.5mu$}\hfill\nobreak \makebox[1.55em][r]{12}% @@ -902,40 +937,40 @@ Currently, \Package{tocbasic} defines the following entry styles: (\linewidth-1.55em,-\baselineskip); \end{tikzpicture}% } - \caption{Illustrations of some attributes of a TOC-entry with style - \PValue{dottedtocline}} + \caption{Illustrations of some attributes of a TOC entry with the + \PValue{dottedtocline} style} \label{fig:tocbasic.dottedtocline} \end{figure} -\item[\PValue{gobble}] is the most ordinary style. Independently from the - setting of \DescRef{\LabelBase.counter.tocdepth}% +\item[\PValue{gobble}] is the simplest possible style. Entries in this style, + regardless of the setting of \DescRef{\LabelBase.counter.tocdepth}% \IndexCounter{tocdepth}\important{\DescRef{\LabelBase.counter.tocdepth}}, - entries with this style will never be printed. The style simply gobbles the - entries. Nevertheless, it supports the standard attribute \PValue{level} but - does ignore it. + will never be printed. The style simply gobbles the + entries, so to speak. It has the default \PValue{level} attribute, but + it is never evaluated. \item[\PValue{largetocline}] is similar to the style used by the standard - classes for the level \PValue{part}. It supports attributes \PValue{level} - and \PValue{indent} only. The last one is already a variation of the - standard classes that do not support an indent of the \PValue{part} entries. - - Before an entry a page break will be made easier. The entries will be - indented by the value of \PValue{indent} from the left. They are printed - using \Macro{large}\Macro{bfseries}. If \DescRef{\LabelBase.cmd.numberline} - is used, the number width is 3\Unit{em}. \DescRef{\LabelBase.cmd.numberline} - is not redefined. The standard classes do not use - \DescRef{\LabelBase.cmd.numberline} for \PName{part} entries. The value of - \PName{indent} even does not influence the indent from the second line of an - entry. + classes for the \PValue{part} level. It supports the \PValue{level} and + \PValue{indent} attributes only. The latter deviates from the standard + classes, which do not support an indent of the \PValue{part} entries. + + A penalty is set to permit page breaks before an entry of an appropriate + level. The entries will be indented by the value of \PValue{indent} from the + left and printed with the font style \Macro{large}\Macro{bfseries}. If + \DescRef{\LabelBase.cmd.numberline} is used, the number width is 3\Unit{em}. + \DescRef{\LabelBase.cmd.numberline} is not redefined. The standard classes + do not use \DescRef{\LabelBase.cmd.numberline} for \PName{part} entries. The + value of \PName{indent} also has no effect on the indentation from the + second line and after in a multi-line entry. \hyperref[fig:tocbasic.largetocline]% - {Figure~\ref*{fig:tocbasic.largetocline}} illustrates the attributes of this - style. There you can also see that the style copies inconsistencies of the - standard classes, e.\,g. the missing indent of the second and following - lines of an entry or the different values of \Macro{@pnumwidth} that results - from the font size dependency. This can even result in a to small distance - between the entry text and the page number. Please note, the entry number - width shown in the figure is only valid if - \DescRef{\LabelBase.cmd.numberline} has been used. In contrast, the standard - classes use a distance of 1\Unit{em} after the number. + {Figure~\ref*{fig:tocbasic.largetocline}} illustrates the characteristics of + this style. You will also notice that the style has adopted some + inconsistencies present in the standard classes, e.\,g. the missing indent + of the second and following lines of an entry or the different values of + \Macro{@pnumwidth} that results from the font-size dependency. This can + result, in extreme cases, in the entry text coming too close. Note that the + width of the entry number shown in the figure is only valid if + \DescRef{\LabelBase.cmd.numberline} has been used. The standard classes, + however, use a distance of 1\Unit{em} after the number. \begin{figure} \centering \resizebox{.8\linewidth}{!}{% @@ -947,8 +982,8 @@ Currently, \Package{tocbasic} defines the following entry styles: \parbox[t]{\dimexpr \linewidth-1.55em\relax}{% \makebox[3em][l]{\large\bfseries I}% \large\bfseries - Text of an entry to the table of contents with style - \PValue{largetocline} and more than one line% + Text of an entry to the table of contents with the + \PValue{largetocline} style and more than one line% \hfill \makebox[0pt][l]{\normalsize\normalfont \makebox[1.55em][r]{\large\bfseries 1}}% @@ -968,39 +1003,42 @@ Currently, \Package{tocbasic} defines the following entry styles: (\linewidth-1.55em,-\baselineskip); \end{tikzpicture}% } - \caption{Illustrations of some attributes of a TOC-entry with style + \caption{Illustrations of some attributes of a TOC entry with style \PValue{largetocline}} \label{fig:tocbasic.largetocline} \end{figure} -\item[\PValue{tocline}] is a very flexible style. The \KOMAScript{} classes - use this style by default for all kinds of entries. Classes \Class{scrbook} - and \Class{scrreprt} respectively \Class{scrartcl} also define - clones \PValue{part}, \PValue{chapter} and \PValue{section} respectively - \PValue{section} and \PValue{subsection}, but add extra +\item[\PValue{tocline}] is a flexible style. The \KOMAScript{} classes use + this style by default for all kinds of entries. Likewise, these classes + define the clones \PValue{part}, \PValue{chapter}, and \PValue{section}, or + \PValue{section} and \PValue{subsection} using this style, but add extra \PName{initial code} to the clones to change their defaults. - The style supports attributes \PValue{level}, \PValue{beforeskip}, - \PValue{dynnumwidth}, \PValue{entryformat}, \PValue{entrynumberformat}, - \PValue{breakafternumber}, \PValue{indent}, \PValue{linefill}, - \PValue{numsep}, \PValue{numwidth}, \PValue{onstarthigherlevel}, - \PValue{onstartlowerlevel}, \PValue{onstartsamelevel}, - \PValue{pagenumberbox}, \PValue{pagenumberformat}, \PValue{raggedentrytext}, - and \PValue{raggedpagenumber}. The defaults of all these attributes depend - on the name of the \PName{entry level}. They correspond to the results of - the standard classes. So after loading \Package{tocbasic}, you can change - the style of the standard classes entries to the table of contents into - \PValue{tocline} using \DescRef{\LabelBase.cmd.DeclareTOCEntryStyle} without obvious visual - changes unless you change exactly these attributes that should induce such - changes. Same is valid for list of figures or list of tables of the standard + The style supports 16\important{\PValue{level}, \PValue{beforeskip}, + \PValue{breakafternumber}, \PValue{dynnumwidth}, \PValue{entryformat}, + \PValue{entrynumberformat}, \PValue{indent}, \PValue{linefill}, + \PValue{numsep}, \PValue{numwidth}, \PValue{onstarthigherlevel}, + \PValue{onstartlowerlevel}, \PValue{onstartsamelevel}, + \PValue{pagenumberbox}, \PValue{pagenumberformat}, + \PValue{raggedentrytext}, \PValue{raggedpagenumber}} additional attributes + in addition to the default \PValue{level} attribute. The defaults of all + these attributes depend on the name of the \PName{entry level} and + correspond to the results of the standard classes. So after loading + \Package{tocbasic}, you can change the style of the entries in the table of + contents of the standard classes into \PValue{tocline} using + \DescRef{\LabelBase.cmd.DeclareTOCEntryStyle} without this leading directly + to major changes in their appearance. Thus you can precisely change only + those attributes that are necessary for the desired changes. The same + applies to the list of figures and the list of tables for the standard classes. - Because of the flexibility of this style it even could be used instead of - the styles \PValue{dottedtocline}, \PValue{undottedtocline} or - \PValue{largetocline}. However it needs more effort for configuration. + Because its great flexibility, this style can in principle replace the + \PValue{dottedtocline}, \PValue{undottedtocline}, and \PValue{largetocline} + styles, but this requires more effort to configure. + \hyperref[fig:tocbasic.tocline]% {Figure~\ref*{fig:tocbasic.tocline}} illustrates some of the length - attributes of this style. All attributes are described in - \autoref{tab:tocbasic.tocstyle.attributes} from + attributes of this style. The others are explained in + \autoref{tab:tocbasic.tocstyle.attributes} starting on \autopageref{tab:tocbasic.tocstyle.attributes}. \begin{figure} \centering @@ -1027,8 +1065,8 @@ Currently, \Package{tocbasic} defines the following entry styles: \setlength{\parindent}{-3em}% \addtolength{\parfillskip}{-2.55em}% \makebox[3em][l]{\large\bfseries I.}% - \textbf{\large Text of a part entry with style - \PValue{tocline} and with at least two lines of text}% + \textbf{\large Text of a part entry with the + \PValue{tocline} style and at least two lines of text}% \hfill \makebox[1.55em][r]{\bfseries 12}\large }% @@ -1058,9 +1096,9 @@ Currently, \Package{tocbasic} defines the following entry styles: \setlength{\parindent}{-1.5em}% \addtolength{\parfillskip}{-2.55em}% \makebox[1.5em][l]{\bfseries 1.}% - \textbf{Text of a chapter entry with style - \PValue{tocline} and for demonstration purpose with more than one - line of text}% + \textbf{Text of a chapter entry with the + \PValue{tocline} style and more than one line of text + for demonstration purposes}% \hfill \makebox[1.55em][r]{\bfseries 12}% }% @@ -1096,9 +1134,9 @@ Currently, \Package{tocbasic} defines the following entry styles: \setlength{\parindent}{-2.3em}% \addtolength{\parfillskip}{-2.55em}% \makebox[2.3em][l]{1.1.}% - Text of a section entry with style - \PValue{tocline} and for demonstration purpose with more than one - line of text% + Text of a section entry with the \PValue{tocline} + style and more than one line of text for + demonstration purposes% \leaders\hbox{$\csname m@th\endcsname \mkern 4.5mu\hbox{.}\mkern 4.5mu$}\hfill\nobreak \makebox[1.55em][r]{3}% @@ -1111,9 +1149,9 @@ Currently, \Package{tocbasic} defines the following entry styles: \setlength{\parindent}{-3.2em}% \addtolength{\parfillskip}{-2.55em}% \makebox[3.2em][l]{1.1.10.}% - Text of a subsection entry with style - \PValue{tocline} and for demonstration purpose with more than one - line of text% + Text of a subsection entry with the \PValue{tocline} + and more than one line of text for demonstration + purposes% \leaders\hbox{$\csname m@th\endcsname \mkern 4.5mu\hbox{.}\mkern 4.5mu$}\hfill\nobreak \makebox[1.55em][r]{12}% @@ -1145,24 +1183,23 @@ Currently, \Package{tocbasic} defines the following entry styles: ($(subsection)+(\linewidth-1.55em,-\baselineskip)$); \end{tikzpicture}% } - \caption{Illustrations of some attributes of a TOC-entry with style - \PValue{tocline}} + \caption{Illustrations of some attributes of a TOC entry with the + \PValue{tocline} style} \label{fig:tocbasic.tocline} \end{figure} \item[\PValue{undottedtocline}] is similar to the style used by the standard - classes \Class{book} and \Class{report} for the \PValue{chapter} entry level - or by \Class{article} for the \PValue{section} entry level of the table of - contents. It supports the attributes \PValue{level}, \PValue{indent}, and - \PValue{numwidth}. The last one is already a variation of the standard - classes that do not support an indent of these entry levels. - - Before an entry, a page break will be made easier. The entries will be - indented by the value of \PValue{indent} from the left. They are printed - using \Macro{bfseries}. \DescRef{\LabelBase.cmd.numberline} is used - unchanged. The width of the entry number is given by the value of - \PValue{numwidth}. For multiline entries the indent will be increased by the - value of \PValue{numwidth} for the second and following - lines. \hyperref[fig:tocbasic.undottedtocline]% + \Class{book} and \Class{report} classes for the \PValue{chapter} entry + level, or by \Class{article} for the \PValue{section} entry level in the + table of contents. It supports\important{\PValue{level}, \PValue{indent}, + \PValue{numwidth}} only three attributes. A penalty is inserted permitting + an appropriate page break before the entry, as is a vertical skip. The + entries are printed with an indentation of \PValue{indent} from the left and + in \Macro{bfseries}. This is a departure from the standard classes, which do + not support the indentation of these entry levels. + \DescRef{\LabelBase.cmd.numberline} is used unchanged. The width of the + entry number is determined by \PValue{numwidth}. For multi-line entries the + indent will be increased by the value of \PValue{numwidth} for the second + and following lines. \hyperref[fig:tocbasic.undottedtocline]% {Figure~\ref*{fig:tocbasic.undottedtocline}} illustrates the attributes of this style. \begin{figure} @@ -1177,8 +1214,8 @@ Currently, \Package{tocbasic} defines the following entry styles: \makebox[1.5em][l]{\bfseries 1}% \parbox[t]{\dimexpr \linewidth-4.05em\relax}{% \bfseries - Text of an entry to the table of contents with style - \PValue{undottedtocline} and more than one line% + Text of an entry to the table of contents with the + \PValue{undottedtocline} style and more than one line% }% \raisebox{-\baselineskip}{\makebox[2.55em][r]{\bfseries 3}}% }; @@ -1199,93 +1236,94 @@ Currently, \Package{tocbasic} defines the following entry styles: (\linewidth-1.55em,-\baselineskip); \end{tikzpicture}% } - \caption{Illustration of some attributes of style \PValue{undottedtocline} - by the example of a chapter title}% + \caption{Illustration of some attributes of the \PValue{undottedtocline} + style with the example of a chapter title}% \label{fig:tocbasic.undottedtocline} \end{figure} \end{description} -\hyperref[tab:tocbasic.tocstyle.attributes]% -{Table~\ref*{tab:tocbasic.tocstyle.attributes}} describes all attributes of -all styles defined by -\Package{tocbasic}. If\ChangedAt[2016/06]{v3.21}{\Package{tocbasic}} you want -to use these attributes as options to \DescRef{\LabelBase.cmd.DeclareNewTOC} -(see \DescPageRef{\LabelBase.cmd.DeclareNewTOC}) you have to prefix the names -of the attribute by \PValue{tocentry}, e\,g., attribute \PValue{level} becomes -option \Option{tocentrylevel}. -If\ChangedAt[2015/12]{v3.20}{\Package{tocbasic}} you want to use these -attributes as options to \DescRef{maincls-experts.cmd.DeclareSectionCommand} -(see \DescPageRef{maincls-experts.cmd.DeclareSectionCommand}) and similar -commands you have to prefix the names of the attributes by \PValue{toc}, -e\,g., attribute \PValue{level} becomes option \Option{toclevel}. - -Last but not least using \Macro{DeclareTOCStyleEntry} will define internal -command \Macro{l@\PName{entry level}}. +You can find an explanation of the attributes of all styles that +\Package{tocbasic} defines in \autoref{tab:tocbasic.tocstyle.attributes}. +If\ChangedAt[2016/06]{v3.21}{\Package{tocbasic}} you use these attributes as +options to \DescRef{\LabelBase.cmd.DeclareNewTOC} (see +\DescPageRef{\LabelBase.cmd.DeclareNewTOC}), you must prefix the names of the +attribute by \PValue{tocentry}, e\,g. \PValue{level} becomes +\Option{tocentrylevel}. If\ChangedAt[2015/12]{v3.20}{\Package{tocbasic}} use +these attributes as options for +\DescRef{maincls-experts.cmd.DeclareSectionCommand}% +\IndexCmd{DeclareSectionCommand}\IndexCmd{DeclareNewSectionCommand}% +\IndexCmd{RedeclareSectionCommand}\IndexCmd{ProvideSectionCommand} (see +\DescPageRef{maincls-experts.cmd.DeclareSectionCommand}) and similar commands, +you must prefix the names of the attributes with \PValue{toc}, e\,g. +\PValue{level} becomes \Option{toclevel}. + +Finally, using \Macro{DeclareTOCStyleEntry} will define the internal command +\Macro{l@\PName{entry level}}. \begin{desclist} \desccaption{% Attributes of the predefined TOC-entry styles of \Package{tocbasic}% \label{tab:tocbasic.tocstyle.attributes}% }{% - Attributes of the TOC-entry styles (\emph{continuation})% + Attributes of the TOC-entry styles (\emph{continued})% }% \entry{\OptionVName{beforeskip}{length}}{% - vertical distance, inserted before an entry of this level using style - \PValue{tocline} (see \autoref{fig:tocbasic.tocline}). The distance is - made using either \Macro{vskip} or \Macro{addvspace} depending on the - \PName{entry level} to adapt the differences of the standard classes and - former versions of \KOMAScript. - - At \PName{entry level} \PValue{part} the attribute will be initialised - with \texttt{2.25em plus 1pt}, at \PValue{chapter} with \texttt{1em plus - 1pt}. If \PName{entry level} currently is unknown, rather - \PValue{section} is initialised with \texttt{1em plus 1pt}. The initial - value for all other levels is \texttt{0pt plus .2pt}.% + The vertical distance inserted before an entry of this level in the + \PValue{tocline} style (see \autoref{fig:tocbasic.tocline}). The distance + is made using either \Macro{vskip} or \Macro{addvspace} depending on the + \PName{entry level}, to maintain compatibility as far as possible with the + standard classes and earlier versions of \KOMAScript. + + For the \PValue{part} \PName{entry level}, the attribute will be + initialised with \texttt{2.25em plus 1pt}; for \PValue{chapter}, with + \texttt{1em plus 1pt}. If the \PName{chapter} \PName{entry level} is + undefined, \PValue{section} is initialised with \texttt{1em plus 1pt} + instead. The initial value for all other levels is \texttt{0pt plus + .2pt}.% }% \entry{\OptionVName{breakafternumber}{switch}}{% \PName{switch} is one of the values for simple switches from \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. If the - switch is active with style \PValue{tocline}, there will be a line break - after the entry number of + switch is active in the \PValue{tocline} style, there will be a line break + after the number set with \DescRef{\LabelBase.cmd.numberline}\IndexCmd{numberline}. The line after - the entry number again starts left aligned with the number. - - This switch is not active by default at style \PValue{tocline}. + the entry number again starts flush left with the number. The default is + false for the \PValue{tocline} style. - If\textnote{Attention!} the feature \Option{numberline} of a list of - something has been activated (see \DescRef{\LabelBase.cmd.setuptoc}, - \autoref{sec:tocbasic.toc}, \DescPageRef{\LabelBase.cmd.setuptoc}), i.\,e., - if a \KOMAScript{} class with option + If\textnote{Attention!} the \Option{numberline} feature has been activated + for a content list (see \DescRef{\LabelBase.cmd.setuptoc}, + \autoref{sec:tocbasic.toc}, \DescPageRef{\LabelBase.cmd.setuptoc}), as is + the case with the \KOMAScript{} classes when the \OptionValueRef{maincls}{toc}{numberline}% - \IndexOption{toc~=\PValue{numberline}} is used, then the not numbered - entries will nevertheless have a (by default empty) number line using the - format code of \Option{entrynumberformat}.% + \IndexOption{toc~=\textKValue{numberline}} option is used, then the + unnumbered entries will nevertheless have a (by default empty) number line + using the formatting of \Option{entrynumberformat}.% }% \entry{\OptionVName{dynnumwidth}{switch}}{% \PName{switch} is one of the values for simple switches from \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. If the - switch is active with style \PValue{tocline}, attribute \PValue{numwidth} - will become a minimum value. If the maximum number width detected at the - previous \LaTeX{} run increased by the value of \PValue{numsep} is greater - than this minimum the calculated value will be used.% + switch is active with the \PValue{tocline} style, the \PValue{numwidth} + attribute specifies a minimum value. If a previous \LaTeX{} run has + determined that the maximum width of the entry numbers of the same level + plus the value of \PValue{numsep} is greater than this minimum, the + calculated value will be used instead.% }% \entry{\OptionVName{entryformat}{command}}{% - This attributes makes the format of the entry. The value should be a - \PName{command} with exactly one argument. The \PName{command} should not - expect the argument to be fully expandable. Commands like - \Macro{MakeUppercase}, that need a fully expandable argument, must no be - used here. Font changes are allowed and are relative to - \Macro{normalfont}\Macro{normalsize}. Please note that the output of - \Option{linefill} and the page number are independent from - \Option{entryformat}. See also attribute \Option{pagenumberformat}. - - The initial value of the attribute for \PName{entry level} \PValue{part} - is printing the argument in \Macro{large}\Macro{bfseries} and for - \PValue{chapter} printing the argument in \Macro{bfseries}. If currently - no level \PValue{chapter} exists, \PValue{section} used - \Macro{bfseries}. All other levels print the argument unchanged.% + You can use this attributes to change the format of the entry. The value + should be a \PName{command} with exactly one argument. This argument is + not necessarily fully expandable. You should not use commands like + \Macro{MakeUppercase}, which expects a fully expandable argument. Font + changes are relative to \Macro{normalfont}\Macro{normalsize}. Note that + the output of \Option{linefill} and the page number are independent of + \Option{entryformat}. See also the \Option{pagenumberformat} attribute . + + The initial value of the attribute for the \PValue{part} \PName{entry + level} is \Macro{large}\Macro{bfseries}, and for \PValue{chapter}, it is + \Macro{bfseries}. If the \PValue{chapter} level is not defined, + \PValue{section} uses \Macro{bfseries}. All other levels print the + argument unchanged.% }% \entry{\OptionVName{entrynumberformat}{command}}{% - This attribute makes the format of the entry number within + You can use this attribute to format the entry number within \DescRef{\LabelBase.cmd.numberline}. The value should be a \PName{command} with exactly one argument. Font changes are relative to the one of attribute \Option{entryformat}. @@ -1293,135 +1331,148 @@ command \Macro{l@\PName{entry level}}. The initial \PName{command} prints the argument unchanged. This means the entry number will be printed as it is. - If\textnote{Attention!} the feature \Option{numberline} of a list of - something has been activated (see \DescRef{\LabelBase.cmd.setuptoc}, - \autoref{sec:tocbasic.toc}, \DescPageRef{\LabelBase.cmd.setuptoc}), i.\,e., - if a \KOMAScript{} class with option + If\textnote{Attention!} the \Option{numberline} feature for a content list + has been activated (see \DescRef{\LabelBase.cmd.setuptoc}, + \autoref{sec:tocbasic.toc}, \DescPageRef{\LabelBase.cmd.setuptoc}), as is + the case with the \KOMAScript{} classes using the \OptionValueRef{maincls}{toc}{numberline}% - \IndexOption{toc~=\PValue{numberline}} - is used, then the not numbered entries will nevertheless execute the - \PName{command}.% + \IndexOption{toc~=\textKValue{numberline}} option, the unnumbered entries + will execute the \PName{command} as well.% }% \entry{\OptionVName{indent}{length}}{% - Horizontal distance of the entry relative to the left margin (siehe + The horizontal distance of the entry from the left margin (see \autoref{fig:tocbasic.dottedtocline} and \autoref{fig:tocbasic.tocline}). - At style \PValue{tocline} all entry levels with a name that starts with - ``\texttt{sub}'' are initialised with the sum of the values of - \PValue{indent} and \PValue{numwidth} of the entry level without this - prefix. At styles \PValue{dottedtocline}, \PValue{undottedtocline} and - \PValue{tocline} the initial values of levels \PValue{part} down to - \PValue{subparagraph} and the levels \PValue{figure} and \PValue{table} - are compatible with the standard classes. All other levels do not have an - initial value. Therefore you have to set an explicit value for such levels - when they are defined first time.% + For the \PValue{tocline} style, all entry levels whose names start with + ``\texttt{sub}'' are initialised with the + \PValue{indent}+\PValue{numwidth} of the entry level of the same name + without this prefix. For the \PValue{dottedtocline}, + \PValue{undottedtocline}, and \PValue{tocline} styles, the initial values + of levels \PValue{part} down to \PValue{subparagraph} and the levels + \PValue{figure} and \PValue{table} are compatible with the standard + classes. All other levels do not have an initial value. Therefore you have + to set an explicit value for such levels when they are defined first + time.% }% \entry{\OptionVName{level}{integer}}{% - The numerical value of the \PName{entry level}. Only those entries are - printed that have a numerical value less or equal to counter + The numerical value of the \PName{entry level}. Only those entries whose + numerical value is less than or equal to the \DescRef{\LabelBase.counter.tocdepth}% - \important{\DescRef{\LabelBase.counter.tocdepth}}\IndexCounter{tocdepth}. + \important{\DescRef{\LabelBase.counter.tocdepth}}\IndexCounter{tocdepth} + counter are printed. This attribute is mandatory for all styles and will be defined - automatically at the declaration of the style. - - At style \PValue{tocline} all entry levels with a name starting with - ``\texttt{sub}'', the initial value is the level value of the entry level - without this prefix increased by one. At the styles - \PValue{dottedtocline}, \PValue{largetocline}, \PValue{tocline}, and - \PValue{undottedtocline} entry levels \PValue{part} down to - \PValue{subparagraph}, \PValue{figure}, and \PValue{table} are initialised - compatible with the standard classes. For all other levels the + automatically when the style is declared. + + For the \PValue{tocline} style, all entry levels whose name starts with + ``\texttt{sub}'' are initialised with the value of the entry level of the + same name without this prefix plus one. For the \PValue{dottedtocline}, + \PValue{largetocline}, \PValue{tocline}, and \PValue{undottedtocline} + styles, the entry levels from \PValue{part} to \PValue{subparagraph}, as + well as \PValue{figure} and \PValue{table}, are initialised to be + compatible with the standard classes. For all other levels, the initialisation is done with the value of \Macro{\PName{entry - level}numdepth} if this is defined.% + level}numdepth}, if this is defined.% }% \entry{\OptionVName{linefill}{code}}{% - At style \PValue{tocline} there can be a filler between the end of the - entry text and the page number. The value of attribute \PName{linefill} is - a \PName{code} that prints this filler. For \PName{entry level} - \PValue{part} and \PValue{chapter} the attribute is initialised with - \Macro{hfill}. If currently no \PName{entry level} \PValue{chapter} has - been defined, \PValue{section} also uses \Macro{hfill}. All other entry - levels are initialised with \DescRef{\LabelBase.cmd.TOCLineLeaderFill} (see + With the \PValue{tocline} style, you can change what is used to fill the + space between the end of the entry text and the page number. The + \PName{linefill} attribute contains the \PName{code} that prints this + filler. For the \PValue{part} and \PValue{chapter} \PName{entry level}s, + the attribute is initialised with \Macro{hfill}. If no \PValue{chapter} + \PName{entry level} has been defined, \PValue{section} also uses + \Macro{hfill}. All other entry levels are initialised with + \DescRef{\LabelBase.cmd.TOCLineLeaderFill} (see \DescPageRef{\LabelBase.cmd.TOCLineLeaderFill}). - If \PName{code} does not result in filling the distance, you should also - activate attribute \PValue{raggedpagenumber}, to avoid ``\texttt{underfull - \Macro{hbox}}'' messages.% + Incidentally, if the \PName{code} specified does not automatically fill + the gap, you should also activate the \PValue{raggedpagenumber} attribute + to avoid ``\texttt{underfull \Macro{hbox}}'' messages.% }% \entry{\OptionVName{numsep}{length}}{% - Style \PValue{tocline} tries to ensure a minimum distance of + The \PValue{tocline} style tries to ensure a minimum distance of \PName{length} between the entry number and the entry text. If \PValue{dynnumwidth} is active, it will correct the number width to achieve - this. Otherwise it simply throws a warning, if the condition is missed. + this. Otherwise it simply throws a warning, if the condition is not met. The initial \PName{length} is 0.4\Unit{em}.% }% \entry{\OptionVName{numwidth}{length}}{% - The reserved width for the entry number (see - \autoref{fig:tocbasic.dottedtocline} until - \autoref{fig:tocbasic.undottedtocline}). At the styles - \PValue{dottedtocline}, \PValue{tocline}, and \PValue{undottedtocline} - this \PName{length} will be added to the \PName{length} of attribute - \PValue{indent} for the second and each following entry text line. - - At style \PValue{tocline} the initial \PName{length} of all entries with - a name starting with ``\texttt{sub}'' is the value of the level without - this prefix plus 0.9\Unit{em}. At the styles \PValue{dottedtocline}, - \PValue{undottedtocline} and \PValue{tocline} the initial \PName{length} - of levels \PValue{part} down to \PValue{subparagraph} and levels - \PName{figure} and \PName{table} is compatible to the standard - classes. All other levels do not have an initial value. Therefore you - have to explicitly set \PValue{numwidth} at the first definition of the - entry.% + The width reserved for the entry number (see + \autoref{fig:tocbasic.dottedtocline} to + \autoref{fig:tocbasic.undottedtocline}). With the \PValue{dottedtocline}, + \PValue{tocline}, and \PValue{undottedtocline} styles, this \PName{length} + is added to the \PName{length} of attribute \PValue{indent} for the second + and following lines of the entry text. + + With the \PValue{tocline} style, the initial \PName{length} of all entries + whose name starts with ``\texttt{sub}'' is the value of the level without + this prefix plus 0.9\Unit{em}, if such a level with corresponding + attributes exists. With the \PValue{dottedtocline}, + \PValue{undottedtocline}, and \PValue{tocline} styles, the initial + \PName{length}s of levels from \PValue{part} to \PValue{subparagraph}, as + well as \PName{figure} and \PName{table}, are compatible with those of the + standard classes. All other levels do not have an initial value. Therefore + you must set \PValue{numwidth} explicitly when the entry level is first + used.% }% \entry{\OptionVName{onstarthigherlevel}{code}}{% - Style \PValue{tocline} can execute \PName{code} at the start of an entry, - if the numerical level is greater than the numerical level of the previous - entry. Remember: The numerical level of, e.\,g., \PValue{section} is - greater than the numerical level of \PValue{part}. Nevertheless - \PValue{part} has the highest position in the entry hierarchy. + The \PValue{tocline} style can execute \PName{code} at the start of an entry, + depending on whether the previous entry had numerical level greater than, + the same as, or less than the current + entry. The \PName{code} specified by this attribute will be executed if the + current entry has a greater numerical value, i.\,e. it is + lower in the entry hierarchy, than the previous one. - Please note that the detection of the level of the previous entry depends - on a valid unchanged value of \Macro{lastpenalty}. + Note that detecting the level of the previous entry only works so long as + \Macro{lastpenalty} has not changed since the previous entry. The initial \PName{code} is \DescRef{\LabelBase.cmd.LastTOCLevelWasLower} (see \DescPageRef{\LabelBase.cmd.LastTOCLevelWasLower}).% }% \entry{\OptionVName{onstartlowerlevel}{code}}{% - Style \PValue{tocline} can execute \PName{code} at the start of an entry, - if the numerical level is lower than the numerical level of the previous - entry. Remember: The numerical level of, e.\,g., \PValue{part} is - lower than the numerical level of \PValue{section}. Nevertheless - \PValue{part} has the highest position in the entry hierarchy. - - Please note that the detection of the level of the previous entry depends - on a valid unchanged value of \Macro{lastpenalty}. - - The initial \PName{code} is \DescRef{\LabelBase.cmd.LastTOCLevelWasHigher} (see - \DescPageRef{\LabelBase.cmd.LastTOCLevelWasHigher}).% + The \PValue{tocline} style can execute \PName{code} at the start of an + entry, depending on whether the previous entry had numerical level greater + than, the same as, or less than the current entry. The \PName{code} + specified by this attribute will be executed if the current entry has a + lower numerical value, i.\,e. it is higher in the entry hierarchy, than + the previous one. + + Note that detecting the level of the previous entry only works so long as + \Macro{lastpenalty} has not changed since the previous entry. + + The initial \PName{code} is \DescRef{\LabelBase.cmd.LastTOCLevelWasHigher} + (see \DescPageRef{\LabelBase.cmd.LastTOCLevelWasHigher}), which usually + favours a page break before the entry.% }% \entry{\OptionVName{onstartsamelevel}{code}}{% - Style \PValue{tocline} can execute \PName{code} at the start of an entry, - if the level is same like the level of the previous entry. - - Please note that the detection of the level of the previous entry depends - on a valid unchanged value of \Macro{lastpenalty}. - - The initial \PName{code} is \DescRef{\LabelBase.cmd.LastTOCLevelWasSame} (see - \DescPageRef{\LabelBase.cmd.LastTOCLevelWasSame}).% + The \PValue{tocline} style can execute \PName{code} at the start of an + entry, depending on whether the previous entry had numerical level greater + than, the same as, or less than the current entry. The \PName{code} + specified by this attribute will be executed if the current entry has the + same numerical value, i.\,e. it is on the same level in the entry + hierarchy, as the previous one. + + Note that detecting the level of the previous entry only works so long as + \Macro{lastpenalty} has not changed since the previous entry. + + The initial \PName{code} is \DescRef{\LabelBase.cmd.LastTOCLevelWasSame} + (see \DescPageRef{\LabelBase.cmd.LastTOCLevelWasSame}), which usually + favours a page break before the entry.% }% \entry{\OptionVName{pagenumberbox}{command}}{% - By default the page number of an entry is printed right aligned in a box - of width \Macro{@pnumwidth}. At style \PValue{tocline} the \PName{command} - to print the number can be changed using this attribute. The - \PName{command} should have exactly one argument, the page number.% + By default the page number of an entry is printed flush right in a box + of width \Macro{@pnumwidth}. In the \PValue{tocline} style, you can + change the \PName{command} to print the number using this attribute. The + \PName{command} should expect exactly one argument, the page number. + + This attribute is initialised with the box already mentioned.% }% \entry{\OptionVName{pagenumberformat}{command}}{% - This attribute is the format of the page number of an entry. The - \PName{command} should have exactly one argument, the page number. Font - changes are relative to the font of \Option{entryformat} followed by - \Macro{normalfont}\Macro{normalsize}. + You can use this attribute to change the format of the page number of an + entry. The \PName{command} should expect exactly one argument, the page + number. Font changes are relative to the font of \Option{entryformat} + followed by \Macro{normalfont}\Macro{normalsize}. The initial \PName{command} of entry level \PValue{part} prints the argument in \Macro{large}\Macro{bfseries}. The initial \PName{command} of @@ -1429,28 +1480,30 @@ command \Macro{l@\PName{entry level}}. \Macro{normalfont}\Macro{normalcolor}.% }% \entry{\OptionVName{raggedentrytext}{switch}}{% - \ChangedAt{v3.21}{\Package{tocbasic}}% - \PName{switch} is one of the values for simple switches from - \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. If the - switch is active, style \PValue{tocline} does print the text of an entry - left-aligned instead of justified and only word, that are longer than a - text line, are automatically hyphenated. - - This switch is not active by default.% + The\ChangedAt{v3.21}{\Package{tocbasic}} \PName{switch} is one of the + values for simple switches from \autoref{tab:truefalseswitch}, + \autopageref{tab:truefalseswitch}. If the switch is active, the + \PValue{tocline} style prints the text of an entry ragged right instead of + fully justified, and only words that are longer than a text line are + automatically hyphenated. + + This \PName{switch} is false by default.% }% \entry{\OptionVName{raggedpagenumber}{switch}}{% - \PName{switch} is one of the values for simple switches from + The \PName{switch} is one of the values for simple switches from \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. If the - switch is active, style \PValue{tocline} does not force the page number to - be right aligned. - - Depending on the value of \PValue{linefill}, the setting of this attribute - could be needed for the wanted printing of the number, or only to avoid - unwanted warning messages. So both attributes should correspond. - - By default the switch is not activated and therefore corresponds with an - initial value \Macro{hfill} or \DescRef{\LabelBase.cmd.TOCLineLeaderFill} of attribute - \PValue{linefill}.% + switch is active, the \PValue{tocline} style does not force the page + number to be right justified. + + Depending on the value of \PValue{linefill}, setting this attribute could + affect only whether a warning message appears, or the formatting of the + page number as well. So it is important to set both attributes so that + they correspond. + + By default the \PName{switch} is not activated and therefore corresponds + with an initial value of \Macro{hfill} or + \DescRef{\LabelBase.cmd.TOCLineLeaderFill} for the \PValue{linefill} + attribute.% }% \end{desclist}% % @@ -1495,101 +1548,103 @@ command \Macro{l@\PName{entry level}}. %\OParameter{initial code}% \end{Declaration} \Macro{DeclareTOCEntryStyle}\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} is -one of the most complex commands in \KOMAScript. It is addressed to \LaTeX{} -developers not the \LaTeX{} users. It provides the definition of a new -TOC-entry \PName{style}. Usually TOC-entries are made using -\Macro{addcontentsline}\IndexCmd{addcontentsline}, or, if you use -\Package{tocbasic}, with recommended +one of the most complex commands in \KOMAScript. It is therefore explicitly +intended for \LaTeX{} developers and not for ordinary \LaTeX{} users. It lets +you define new a \PName{style} for content-list entries. Usually, entries to +content lists are made using +\Macro{addcontentsline}\IndexCmd{addcontentsline}, or preferably, if you use +\Package{tocbasic}, with \DescRef{\LabelBase.cmd.addxcontentsline}\IndexCmd{addxcontentsline} (see -\autoref{sec:tocbasic.basics}, -\DescPageRef{\LabelBase.cmd.addxcontentsline}). In both cases \LaTeX{} -writes a corresponding \Macro{contentsline}\IndexCmd{contentsline} into the -given auxiliary file. Reading this auxiliary file each \Macro{contentsline} -results in execution of a command \Macro{l@\PName{entry level}}. - -Whenever you assign a \PName{style} to a TOC-entry level using -\DescRef{\LabelBase.cmd.DeclareTOCStyleEntry}, first of all the \PName{initial - code} is executed and then \Macro{l@\PName{entry level}} is defined to be -\PName{command code}. So \PName{command code} is the code that will be -expanded and executed by \Macro{l@\PName{entry level}}. Inside \PName{command - code} \texttt{\#1} is the name of the TOC-entry level and \texttt{\#\#1} and -\texttt{\#\#2} are the arguments of \Macro{l@\PName{entry level}}. - -The \PName{initial code} should initialise all attributes of the -\PName{style}. Developers are recommended to use \PName{initial code} to -initialise all internal macros of the \PName{style} without the need of -using an \PName{option list}. The second task of the \PName{initial code} is -the definition of options to setup the attributes of the \PName{style}. Option -\Option{level} is always defined automatically. The value of \Option{level} -can be got in \PName{command code} using -\Macro{@nameuse}\PParameter{\#1tocdepth}% -\important{\Macro{\PName{entry level}tocdepth}}, e.\,g., to compare it with -the counter \DescRef{\LabelBase.counter.tocdepth}\IndexCounter{tocdepth}. - -Commands \Macro{DefineTOCEntryBooleanOption}, +\autoref{sec:tocbasic.basics}, \DescPageRef{\LabelBase.cmd.addxcontentsline}). +In both cases \LaTeX{} writes a corresponding +\Macro{contentsline}\IndexCmd{contentsline} to the appropriate auxiliary file. +When reading this auxiliary file, \LaTeX{} then executes a +\Macro{l@\PName{entry level}} command for each \Macro{contentsline}. + +If you later assign a \PName{style} to an entry level using +\DescRef{\LabelBase.cmd.DeclareTOCStyleEntry}, the \PName{initial code} is +executed first, if provided, and then the \PName{command code} for the +definition of \Macro{l@\PName{entry level}}. The \PName{command code} is the +code that will be expanded and executed by \Macro{l@\PName{entry level}}. +Inside \PName{command code} \texttt{\#1} is the name of the TOC entry level +and \texttt{\#\#1} and \texttt{\#\#2} are the arguments of +\Macro{l@\PName{entry level}}. + +The \PName{initial code} serves first to initialise all attributes of the +\PName{style}. Developers should make sure that all attributes are provided +with values here. Only then does \DescRef{\LabelBase.cmd.DeclareTOCStyleEntry} +work without errors if an \PName{option list} is not specified. The second +task of the \PName{initial code} is to define all the options that this +\PName{style} recognises. The \Option{level} option is always defined +automatically. The value of the \Option{level} can be queried within the +\PName{command code} with \Macro{@nameuse}\PParameter{\#1tocdepth}% +\important{\Macro{\PName{entry level}tocdepth}}, for example, to compare it +with the \DescRef{\LabelBase.counter.tocdepth}\IndexCounter{tocdepth} counter. + +To define options for the attributes of the +\PName{style} inside the \PName{initial code}, you can use the commands \Macro{DefineTOCEntryBooleanOption}, \Macro{DefineTOCEntryCommandOption}, \Macro{DefineTOCEntryIfOption}, -\Macro{DefineTOCEntryLengthOption}, and \Macro{DefineTOCEntryNumberOption} -should be used to define options for the attributes of the -\PName{style} inside \PName{initial code} only. If you use an \PName{option} -defined by one of these commands, a macro \Macro{\PName{prefix}\PName{entry - level}\PName{postfix}} will be defined to be the assigned value or the -\PName{default value} of the option. Somehow special is -\Macro{DefineTOCEntryIfOption}. It defines \Macro{\PName{prefix}\PName{entry - level}\PName{postfix}} as a command with two arguments. If the value to -the option is an activation value of \autoref{tab:truefalseswitch}, -\autopageref{tab:truefalseswitch} the command expands to the first -argument. If the value to the option is a deactivation value, the command +\Macro{DefineTOCEntryLengthOption}, and \Macro{DefineTOCEntryNumberOption}. +These commands each define an \PName{option} that, when called, +defines a macro named \Macro{\PName{prefix}\PName{entry + level}\PName{postfix}} set to the given value or to the +\PName{default value} of the option. The +\Macro{DefineTOCEntryIfOption} command is a somewhat special case. It defines \Macro{\PName{prefix}\PName{entry + level}\PName{postfix}} as a command with two arguments. If the value passed to +the option is one of the activation (true) values from \autoref{tab:truefalseswitch}, +\autopageref{tab:truefalseswitch}, the command expands to the first +argument. If the value to the option is a deactivation (false) value, the command expands to the second argument. -The \PName{description} should be a real short text that describes the sense -of the option with some catchwords. Package \Package{tocbasic} uses this text -in error messages, warnings or information output on the terminal and into the -\File{log}-file. +The \PName{description} should be a brief message that describes the sense +of the option with some keywords. The \Package{tocbasic} package uses this text +in error messages, warnings, and information output on the terminal and to the +\File{log} file. -The most simple style of \Package{tocbasic}, \PValue{gobble}, is defined +The simplest style of \Package{tocbasic}, \PValue{gobble}, is defined using: \begin{lstcode} \DeclareTOCEntryStyle{gobble}{}% \end{lstcode} -If you would define a entry level \PValue{dummy} using: +If you now define an entry level \PValue{dummy} in this style using: \begin{lstcode} \DeclareTOCStyleEntry[level=1]{gobble}{dummy} \end{lstcode} -among others this would do something like: +this would correspond, among other things, to: \begin{lstcode} \def\dummytocdepth{1} \def\l@dummy#1#2{} \end{lstcode} -Inside style \PValue{tocline} for example +For example, within the \PValue{tocline} style, \begin{lstcode} \DefineTOCEntryCommandOption{linefill}[\TOCLineLeaderFill]% {scr@tso@}{@linefill}{filling between text and page number}% \end{lstcode} -is used to define option \Option{linefill} with \PName{default value} -\DescRef{\LabelBase.cmd.TOCLineLeaderFill}. A call like: +is used to define the \Option{linefill} option. By specifying +\DescRef{\LabelBase.cmd.TOCLineLeaderFill} as the \PName{default value}, +a call such as \begin{lstcode} \RedeclareTOCStyleEntry[linefill]{tocline}{part} \end{lstcode} -would therefore result in a definition like: +would, among other things, create the definition \begin{lstcode} \def\scr@tso@part@linefill{\TOCLineLeaderFill} \end{lstcode} -Whoever likes to define his own styles is recommended to first study the -definition of style \PValue{dottedtocline}. If this definition is understood, -the much more complex definition of style \PValue{tocline} gives a lot of -hints of the correct usage of the described commands. +If you want to define your own styles, you should first study the definition +of the \PValue{dottedtocline} style. After you understand this definition, you +can find many hints as to how to use the commands effectively in the much more +complex definition of the \PValue{tocline} style. -In many cases it will be enough to clone an existing style using +However, in many cases it will be sufficient to clone an existing style using \DescRef{\LabelBase.cmd.CloneTOCEntryStyle} and to change the initial code of the new style using \DescRef{\LabelBase.cmd.TOCEntryStyleInitCode} or \DescRef{\LabelBase.cmd.TOCEntryStyleStartInitCode}. -\Macro{DefineTOCEntryOption} is merely used to define the other -commands. It is not recommended to define options directly using -\Macro{DefineTOCEntryOption}. Normally this is even not needed. It is -alluded only for completeness.% +\Macro{DefineTOCEntryOption} is merely used to define the other commands and +you should not use it directly. Normally, there is no need for it. It is +mentioned here only for the sake of completeness.% \EndIndexGroup @@ -1597,13 +1652,17 @@ alluded only for completeness.% \Macro{CloneTOCEntryStyle}\Parameter{style}\Parameter{new style}% \end{Declaration} With\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} this command you can clone -an existing \PName{style}. This defines a \PName{new style} with the same -attributes and settings like the existing \PName{style}. The package itself -uses \Macro{CloneTOCEntryStyle} to declare style \PValue{default} as a clone -of \PValue{dottedtocline}. The \KOMAScript{} classes use the command to -declare the styles \PValue{part}, \PValue{section}, and \PValue{chapter} or -\PValue{subsection} as a clone of \PValue{tocline} and the style -\PValue{default} new as a clone of \PValue{section} or \PValue{subsection}.% +an existing \PName{style}. It defines a \PName{new style} with the same +attributes and settings as the existing \PName{style}. The package itself uses +\Macro{CloneTOCEntryStyle} to declare the \PValue{default} style as a clone of +\PValue{dottedtocline}. The \KOMAScript{} classes use the command to declare +the styles \PValue{part}, \PValue{section}, and \PValue{chapter} or +\PValue{subsection} as clones of \PValue{tocline} and then modify them with +\DescRef{\LabelBase.cmd.TOCEntryStyleInitCode} and +\DescRef{\LabelBase.cmd.TOCEntryStyleStartInitCode}. The \Class{scrbook} and +\Class{scrreprt} classes newly declare the \PValue{default} style as a clone +of \PValue{section}, and \Class{scrartcl} declares it as a clone of +\PValue{subsection}.% \EndIndexGroup @@ -1615,22 +1674,22 @@ declare the styles \PValue{part}, \PValue{section}, and \PValue{chapter} or \end{Declaration} Every\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} TOC-entry style has an initialisation code. This is used whenever a \PName{style} is assigned to an -TOC-entry using \DescRef{\LabelBase.cmd.DeclareTOCEntryStyle}. This -\PName{initial code} should never do anything global, because it is also used -for local initialisation inside other commands like -\DescRef{\LabelBase.cmd.DeclareNewTOC}\IndexCmd{DeclareNewTOC}. The \PName{initial code} not -only defines all attributes of a \PName{style}. It also should set the -defaults for those attributes. +TOC entry using \DescRef{\LabelBase.cmd.DeclareTOCEntryStyle}. This +\PName{initial code} should not have global side effects, because it is also +used for local initialisation inside other commands like +\DescRef{\LabelBase.cmd.DeclareNewTOC}\IndexCmd{DeclareNewTOC}. The +\PName{initial code} not only defines all attributes of a \PName{style}, but +it also sets the defaults for those attributes. You can use \Macro{TOCEntryStyleStartInitCode} and -\Macro{TOCEntryStyleInitCode} to extend the already existing initialisation -code by \PName{initial code}. \Macro{TOCEntryStyleStartInitCode} adds -\PName{initial code} in front of the existing initialisation -code. \Macro{TOCEntryStyleInitCode} adds the \PName{initial code} at the end -of the existing initialisation code. The \KOMAScript{} classes, e.\,g., are -using \Macro{TOCEntryStyleStartInitCode} to change the filling, font and -vertical distances of style \PValue{part} that is a clone of -\PValue{tocline}. Class \Class{scrbook} and \Class{scrreprt} use +\Macro{TOCEntryStyleInitCode} to extend previously existing initialisation +code with further \PName{initial code}. \Macro{TOCEntryStyleStartInitCode} +adds \PName{initial code} in front of the existing code. +\Macro{TOCEntryStyleInitCode} adds the \PName{initial code} at the end of the +existing initialisation code. The \KOMAScript{} classes, for example, use +\Macro{TOCEntryStyleStartInitCode} to properly initialise the fill, fonts, and +vertical spacing of the \PValue{part} style cloned from \PValue{tocline}. For +example, the \Class{scrbook} and \Class{scrreprt} classes use \begin{lstcode} \CloneTOCEntryStyle{tocline}{section} \TOCEntryStyleStartInitCode{section}{% @@ -1639,7 +1698,7 @@ vertical distances of style \PValue{part} that is a clone of {\TOCLineLeaderFill\relax}% } \end{lstcode} -to declare \PValue{section} as a modified clone of \PValue{tocline}.% +to define \PValue{section} as a modified clone of \PValue{tocline}.% \EndIndexGroup @@ -1648,33 +1707,32 @@ to declare \PValue{section} as a modified clone of \PValue{tocline}.% \Macro{LastTOCLevelWasSame}% \Macro{LastTOCLevelWasLower} \end{Declaration} -At\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} the very beginning entries -with style \PValue{tocline} \Package{tocbasic} executes one of these three -commands depending on \Macro{lastpenalty}. \Macro{LastTOCLevelWasHigher} and -\Macro{LastTOCLevelWasSame} used in vertical mode add -\Macro{addpenalty}\PParameter{\Macro{@lowpenalty}} and therefore permit a -page break before an entry with same or higher hierarchical -position. \Macro{LastTOCLevelWasLower} is an empty command. Therefore page -break between an entry and its sub-entry is not permitted. - -Users should not redefine these commands. Instead of a redefinition you should -change the behaviour of single entry levels using attributes -\PValue{onstartlowerlevel}, \PValue{onstartsamelevel}, and -\PValue{onstarthigherlevel}.% +At\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} the beginning of entries +using the \PValue{tocline} style, \Package{tocbasic} executes one of these +three commands depending on \Macro{lastpenalty}. \Macro{LastTOCLevelWasHigher} +and \Macro{LastTOCLevelWasSame} used in vertical mode add +\Macro{addpenalty}\PParameter{\Macro{@lowpenalty}} and therefore permit a page +break before an entry with the same or higher hierarchical position. +\Macro{LastTOCLevelWasLower} is empty, so a page break between an entry and +its first sub-entry is not permitted. + +Users should not redefine these commands. Instead, you should change the +behaviour of single entry levels using the \PValue{onstartlowerlevel}, +\PValue{onstartsamelevel}, and \PValue{onstarthigherlevel} attributes.% \EndIndexGroup \begin{Declaration} - \Macro{TOCLineLeaderFill}\OParameter{filling code} + \Macro{TOCLineLeaderFill}\OParameter{leader} \end{Declaration} -Command\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} has been made to be used -as value of option \Option{linefill} of assigning style \PName{tocline} to a -TOC-entry. It is a line filler between the end of the entry text and the entry -page number. The \PName{filling code} will be repeated with constant -distance. The default for this optional argument is a dot. - -As implied by the name of the command it uses \Macro{leaders} to put the -\PName{filling code}. The distance is defined analogous to the \LaTeX{} kernel +This\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} command is intended to be +used as a value for the \Option{linefill} option of the \PName{tocline} +TOC-entry style. It creates a connection between the end of the entry text and +the entry's page number. You can specify the \PName{leader}, which is repeated +at regular intervals, as an optional argument. The default is a dot. + +As the name suggests, the command uses \Macro{leaders} to output the +\PName{leader}. The spacing used is defined analogously to the \LaTeX{} kernel command \Macro{@dottedtocline} by \Macro{mkern}\Macro{@dotsep}\Unit{\texttt{mu}}.% \EndIndexGroup @@ -1682,75 +1740,79 @@ command \Macro{@dottedtocline} by \section{Internal Commands for Class and Package Authors} -\label{sec:tocbasic.internals} +\seclabel{internals} -Commands with prefix \Macro{tocbasic@} are internal but class and package -authors may use them. But even if you are a class or package author you -should not change them! +The \Package{tocbasic} package provides some internal commands for the use of +class and package authors. These commands all begin with the prefix +\Macro{tocbasic@}. But\textnote{Attention!} even class or package authors +should not redefine them! Their inner functioning may be changed or extended +at any time, so redefining these commands could significantly damage the +\Package{tocbasic}'s operation. \begin{Declaration} \Macro{tocbasic@extend@babel}\Parameter{extension} \end{Declaration} -The Package \Package{babel}\IndexPackage{babel} (see \cite{package:babel}), -or more specifically a \LaTeX{} kernel that has been extended by the language -management of \Package{babel} writes instructions to change the language -inside of the files with the file name extensions \File{toc}, \File{lof}, and -\File{lot} into those files at every change of the current language either at -the begin of the document or inside the document. Package \Package{tocbasic} -extends this mechanism with \Macro{tocbasic@extend@babel} to be used for other -file name extensions too. Argument \PName{extension} has to be expandable! -Otherwise the meaning of the argument may change until it will be used really. - -Normally this command will be used by default for every file name -\PName{extension} that will be added to the list of known extensions using -\DescRef{\LabelBase.cmd.addtotoclist}. This may be suppressed using feature -\PValue{nobabel}\important{\PValue{nobabel}} (see \DescRef{\LabelBase.cmd.setuptoc}, -\autoref{sec:tocbasic.toc}, \DescPageRef{\LabelBase.cmd.setuptoc}). For the file -name extensions \File{toc}, \File{lof}, and \File{lot} this will be done -automatically by \Package{tocbasic} to avoid double language switching in the -corresponding files. - -Normally there isn't any reason to call this command yourself. But there may -by lists of something, that should not be under control of \Package{tocbasic}, -and so are not in \Package{tocbasic}'s list of known file name extensions, but -nevertheless should be handled by the language change mechanism of -\Package{babel}. The command may be used explicitly for those files. But please -note that this should be done only once per file name extension!% +At every change of the current language, either at the beginning of the +document or inside the document, the \Package{babel}\IndexPackage{babel} +package (see \cite{package:babel}), or rather a \LaTeX{} kernel enhanced by +\Package{babel}'s language management, writes language-switching commands to +the files with the \File{toc}, \File{lof}, and \File{lot} extensions. The +\Package{tocbasic} package extends this mechanism with +\Macro{tocbasic@extend@babel} so that it also works for other file extensions. +The \PName{extension} argument must be completely expanded! Otherwise the +there is a risk that, for example, the meaning of the argument has already +change at the time it is actually evaluated. + +This command is typically invoked by default for every file \PName{extension} +added to the list of known extensions with +\DescRef{\LabelBase.cmd.addtotoclist}. You can suppress this with the +\PValue{nobabel}\important{\PValue{nobabel}} feature (see +\DescRef{\LabelBase.cmd.setuptoc}, \autoref{sec:tocbasic.toc}, +\DescPageRef{\LabelBase.cmd.setuptoc}). \Package{tocbasic} does this +automatically for the extensions \File{toc}, \File{lof}, and \File{lot} to +avoid switching languages twice in the corresponding files. + +There is usually no reason to call this command yourself. However, there could +conceivably be content lists that are not under the control of +\Package{tocbasic} and so are not in \Package{tocbasic}'s list of known file +extensions, but which nevertheless should use \Package{babel}'s language +switching mechanism. You can call the command explicitly for those files. +But\textnote{Attention!} please note that this should be done only once per +file extension!% \EndIndexGroup \begin{Declaration} \Macro{tocbasic@starttoc}\Parameter{extension} \end{Declaration} -This command is something like the \LaTeX{} kernel macro -\Macro{@starttoc}\IndexCmd{@starttoc}\important{\Macro{@starttoc}}. It is the -command behind \DescRef{\LabelBase.cmd.listoftoc*} (see \autoref{sec:tocbasic.toc}, -\DescPageRef{\LabelBase.cmd.listoftoc*}). Authors of classes or packages -who want to participate from the advantages of \Package{tocbasic} should at -least use this command. Nevertheless it is recommended to use -\DescRef{\LabelBase.cmd.listoftoc}. Command \Macro{tocbasic@starttoc} internally uses -\Macro{\@starttoc}, but sets +This command is the actual replacement for the +\Macro{@starttoc}\IndexCmd{@starttoc}\important{\Macro{@starttoc}} command +from the \LaTeX{} kernel. It is the command behind +\DescRef{\LabelBase.cmd.listoftoc*} (see \autoref{sec:tocbasic.toc}, +\DescPageRef{\LabelBase.cmd.listoftoc*}). Class or package authors who want to +take advantage of \Package{tocbasic} should at least use this command, or even +better, \DescRef{\LabelBase.cmd.listoftoc}. The command uses +\Macro{\@starttoc} internally, but sets \Length{parskip}\IndexLength{parskip}\important{\Length{parskip}\\ - \Length{parindent}\\ - \Length{parfillskip}} and \Length {parindent}\IndexLength{parindent} to 0 -and \Length{parfillskip} to 0 until infinite before. Moreover, -\Macro{@currext}\important{\Macro{@currext}}\IndexCmd{@currext} will be set to -the file name extension of the current TOC-file, so this will be available -while the execution of the hooks, that will be done before and after reading -the auxiliary files. - -Because\textnote{Attention!} of \LaTeX{} will immediately open a new TOC-file -for writing after reading that file, the usage of \Macro{tocbasic@starttoc} -may result in an error message like +\Length{parindent}\\ \Length{parfillskip}}, +\Length{parindent}\IndexLength{parindent} to 0, and \Length{parfillskip} to 0 +to infinity. Moreover, +\Macro{@currext}\important{\Macro{@currext}}\IndexCmd{@currext} is set to the +file extension of the current TOC file, so it can be evaluated during the +subsequent execution of the hooks. You can find an explanation of these hooks +below. + +Because\textnote{Attention!} \LaTeX{} opens a new content-list file for +writing after reading that file, calling this command may result in an error +message of the type \begin{lstoutput} ! No room for a new \write . \ch@ck ...\else \errmessage {No room for a new #3} \fi \end{lstoutput} -if there are no more unused write handles. This may be solved, e.\,g., using -package -\Package{scrwfile}\important{\Package{scrwfile}}\IndexPackage{scrwfile}. -See \autoref{cha:scrwfile} for more information about that package.% +if no more write handles are available. You can solve this problem by loading +the \Package{scrwfile}\important{\Package{scrwfile}}\IndexPackage{scrwfile} +package described in \autoref{cha:scrwfile}, or by using Lua\LaTeX{}.% \EndIndexGroup @@ -1758,27 +1820,27 @@ See \autoref{cha:scrwfile} for more information about that package.% \Macro{tocbasic@@before@hook}% \Macro{tocbasic@@after@hook} \end{Declaration} -The hook \Macro{tocbasic@@before@hook} will be executed immediately before -reading a auxiliary file for a TOC even before execution of the instructions -of a \DescRef{\LabelBase.cmd.BeforeStartingTOC} command. It is permitted to -extend this hook using \Macro{g@addto@macro}\IndexCmd{g@addto@macro}. - -Similarly \Macro{tocbasic@@after@hook} will be executed immediately after -reading such an auxiliary file and before execution of instructions of -\DescRef{\LabelBase.cmd.AfterStartingTOC}. It is permitted to extend this hook -using \Macro{g@addto@macro}\IndexCmd{g@addto@macro}. - -\KOMAScript{} uses these hooks, to provide the automatic width calculation of -the place needed by heading numbers. Only classes and packages should use -these hooks. Users\textnote{Attention!} should really use +The \Macro{tocbasic@@before@hook} hook is executed immediately before reading +an auxiliary file for a content list, before executing the commands defined +with \DescRef{\LabelBase.cmd.BeforeStartingTOC} command. You can extend this +hook using \Macro{g@addto@macro}\IndexCmd{g@addto@macro}. + +Similarly, \Macro{tocbasic@@after@hook} is executed immediately after reading +such an auxiliary file and before executing the commands defined with +\DescRef{\LabelBase.cmd.AfterStartingTOC}. You can extend this hook using +\Macro{g@addto@macro}\IndexCmd{g@addto@macro}. + +\KOMAScript{} uses these hooks to dynamically adjust content lists to the +width of the heading numbers. Only classes and packages should use these +hooks. Users\textnote{Attention!} should really use \DescRef{\LabelBase.cmd.BeforeStartingTOC} and \DescRef{\LabelBase.cmd.AfterStartingTOC} instead. Authors of packages should -also favour those commands! These hooks should not be used to generate any +also prefer these commands. These hooks should not be used to generate any output! If neither\textnote{Attention!} \DescRef{\LabelBase.cmd.listofeachtoc} nor \DescRef{\LabelBase.cmd.listoftoc} nor \DescRef{\LabelBase.cmd.listoftoc*} are -used for the output of a TOC, the hooks should be executed explicitly.% +used to output the content list, the hooks should be executed explicitly.% \EndIndexGroup @@ -1786,26 +1848,31 @@ used for the output of a TOC, the hooks should be executed explicitly.% \Macro{tocbasic@\PName{extension}@before@hook}% \Macro{tocbasic@\PName{extension}@after@hook} \end{Declaration} -These hooks are processed after \DescRef{\LabelBase.cmd.tocbasic@@before@hook}, respectively -before \DescRef{\LabelBase.cmd.tocbasic@@after@hook} before and after loading the TOC-file with -the corresponding file \PName{extension}. Authors\textnote{Attention!} of -classes and packages should never manipulate them! But if +These hooks are executed directly after +\DescRef{\LabelBase.cmd.tocbasic@@before@hook} or before +\DescRef{\LabelBase.cmd.tocbasic@@after@hook} for the TOC file with the +corresponding file \PName{extension}. Class\textnote{Attention!} and package +authors should never change them under any circumstances! If neither\textnote{Attention!} \DescRef{\LabelBase.cmd.listofeachtoc} nor \DescRef{\LabelBase.cmd.listoftoc} nor \DescRef{\LabelBase.cmd.listoftoc*} are -used for the output of a TOC, the hooks should be executed explicitly, if they -are defined. Please note that they even can be undefined.% +used to output a content list, the hooks should nevertheless be called, if +they are defined. These commands can be undefined. For an appropriate test, +see \DescRef{scrbase.cmd.scr@ifundefinedorrelax}% +\IndexCmd{scr@ifundefinedorrelax} in \autoref{sec:scrbase.if}, +\DescPageRef{scrbase.cmd.scr@ifundefinedorrelax}.% \EndIndexGroup \begin{Declaration} \Macro{tocbasic@listhead}\Parameter{title} \end{Declaration} -This command is used by \DescRef{\LabelBase.cmd.listoftoc} to set the heading of the TOC, -either the default heading or the individually defined heading. If you define -your own TOC-command not using \DescRef{\LabelBase.cmd.listoftoc} you may use -\Macro{tocbasic@listhead}. In this case you should define +This command is used by \DescRef{\LabelBase.cmd.listoftoc} and +\DescRef{\LabelBase.cmd.listofeachtoc} to set the heading of the content list. +This can be either the default heading of the \Package{tocbasic} package or a +custom definition. If you define your own command for the heading, you can +also use \Macro{tocbasic@listhead}. In this case, you should define \Macro{@currext}\important{\Macro{@currext}}\IndexCmd{@currext} to be the file -extension of the corresponding TOC-file before using +extension of the corresponding TOC file before using \Macro{tocbasic@listhead}.% \EndIndexGroup @@ -1813,10 +1880,10 @@ extension of the corresponding TOC-file before using \begin{Declaration} \Macro{tocbasic@listhead@\PName{extension}}\Parameter{title} \end{Declaration} -This command is used in \DescRef{\LabelBase.cmd.tocbasic@listhead} to set the individual -headings, optional table of contents entry, and running head, if it was -defined. If it was not defined it will be defined and used in -\DescRef{\LabelBase.cmd.tocbasic@listhead} automatically. +This command is used in \DescRef{\LabelBase.cmd.tocbasic@listhead} to set the +individual headings, optional table of contents entry, and running head, if it +is defined. Otherwise, \DescRef{\LabelBase.cmd.tocbasic@listhead} defines them +before their use.% \EndIndexGroup @@ -1825,22 +1892,21 @@ defined. If it was not defined it will be defined and used in \Parameter{extension}\Parameter{level}\Parameter{number}\Parameter{text}% \Macro{nonumberline} \end{Declaration} -Command\ChangedAt{v3.12}{\Package{tocbasic}} \Macro{tocbasic@addxcontentsline} -uses \Macro{addcontentsline} to either create a numbered or not numbered text -entry to the TOC-file with the given \PName{extension}. Note, all parameters -of \Macro{tocbasic@addxcontentsline} are mandatory. But you may use an empty -\PName{number} argument, if you do not want a number. In this case the -\PName{text} will be prefixed by \Macro{nonumberline} without any argument. In -the other case, if \PName{number} is not empty, -\DescRef{\LabelBase.cmd.numberline} with argument \PName{number} will used as -usual. - -Command \Macro{nonumberline} is redefined inside +The\ChangedAt{v3.12}{\Package{tocbasic}} \Macro{tocbasic@addxcontentsline} +command creates entry of the specified level in the TOC file with the given +\PName{extension}. Whether the entry is numbered or not depends on whether or +not the \PName{number} argument is empty. In this case the \PName{text} will +be prefixed by \Macro{nonumberline} without any argument. Otherwise, +\DescRef{\LabelBase.cmd.numberline} with the \PName{number} argument will used +as usual. + +The \Macro{nonumberline} command is redefined inside \DescRef{\LabelBase.cmd.listoftoc} (see \autoref{sec:tocbasic.toc}, -\DescPageRef{\LabelBase.cmd.listoftoc}) depending on feature \PValue{numberline} -(see \autoref{sec:tocbasic.toc}, \DescPageRef{\LabelBase.cmd.setuptoc}). This -guarantees that changes of the feature results in changes of the corresponding -TOC immediately at the next \LaTeX{} run.% +\DescPageRef{\LabelBase.cmd.listoftoc}) depending on the \PValue{numberline} +feature (see \autoref{sec:tocbasic.toc}, +\DescPageRef{\LabelBase.cmd.setuptoc}). As a result, changing this feature +results in changes of the corresponding TOC immediately at the next \LaTeX{} +run.% \EndIndexGroup @@ -1848,41 +1914,36 @@ TOC immediately at the next \LaTeX{} run.% \Macro{tocbasic@DependOnPenaltyAndTOCLevel}\Parameter{entry level}% \Macro{tocbasic@SetPenaltyByTOCLevel}\Parameter{entry level} \end{Declaration} -At\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} the end of TOC-entry style -\PValue{tocline} (see \autoref{sec:tocbasic.tocstyle}) \Macro{penalty} is set -to prohibit page breaks. The used penalty value depends on the \PName{entry - level}. This is done by \Macro{tocbasic@SetPenaltyByTOCLevel}. At the very -beginning of an entry \Macro{tocbasic@DependOnPenaltyAndTOCLevel} is used to -execute the value of either style option \Option{onstartlowerlevel}, -\Option{onstartsamelevel}, or \Option{onstarthigherlevel} depending on -\Macro{lastpenalty} and the current \PName{entry level}. The default of the -first and second option would be to permit a page break, if used in vertical -mode. - -Developers of \PValue{tocline}-compatible styles should adapt this. To do so, -they are even allowed to copy the style option declarations of -\Option{onstartlowerlevel}, \Option{onstartsamelevel}, and -\Option{onstarthigherlevel}. These options should even use the same internal -macros \Macro{scr@tso@\PName{entry level}@LastTOCLevelWasHigher}, -\Macro{scr@tso@\PName{entry level}@LastTOCLevelWasSame} and -\Macro{scr@tso@\PName{entry level}@LastTOCLevelWasLower} to store the current -values of the options.% +The\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} \PValue{tocline} +content-list style (see \autoref{sec:tocbasic.tocstyle}) sets a +\Macro{penalty} at the end of each entry via +\Macro{tocbasic@SetPenaltyByTOCLevel} so that no page break can occur after an +entry. The exact value chosen depends on the \PName{entry level}. + +At the beginning of an entry, \Macro{tocbasic@DependOnPenaltyAndTOCLevel} is +used to execute the value of the \Option{onstartlowerlevel}, the +\Option{onstartsamelevel}, or the \Option{onstarthigherlevel} style option, +depending on \Macro{lastpenalty} and the current \PName{entry level}. By +default, the first two permit a page break when executed in vertical mode. + +Developers of \PValue{tocline}-compatible styles should copy this behaviour. +To do so, they can fall back on these internal macros.% \EndIndexGroup \section{A Complete Example} \seclabel{example} -This section will show you a complete example of a user defined floating -environment with list of that kind of floats and \KOMAScript{} integration -using \Package{tocbasic}. This example uses internal commands, that have a -``\texttt{@}'' in their name. This means\textnote{Attention}, that the code -has to be put into a package or class, or has to be placed between +This section provides a complete example of how to define your own floating +environment including an associated content list and \KOMAScript{} integration +using \Package{tocbasic}. This example uses internal commands, that is, they +have a ``\texttt{@}'' in their name. This means\textnote{Attention}, that you +must either put the code into a package or class or placed it between \Macro{makeatletter}\important[i]{\Macro{makeatletter}\\\Macro{makeatother}}% \IndexCmd{makeatletter} and \Macro{makeatother}\IndexCmd{makeatother}. -First\textnote{environment} of all, a new floating environment will be -needed. This could simply be done using: +First\textnote{environment}, we need a new floating environment. +That's easy with the following: \begin{lstcode} \newenvironment{remarkbox}{% \@float{remarkbox}% @@ -1890,21 +1951,22 @@ needed. This could simply be done using: \end@float } \end{lstcode} -To the new environment is named \Environment{remarkbox}. +The new environment is named \Environment{remarkbox}. -Each\textnote{placement} floating environment has a default -placement. This is build by some of the well known placement options: +Each\textnote{placement} floating environment has a default placement. It +consists of one or more of the well-known placement options: \PValue{b}, + \PValue{h}, \PValue{p} and \PValue{t}. \begin{lstcode} \newcommand*{\fps@remarkbox}{tbp} \end{lstcode} -So, the new floating environment should be placed by default only either at -the top of a page, at the bottom of a page, or on a page on its own. - -Floating\textnote{type} environments have a numerical floating -type. Environments with the same active bit at the floating type cannot change -their order. Figures and table normally use type~1 and 2. So a figure that -comes later at the source code than a table, may be output earlier than the -table and vica versa. +The new floating environment should be placed by default only either at +the top of a page, at the bottom of a page, or on a separate page. + +Floating\textnote{type} environments also have a numerical floating +type between 1 and 31. Environments with the same active bit at the floating type cannot change +their order. Figures and tables normally use type~1 and 2. So a figure that +comes later in the source code than a table may be output earlier than the +table and vice versa. \begin{lstcode} \newcommand*{\ftype@remarkbox}{4} \end{lstcode} @@ -1918,157 +1980,156 @@ The\textnote{number} captions of floating environment also have numbers. Remark~\theremarkbox\csname autodot\endcsname} \newcommand*{\fnum@remarkbox}{\remarkboxformat} \end{lstcode} -Here first a new counter has been defined, that is independent from chapters +Here, a new counter is defined first, which is independent of the chapters or the counters of other structural levels. \LaTeX{} itself also defines -\Macro{theremarkbox} with the default Arabic representation of the counter's -value. Afterwards this has been used defining the formatted output of the -counter. Last this formatted output has been used for the output of the -environment number of the \DescRef{maincls.cmd.caption} command. - -Floating\textnote{file name extension} environments have lists of themselves -and those need a auxiliary file with name \Macro{jobname} and a file name -extension, the TOC-file\Index{TOC-file}: +\Macro{theremarkbox} with the default output as an Arabic number. +This is then used to define the formatted output of the +counter. The formatted output is again defined as a floating-point +number for use in the \DescRef{maincls.cmd.caption} command. + +Floating\textnote{file name extension} environments have their own content lists +and those need an auxiliary file named \Macro{jobname} and a file +extension: \begin{lstcode} \newcommand*{\ext@remarkbox}{lor} \end{lstcode} -The file name extension of the TOC-file for the list of -\Environment{remarkbox}es is ``\File{lor}''. +As the file extension, we use ``\File{lor}''. -This was the definition of the floating environment. But the list of this new -environment's captions is still missing. To reduce the implementation effort -package \Package{tocbasic} will be used for this. This will be loaded using +With this, the floating environment works. But the content list of +is still missing. So that we do not have to implement it ourselves, we +use the \Package{tocbasic} package. This is loaded with \begin{lstcode} \usepackage{tocbasic} \end{lstcode} -inside of document preambles. Authors of classes or packages would use +inside of document preambles. Class or package authors would use \begin{lstcode} \RequirePackage{tocbasic} \end{lstcode} instead. -Now\textnote{extension} we register the file name extension for package -\Package{tocbasic}: +Now\textnote{extension} we register the file name extension with the +\Package{tocbasic} package: \begin{lstcode} \addtotoclist[float]{lor} \end{lstcode} -Thereby the owner \PValue{float} has been used, to allude all further -\KOMAScript{} options for list of figures and list of tables also to the new -one. +We use \PValue{float} as the owner so that all subsequent \KOMAScript{} +options that relate to lists of floating environments also apply to the new +content list. -Next\textnote{title} we define a title or heading for the list of -\Environment{remarkbox}es: +Next\textnote{title} we define a title or heading for this content list: \begin{lstcode} \newcommand*{\listoflorname}{List of Remarks} \end{lstcode} -You may use package \Package{scrbase} to additionally support titles in other -languages than English. - -Also\textnote{entry} a command is needed to define the layout of the entries -to the list of remarks: +When working with multiple languages, the normal practice is to define an +English title first and then, for example with the help of the +\Package{scrbase} package, to add titles for all the other languages you want +to support. See \autoref{sec:scrbase.languageSupport}, starting on +\autopageref{sec:scrbase.languageSupport}. + +Now\textnote{entry} all we have to do is define what a single entry in the +content list should look like: \begin{lstcode} \newcommand*{\l@remarkbox}{\l@figure} \end{lstcode} -Here simply the entries to the list of remarks get the same layout like the -entries to the list of figures. This would be the easiest solution. A more -explicit would be, e.\,g., +This specifies that entries in the list of remarks should look exactly like the +entries in the list of figures. This would be the easiest solution. A more +explicit definition would be something like: \begin{lstcode} \DeclareTOCStyleEntry[level=1,indent=1em,numwidth=1.5em]% {tocline}{remarkbox} \end{lstcode} -Additionally\textnote{chapter entry} you may want structure the list of -remarks depending on chapters. +You\textnote{chapter entry} also want chapter entries to affect the content +list. \begin{lstcode} \setuptoc{lor}{chapteratlist} \end{lstcode} -The \KOMAScript{} classes provide that feature and maybe other classes do so -too. Unfortunately the standard classes do not. - -This\textnote{list of remarks} would already be enough. Now, users may already -select different kinds of headings either using the corresponding options of -the \KOMAScript{} classes, or \DescRef{\LabelBase.cmd.setuptoc}, e.\,g., with -or without entry in the table of contents, with or without number. But a -simple +Setting this property allows this when you use a \KOMAScript{} class, and other class +that supports this property. Unfortunately, the standard classes do not. + +This\textnote{list of remarks} should be enough. Users can now +select different kinds of headings using the corresponding options of +the \KOMAScript{} classes or \DescRef{\LabelBase.cmd.setuptoc}, (e.\,g. with +or without an entry in the table of contents, with or without numbering). But +with a simple \begin{lstcode} \newcommand*{\listofremarkboxes}{\listoftoc{lor}} \end{lstcode} -may make the usage a little bit easier again. - -As you've seen only five commands refers to the list of remarks. Only three of -them are necessary. Nevertheless the new list of remarks already provides -optional numbering of the heading and optional not numbered entry into the -table of contents. Optional even a lower document structure level may be used -for the heading. Running headers are provides with the \KOMAScript{} classes, -the standard classes, and all classes that explicitly support -\Package{tocbasic}. Supporting classes even pay attention to this new list of -remarks at every new \DescRef{maincls.cmd.chapter}. Even changes of the -current language are handled inside the list of remarks like they will inside -the list of figures or inside the list of tables. - -Moreover,\textnote{additional features} an author of a package may add more -features. For example, options to hide \DescRef{\LabelBase.cmd.setuptoc} from -the users may be added. On the other hand, the \Package{tocbasic} manual may -be referenced to describe the corresponding features. The advantage of this -would be that user would get information about new features provides by -\Package{tocbasic}. But if the user should be able to set the features of the -remarks even without knowledge about the file name extension \File{lor} a -simple +you can simplify the usage even more. + +As you've seen, just five one-line commands, of which only three or four are +really necessary, refer to the content list. Nevertheless, the new list of +remarks already provides the ability to place both numbered and unnumbered +entries into the table of contents.You can use a lower sectioning level for +the headings. Running heads are set for the \KOMAScript{} classes, the +standard classes, and all classes that explicitly support \Package{tocbasic}. +Supporting classes even pay attention to this new list of remarks at each new +\DescRef{maincls.cmd.chapter}. Even changes to the current language made with +\Package{babel} are included in the list of remarks. + +Of course\textnote{additional features}, package authors can add more +features. For example, they could explicitly offer options to hide +\DescRef{\LabelBase.cmd.setuptoc} from users. Or they can refer to the +\Package{tocbasic} manual when explaining the appropriate features. The +advantage of this is that users automatically benefit from any future +extensions to \Package{tocbasic}. However, if you do not want to burden the +user with the fact that the file extension \File{lor} is used for the key +terms, then \begin{lstcode} \newcommand*{\setupremarkboxes}{\setuptoc{lor}} \end{lstcode} -would be enough to use a list of features argument to -\Macro{setupremarkboxes} as list of features of file name extension \File{lor}. +is sufficient to set a list of features passed as an argument to +\Macro{setupremarkboxes} as a list of features for the file extension +\File{lor}. -\section{Everything with One Command Only} -\label{sec:tocbasic.highlevel} +\section{Everything with Only One Command} +\label{sec:tocbasic.declarenewtoc} -The example from the previous section shows, that using \Package{tocbasic} to -define floating environments and lists with the captions of those floating -environments is easy. The following example will show, that it may be even -easier. +The example in the previous section has shows that \Package{tocbasic} makes it +easy to define your own floating environments with their own content lists. +This section shows how it can be even easier. \begin{Declaration} \Macro{DeclareNewTOC}\OParameter{options}\Parameter{extension} \end{Declaration} -This command declares\ChangedAt{v3.06}{\Package{tocbasic}} in one step only a -new TOC, the heading of that TOC, the term used for the TOC-entries, and to -manage the file name \PName{extension}. Additionally optional floating and -non-floating environments may be defined, and inside of both such environments -\DescRef{maincls.cmd.caption}% -\important{\DescRef{maincls.cmd.caption}}\IndexCmd{caption} may be used. The -additional features \DescRef{maincls.cmd.captionabove}\important[i]{% +This command declares\ChangedAt{v3.06}{\Package{tocbasic}} a new content list, +its heading, and the description of the entries controlled by +\Package{tocbasic} all in a single step. Optionally, you can also define +floating and non-floating environments at the same time. Inside of both such +environments, \DescRef{maincls.cmd.caption}% +\important{\DescRef{maincls.cmd.caption}}\IndexCmd{caption} creates entries +for this new content list. You can also use the \KOMAScript{} extensions +\DescRef{maincls.cmd.captionabove}\important[i]{% \DescRef{maincls.cmd.captionabove}\\ \DescRef{maincls.cmd.captionbelow}}, \DescRef{maincls.cmd.captionbelow}, and -\DescRef{maincls.env.captionbeside} of the \KOMAScript{} classes (see -\autoref{sec:maincls.floats}) may also be used inside of those environments. - -Argument \PName{extension} is the file name extension of the TOC-file, that -represents the list of something. See \autoref{sec:tocbasic.basics} for more -information about this. This argument is mandatory and must not be empty! - -Argument \PName{options} is a comma separated list, like you know it from, -e.\,g., \DescRef{maincls.cmd.KOMAoptions} (see -\autoref{sec:typearea.options}). Nevertheless\textnote{Attention!}, those -options cannot be set using -\DescRef{maincls.cmd.KOMAoptions}\IndexCmd{KOMAoptions}! An overview of all -available options may be found in +\DescRef{maincls.env.captionbeside} (see \autoref{sec:maincls.floats}). + +The \PName{extension} argument is the file extension of the TOC file that +represents the content list, as explained in \autoref{sec:tocbasic.basics}. +This argument is mandatory and must not be empty! + +The \PName{options} argument is a comma-separated list, of the same type as, +for example, \DescRef{maincls.cmd.KOMAoptions} (see +\autoref{sec:typearea.options}). However\textnote{Attention!}, those options +cannot be set using \DescRef{maincls.cmd.KOMAoptions}\IndexCmd{KOMAoptions}! +You can find an overview of all available options in \autoref{tab:tocbasic.DeclareNewTOC-options}. -If\ChangedAt[2015/12]{v3.20}{\Package{tocbasic}} option \Option{tocentrystyle} -is not used, style \PValue{default} will be used. For information about this -style see \autoref{sec:tocbasic.tocstyle}. If you do not want to define a -command for entries to the list of something, you can use an empty argument, -i.\,e., \OptionValue{tocentrystyle}{} or -\OptionValue{tocentrystyle}{\PParameter{}}. Nevertheless, this would contain -the risk to get a lot of errors while printing that list. +If\ChangedAt[2015/12]{v3.20}{\Package{tocbasic}} the \Option{tocentrystyle} +option is not used, the \PValue{default} style will be used if required. For +information about this style, see \autoref{sec:tocbasic.tocstyle}. If you do +not want to define a command for entries to the content list, you can use an +empty argument, i.\,e. \OptionValue{tocentrystyle}{} or +\OptionValue{tocentrystyle}{\PParameter{}}. Depending\ChangedAt[2015/12]{v3.20}{\Package{tocbasic}}% \ChangedAt[2016/06]{v3.21}{\Package{tocbasic}} on the style of the entries to -the list of something, you can setup all valid attributes of the selected -style as part of the \PName{options}. To do so you have to prefix the names of -the attributes given in \autoref{tab:tocbasic.tocstyle.attributes} from -\autopageref{tab:tocbasic.tocstyle.attributes} by prefix -\PValue{tocentry}. Later changes of the style of the entries can be made using +the content list, you can set all valid attributes of the selected style as +part of the \PName{options}. To do so, you must add the prefix +\PValue{tocentry} to the names of the attributes given in +\autoref{tab:tocbasic.tocstyle.attributes}, starting on +\autopageref{tab:tocbasic.tocstyle.attributes}. You can make later changes to +the style of the entries at any time using \DescRef{\LabelBase.cmd.DeclareTOCStyleEntry}% \IndexCmd{DeclareTOCStyleEntry}% \important{\DescRef{\LabelBase.cmd.DeclareTOCStyleEntry}}. See @@ -2079,112 +2140,141 @@ the styles.% \begin{desclist} \renewcommand*{\abovecaptionskipcorrection}{-\normalbaselineskip}% \desccaption[{Options for command \Macro{DeclareNewTOC}}]{% - Options for command - \Macro{DeclareNewTOC}\ChangedAt{v3.06}{\Package{tocbasic}}% + Options for the + \Macro{DeclareNewTOC}\ChangedAt{v3.06}{\Package{tocbasic}} command% \label{tab:tocbasic.DeclareNewTOC-options}% }{% - Options for command \Macro{DeclareNewTOC} (\emph{continuation})% + Options for the \Macro{DeclareNewTOC} command (\emph{continued})% }% - \entry{\OptionVName{atbegin}{instructions}% + \entry{\OptionVName{atbegin}{commands}% \ChangedAt{v3.09}{\Package{tocbasic}}}{% - The \PName{instructions} will be executed at the begin of the floating or + The \PName{commands} will be executed at the begin of the floating or non-floating environment.% }% - \entry{\OptionVName{atend}{instructions}% + \entry{\OptionVName{atend}{commands}% \ChangedAt{v3.09}{\Package{tocbasic}}}{% - The \PName{instructions} will be executed at the end of the floating or + The \PName{commands} will be executed at the end of the floating or non-floating environment.% }% \entry{\OptionVName{counterwithin}{\LaTeX{} counter}}{% - If you define a float or non-float, the captions will be numbered and a - counter \PName{type} (see option \Option{type}) will be defined. You may - declare another counter to be the parent \LaTeX{} counter. In this case, - the parent counter will be set before the float counter and the float - counter will be reset whenever the parent counter is increased using - \Macro{stepcounter} or \Macro{refstepcounter}.% + If you define a new floating or non-floating environment, a new counter + \Counter{\PName{type}} will be created as well (see option + \Option{type}). You can make this counter depenent another \LaTeX{} + counter in the same way, for example, that the \Counter{figure} counter in + the \Class{book} classes is dependent on the \Counter{chapter} counter.% }% \entry{\Option{float}}{% - If set, float environments for that type will be defined. The names of the - environments are the value of \PName{type} and for double column floats - the value of \PName{type} with addendum ``\PValue{*}''.% + If set, defines a new content list and a floating environment, both named + \PName{type}, and an environment for double-column floats named + \PName{type*}.% }% \entry{\OptionVName{floatpos}{float positions}}{% - The default floating position of the float. If no float position was - given, ``tbp'' will be used like the standard classes do for figures and - tables.% + Each floating environment has default \PName{float positions} that can be + changed through the optional argument of the floating environment. The + syntax and semantics are identical to those of the standard floating + environments. If the option is not used, the default \PName{float + positions} are ``\texttt{tbp}'', that is \emph{top}, \emph{bottom}, + \emph{page}.% }% \entry{\OptionVName{floattype}{number}}{% - The numerical float type of the defined floats. Float types with common - bits cannot be reordered. At the standard classes figures has float type 1 - and tables has float type 2. If no float type was given, 16 will be used.% + Each floating environment has a \PName{number}. Floating environments + where only different bits are set can be moved past each other. The + floating environments \Environment{figure} and \Environment{table} usually + have the types 1 and 2, so they can move past each other. The numerical + float type can be between 1 and 31. If common bits are set, the float + types cannot be reordred. If no float type is given, the greatest possible + one-bit type, 16, will be used.% }% \entry{\Option{forcenames}}{% - If set, the names will be even defined, if they where already defined + If set, the names will be defined even if they were already defined before.% }% \entry{\OptionVName{hang}{length}}{% \ChangedAt[2015/12]{v3.20}{\Package{tocbasic}}% \ChangedAt[2015/12]{v3.21}{\Package{tocbasic}}% - This option is deprecated since \KOMAScript~3.20. Now, the amount of the - hanging indent of the entries for that list\index{table of contents>entry} - depend on attributes of the TOC-entry style given by option - \Option{tocentrystyle}. The styles of \KOMAScript{} provide an attribute - \PValue{numwidth}. If the used style has such an attribute, - \Macro{DeclareNewTOC} will initialise it with 1.5\Unit{em}. You can change - the real \PName{value} using \OptionVName{tocentrynumwidth}{value}. The - \KOMAScript{} classes for example use - \OptionValue{tocentrynumwidth}{2.3em}.% + This option has been deprecated since \KOMAScript~3.20. Instead, the + amount of the hanging indent of entries to the content list\index{content + list>entry} depends on attributes of the TOC-entry style given by the + \Option{tocentrystyle} option. The \KOMAScript{} styles provide the + \PValue{numwidth} attribute. If the style used has such an attribute, + \Macro{DeclareNewTOC} will initialise it with a default of 1.5\Unit{em}. + You can easily change the \PName{value} using + \OptionVName{tocentrynumwidth}{value}. The \KOMAScript{} classes, for + example, use \OptionValue{tocentrynumwidth}{2.3em}.% }% \entry{\OptionVName{indent}{length}}{% \ChangedAt[2015/12]{v3.20}{\Package{tocbasic}}% \ChangedAt[2015/12]{v3.21}{\Package{tocbasic}}% - This option is deprecated since \KOMAScript~3.20. Now, the amount of - indenting the entries of that list\index{table of contents>entry} depend - on attributes of the TOC-entry style given by option - \Option{tocentrystyle}. The styles of \KOMAScript{} provide an attribute - \PValue{indent}. If the used style has such an attribute, - \Macro{DeclareNewTOC} will initialise it with 1\Unit{em}. You can change - the real \PName{value} using \OptionVName{tocentryindent}{value}. The - \KOMAScript{} classes for example use - \OptionValue{tocentrynumwidth}{1.5em}.% + This option has been deprecated since \KOMAScript~3.20. Instead, the + amount that entries to the content list\index{content list>entry} are + indented depends on attributes of the TOC-entry style given by the + \Option{tocentrystyle} option. The \KOMAScript{} styles provide the + \PValue{indent} attribute. If the style used has such an attribute, + \Macro{DeclareNewTOC} will initialise it with a default of 1\Unit{em}. You + can easily change the \PName{value} using + \OptionVName{tocentryindent}{value}. The \KOMAScript{} classes for example + use \OptionValue{tocentrynumwidth}{1.5em}.% }% \entry{\OptionVName{level}{number}}{% \ChangedAt[2015/12]{v3.20}{\Package{tocbasic}}% \ChangedAt[2015/12]{v3.21}{\Package{tocbasic}}% - This option is deprecated since \KOMAScript~3.20. Now, the level of the - entries of that list\index{table of contents>entry} depend on attributes - of the TOC-entry style given by option - \Option{tocentrystyle}. Nevertheless all styles have an attribute - \PValue{level} and \Macro{DeclareNewTOC} initialises it with 1. You can - change the real \PName{value} using \OptionVName{tocentrylevel}{value}.% + This option has been deprecated since \KOMAScript~3.20. Instead, the level + of the entries to the content list\index{content list>entry} depends on + attributes of the TOC-entry style given by the \Option{tocentrystyle} + option. Nevertheless, all styles have the \PValue{level} attrobite, and + \Macro{DeclareNewTOC} initialises it with a default value of 1. You can + easily change the \PName{value} using \OptionVName{tocentrylevel}{value}.% }% - \entry{\OptionVName{listname}{string}}{% - The name of the TOC. If not given the value of \PValue{types} with upper - case first char using \Macro{MakeUppercase}\IndexCmd{MakeUppercase} - prefixed by ``List of '' will be used.% + \entry{\OptionVName{listname}{title}}{% + Each content list has a heading, or title, that you can specify with this + option. If the option is not specified, the title will be ``List of + \PName{entry type}'' (see the \Option{types} option), with the first + character of the \PName{entry type} changed to upper case. It also defines + the \Macro{list\PName{entry type}name} macro with this value, which you + can change at any time. This macro, however, is only defined if it is not + already defined or if the \Option{forcenames} option is also set.% }% - \entry{\OptionVName{name}{string}}{% - The name of an element. If no name is given, the value of \PValue{type} - with upper case first char will be used.% + \entry{\OptionVName{name}{entry name}}{% + Both the optional prefix for entries in the content list and the labels in + floating or non-floating environments (see the \Option{float} and + \Option{nonfloat} options) require an \PName{entry name} for an entry to + the content list. If no \PName{entry name} is given, the value of the + \PValue{type} (see the \Option{type} option) with the first character + changed to upper case will be used. It also defines a \Macro{\PName{entry + type}name} macro with this value, which you can change at any time. This + macro, however, is only defined if it is not already defined or if the + \Option{forcenames} option is also set.% }% \entry{\Option{nonfloat}}{% - If set, a non floating environment will be defined. The name of the - environment is the value of \PName{type} with attached ``\PValue{-}''.% + If set, defines not only a content list but also a non-floating environment, + \Environment{\PName{entry type}-} (see the \Option{type} option), which can + be used similarly to a floating environment, but which does not move from + the place where it is used.% }% \entry{\OptionVName{owner}{string}}{% - The owner as described in the sections before. If no owner was given owner - \PValue{float} will be used.% + Every new content list has an owner in \Package{tocbasic} (see + \autoref{sec:tocbasic.basics}). You can specify this here. If no owner is + specified, the owner ``\PValue{float}'' is used. The \KOMAScript{} classes + use this owner for the list of figures and the list of tables.% + }% + \entry{\OptionVName{setup}{list of attributes}}{% + \ChangedAt{v3.25}{\Package{tocbasic}}% + The \PName{list of attributes} is set with + \DescRef{\LabelBase.cmd.setuptoc}. Note that to specify multiple + attributes in a comma-separated list, you must put this list between + braces.% }% \entry{\OptionVName{tocentrystyle}{TOC-entry style}}{% - \ChangedAt[2015/12]{v3.20}{\Package{tocbasic}}% - \PName{TOC-entry style} is the style that should be used for all entries - into the TOC corresponding to the \PName{extension}. The name of the entry - level is given by option \Option{type}. Additional to the options of this - table all attributes of the \PName{TOC-entry style} can be used as - options. To do so, you have to prefix the name of such an attribute by - \PValue{toc}. For example, you can change the numerical level of the - entries using option \Option{tocentrylevel}. For more information about - the styles and their attributes see \autoref{sec:tocbasic.tocstyle} from + \ChangedAt{v3.20}{\Package{tocbasic}}% + \PName{TOC-entry style} specifies the style that should be used for all + entries to the content list corresponding to the \PName{extension}. The + name of the entry level is given by the \Option{type} option. In addition + to the options in this table, all attributes of the \PName{TOC-entry + style} can be used as options. To do so, you have to prefix the name of + such an attribute with \PValue{toc}. For example, you can change the + numerical level of the entries using the \Option{tocentrylevel} option. + For more information about the styles and their attributes see + \autoref{sec:tocbasic.tocstyle}, starting on \autopageref{sec:tocbasic.tocstyle}.% }% \entry{\OptionVName{tocentry\PName{style-option}}{value}}{% @@ -2195,22 +2285,31 @@ the styles.% TOC-entry styles. See \autoref{tab:tocbasic.tocstyle.attributes}, \autopageref{tab:tocbasic.tocstyle.attributes} for information about the attributes of the predefined TOC-entry styles of package - \Package{tocbasic}, that can be used as \PName{style-option}.% + \Package{tocbasic} that can be used as \PName{style-option}.% }% - \entry{\OptionVName{type}{string}}{% - sets the type of the new declared TOC. The type will be used e.\,g. to - defined a \Macro{listof}\PName{string}. If no type is set up the extension - from the mandatory argument will be used.% + \entry{\OptionVName{type}{entry type}}{% + Sets the type of the newly declared content list. The \PName{entry type} + is also used as a base name for various macros and possibly environments + and counters. It should therefore consist only of letters. If this option + is not used, the file \PName{extension} from the mandatory argument will + be used as the \PName{entry type}.% }% \entry{\OptionVName{types}{string}}{% - the plural of the type. If no plural was given the value of \PValue{type} - with attached ``s'' will be used.% + In several places, the plural form of the \PName{entry type} is required. + If no plural is given, the value of the \PValue{entry type} with an ``s'' + appended will be used.% + }% + \entry{\OptionVName{unset}{list of attributes}}{% + \ChangedAt{v3.25}{\Package{tocbasic}}% + The \PName{list of attributes} is unset with + \DescRef{\LabelBase.cmd.unsettoc}. Note that to specify a comma-separated + list of attributes, you must put this list between braces.% }% \end{desclist} \begin{Example} - Using \Macro{DeclareNewTOC} reduces the example from - \autoref{sec:tocbasic.example} to: + Using \Macro{DeclareNewTOC} significantly shortens the example from + \autoref{sec:tocbasic.example}: \begin{lstcode} \DeclareNewTOC[% type=remarkbox,% @@ -2222,25 +2321,24 @@ the styles.% ]{lor} \setuptoc{lor}{chapteratlist} \end{lstcode} - Beside environments \Environment{remarkbox} and \Environment{remarkbox*} the - counter \Counter{remarkbox}, the commands \Macro{theremarkbox}, + In addition to the \Environment{remarkbox} and \Environment{remarkbox*} environments, + this also defines the \Counter{remarkbox} counter; the commands \Macro{theremarkbox}, \Macro{remarkboxname}, and \Macro{remarkboxformat} that are used for captions; the commands \Macro{listremarkboxnames} and - \Macro{listofremarkboxes} that are used at the list of remarks; and some - internal commands that depends on the file name extension \File{lor} are - defined. If the package should use a default for the floating type, option - Option{floattype} may be omitted. If option \Option{nonfloat} will be used - additionally, then a non-floating environment \Environment{remarkbox-} will - be also defined. You may use \DescRef{maincls.cmd.caption}\IndexCmd{caption} inside of - that non-floating environment as usual for floating environments. + \Macro{listofremarkboxes} that are used in the list of remarks; and some + internal commands that depend on the file name extension \File{lor}. + If the package should use a default for the floating type, the + Option{floattype} option can be omitted. If the \Option{nonfloat} option is specified, + a non-floating environment, \Environment{remarkbox-}, will + also be defined, inside which you can use \DescRef{maincls.cmd.caption}\IndexCmd{caption}. \hyperref[tab:tocbasic.comparison]{Figure~\ref*{tab:tocbasic.comparison}} - shows a comparison of the commands, counters and environments of the - example environment \Environment{remarkbox} and of the commands, counters - and environments for figures.% + compares the commands, counters, and environments of the + example \Environment{remarkbox} environment to the commands, counters, + and environments of figures.% \begin{table} \centering - \caption{Comparison of example environment \Environment{remarkbox} - and environment \Environment{figure}} + \caption{Comparing the example \Environment{remarkbox} environment + with the \Environment{figure} environment} \label{tab:tocbasic.comparison} \begin{tabularx}{\textwidth}{ll>{\raggedright}p{6em}X} \toprule @@ -2277,42 +2375,41 @@ the styles.% & numeric float type for order perpetuation\\[1ex] \File{lor} & \File{lof} & - & file name extension of the TOC-file of the respective list \\ + & file name extension of the TOC file of the respective list \\ \bottomrule \end{tabularx} \end{table} - And now a possible usage of the example environment: + And here is a possible use of the example environment: \begin{lstcode} \begin{remarkbox} \centering - Equal should be typeset equally - and with equal formatting. - \caption{First theorem of typography} + The same thing should always be typeset in the same way + and with the same appearance. + \caption{First Law of Typography} \label{rem:typo1} \end{remarkbox} \end{lstcode} - A segment of an example page with this environment could be: + A snippet of a sample page with this environment might look like this: \begin{center}\footnotesize \begin{tabular} {|!{\hspace{.1\linewidth}}p{.55\linewidth}!{\hspace{.1\linewidth}}|} \\ \centering - Equal should be typeset equally - and with equal formatting.\\[\abovecaptionskip] + The same thing should always be typeset in the same way + and with the same appearance.\\[\abovecaptionskip] {% \usekomafont{caption}\footnotesize{\usekomafont{captionlabel}% - Remark 1: }First theorem of typography + Remark 1: }First Law of Typography }\\ \end{tabular}% \end{center}% \end{Example} -Users of \Package{hyperref} should always use option -\Option{listname}. Otherwise they may get an error message, because -\Package{hyperref} usually has a problem with the -\Macro{MakeUppercase}\IndexCmd{MakeUppercase} command that is used to change -the case of the first letter of \Option{types} in the name of the list.% +Users of \Package{hyperref} should always use the \Option{listname} option. +Otherwise they may get an error message because \Package{hyperref} usually has +a problem with the \Macro{MakeUppercase}\IndexCmd{MakeUppercase} command that +is needed to convert the first letter of \Option{types} to upper case.% \EndIndexGroup % \EndIndexGroup |