diff options
Diffstat (limited to 'macros/latex/contrib/koma-script/doc/tocbasic-en.tex')
-rw-r--r-- | macros/latex/contrib/koma-script/doc/tocbasic-en.tex | 2612 |
1 files changed, 2612 insertions, 0 deletions
diff --git a/macros/latex/contrib/koma-script/doc/tocbasic-en.tex b/macros/latex/contrib/koma-script/doc/tocbasic-en.tex new file mode 100644 index 0000000000..fe5be7f4a6 --- /dev/null +++ b/macros/latex/contrib/koma-script/doc/tocbasic-en.tex @@ -0,0 +1,2612 @@ +% ====================================================================== +% tocbasic-en.tex +% Copyright (c) Markus Kohm, 2002-2022 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in MANIFEST.md. +% ====================================================================== +% +% Package tocbasic for Package and Class Authors +% Maintained by Markus Kohm +% +% ====================================================================== + +\KOMAProvidesFile{tocbasic-en.tex} + [$Date: 2022-06-05 12:40:11 +0200 (So, 05. Jun 2022) $ + KOMA-Script guide (package tocbasic)] + +\translator{Markus Kohm\and Arndt Schubert\and Karl Hagen} + +\chapter{Managing Content Lists with \Package{tocbasic}} +\labelbase{tocbasic} +\BeginIndexGroup% +\BeginIndex{Package}{tocbasic}% +\BeginIndex{}{table of contents}% +\BeginIndex{}{content list}% +\BeginIndex{}{file>extension}% +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. + +\section{Basic Commands} +\label{sec:tocbasic.basics} + +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}, + \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 of a category that the author of +the class or package using \Package{tocbasic} has chosen independently. For +example, \KOMAScript{} uses the category \texttt{float} as owner 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{then code}% + \Parameter{else code} +\end{Declaration} +This\ChangedAt{v3.28}{\Package{tocbasic}} 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} + 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}{% + extension `foo' already in use% + }{% + Each extension may be used only + once.\MessageBreak + The class or another package already + uses extension `foo'.\MessageBreak + This error is fatal!\MessageBreak + You should not continue!}% + }{% + \PackageInfo{bar}{using extension `foo'}% + } +\end{lstcode} +\end{Example} +\EndIndexGroup + + +\begin{Declaration} + \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 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 empty. + +Note\textnote{Attention!} that passing an empty \PName{owner} argument is not +always the same as completely omitting the optional argument, including the +square brackets. An empty argument would always result in an empty owner. +\begin{Example} + 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 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} + 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. + This may be either an incompatibility of packages, an error at a package, + or a mistake by the user. +\end{lstoutput} + + 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 content list available + } +\end{lstcode} + Now if the user calls this command, for example with +\begin{lstcode} + \createnewlistofsomething{foo} +\end{lstcode} + 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 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 the category ``\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 \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{commands} +\end{Declaration} +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} + \AtAddToTocList[]{% + \expandafter\tocbasic@extend@babel + \expandafter{\@currext}% + } +\end{lstcode} + to add every file extension to the existing \Package{tocbasic} integration + with the \Package{babel} package. +\end{Example} + +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 + + +\begin{Declaration} + \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}, is given, the \PName{extension} +will only be removed if it was added by this \PName{owner}. +% TODO: Fix new translation +This also applies to the empty \PName{owner}. If, on the other hand, no +\OParameter{owner} is specified at all and the square brackets are also +omitted, the owner is not tested and the \PName{extension} is removed +regardless of the owner.% +% :ODOT +\EndIndexGroup + + +\begin{Declaration} + \Macro{doforeachtocfile}\OParameter{owner}\Parameter{commands} +\end{Declaration} +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 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} + 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} 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}. + +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 Content List} +\label{sec:tocbasic.toc} + +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} +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 file currently being processed. +\begin{Example} + You want to add a vertical space of one line to all TOC files. +\begin{lstcode} + \addtoeachtocfile{% + \protect\addvspace{\protect\baselineskip}% + } +\end{lstcode} + 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} +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{section number}% + \Parameter{text} +\end{Declaration} +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.toc}, +\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}. + +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{addxcontentslinetoeachtocfile}\OParameter{owner} + \Parameter{level} + \OParameter{section number}% + \Parameter{text} + \Macro{addcontentslinetoeachtocfile}\OParameter{owner} + \Parameter{level}\Parameter{text}% +\end{Declaration} +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} + 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} +\end{lstcode} + 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 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*}\Parameter{extension}% + \Macro{listofeachtoc}\OParameter{owner}% + \Macro{listof\PName{extension}name} +\end{Declaration} +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 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} + 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. If, however, you want to output this list without a + title, you could use +\begin{lstcode} + \listof*{loa} +\end{lstcode} + 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} + already, then +\begin{lstcode} + \listoftoc{loa} +\end{lstcode} + 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} +\end{Example} + +Because\textnote{Attention!} \LaTeX{} normally opens a new file for each of +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 the +\Package{scrwfile}\important{\Package{scrwfile}}\IndexPackage{scrwfile} +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{commands}% + \Macro{AfterStartingTOC}\OParameter{extension}\Parameter{commands} +\end{Declaration} +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 which is about to be or has just been read. + +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{commands}% + \Macro{AfterTOCHead}\OParameter{extension}\Parameter{commands} +\end{Declaration} +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 + + +\begin{Declaration} + \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}. 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 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} +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{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. + +Obviously, the \PName{definition} is also responsible for the interpretation +of additional features related to the title. This is especially true +for the features \PValue{leveldown}, \PValue{numbered} and \PValue{totoc}, +that are be explained next.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{setuptoc}\Parameter{extension}\Parameter{feature list}% + \Macro{unsettoc}\Parameter{extension}\Parameter{feature list} +\end{Declaration} +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[\PValue{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 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~=\textKValue{leveldown}} option for all file extensions + with the owner \PValue{float}. +\item[\PValue{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[\PValue{noindent}]\ChangedAt{v3.27}{\Package{tocbasic}}% + causes all content-list entry styles provided by \KOMAScript{} to ignore + the \PValue{indent} attribute (see + \autoref{tab:tocbasic.tocstyle.attributes}, + \autopageref{tab:tocbasic.tocstyle.attributes.indent}) and instead to + deactivate the indentation.% +\item[\PValue{noparskipfake}] prevents\ChangedAt{v3.17}{\Package{tocbasic}} + 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[\PValue{noprotrusion}] prevents\ChangedAt{v3.10}{\Package{tocbasic}} + 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[\PValue{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~=\textKValue{numbered}} option for all file extensions + with the owner \PValue{float}. +\item[\PValue{numberline}] \leavevmode\ChangedAt{v3.12}{\Package{tocbasic}}% + 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~=\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~=\textKValue{numberline}} option. Similarly, this feature + is reset if you use \OptionValueRef{maincls}{listof}{nonumberline}% + \important{\OptionValueRef{maincls}{listof}{nonumberline}}% + \IndexOption{listof~=\textKValue{nonumberline}} or + \OptionValueRef{maincls}{toc}{nonumberline}% + \important{\OptionValueRef{maincls}{toc}{nonumberline}}% + \IndexOption{toc~=\textKValue{nonumberline}}. +\item[\PValue{onecolumn}] \leavevmode\ChangedAt{v3.01}{\Package{tocbasic}}% + 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 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[\PValue{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~=\textKValue{totoc}} option for all file extensions with + the owner \PValue{float}. +\end{description} +The \KOMAScript{} classes recognize an additional feature: +\begin{description} +\item[\PValue{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 this option. +\end{description} +\begin{Example} + Because \KOMAScript{} classes use \Package{tocbasic} for the list of figures + 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} + + 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 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} + Using \DescRef{scrbase.cmd.Ifundefinedorrelax} requires the + \Package{scrbase} package (see \autoref{sec:scrbase.if}, + \DescPageRef{scrbase.cmd.Ifundefinedorrelax}). + + 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 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{then code}\Parameter{else code} +\end{Declaration} +You\ChangedAt{v3.28}{\Package{tocbasic}} 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{Configuring Content-List Entries} +\seclabel{tocstyle}% +\BeginIndexGroup +\BeginIndex{}{table of contents>entry}% +\Index{list of contents|\see{table of contents}} + +Since\ChangedAt{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 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 + + +\begin{Declaration} + \Macro{numberline}\Parameter{entry number}% + \Macro{usetocbasicnumberline}\OParameter{code} +\end{Declaration} +Although\ChangedAt{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 +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. + +Note\textnote{Attention!} that \Macro{usetocbasicnumberline} can change the +internal switch \Macro{@tempswa} globally!% +\EndIndexGroup + + +\begin{Declaration} + \Macro{DeclareTOCStyleEntry}\OParameter{option list}\Parameter{style}% + \Parameter{entry level} + \Macro{DeclareTOCStyleEntries}\OParameter{option list}\Parameter{style}% + \Parameter{entry level list} +\end{Declaration} +These\ChangedAt{v3.20}{\Package{tocbasic}} commands define or configure 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} or +\Macro{DeclareTOCStyleEntries}. 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 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 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 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}. 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} + \centering + \resizebox{.8\linewidth}{!}{% + \begin{tikzpicture} + \draw[color=lightgray] (0,2\baselineskip) -- (0,-2.5\baselineskip); + \draw[color=lightgray] (\linewidth,2\baselineskip) -- + (\linewidth,-2.5\baselineskip); + \node (dottedtocline) at (0,0) [anchor=west,inner sep=0,outer sep=0] + {% + \hspace*{7em}% + \parbox[t]{\dimexpr\linewidth-9.55em}{% + \setlength{\parindent}{-3.2em}% + \addtolength{\parfillskip}{-2.55em}% + \makebox[3.2em][l]{1.1.10}% + 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}% + }% + }; + \draw[|-|,color=gray,overlay] (0,0) -- + node [anchor=north,font=\small] { + \PValue{indent} + } + (3.8em,0); + \draw[|-|,color=gray,overlay] (3.8em,\baselineskip) -- + node [anchor=south,font=\small] { + \PValue{numwidth} + } + (7em,\baselineskip); + \draw[|-|,color=gray,overlay] (\linewidth,\ht\strutbox) -- + node [anchor=south,font=\small] { + \Macro{@tocrmarg} + } + (\linewidth-2.55em,\ht\strutbox); + \draw[|-|,color=gray,overlay] (\linewidth,-\baselineskip) -- + node [anchor=north,font=\small] { + \Macro{@pnumwidth} + } + (\linewidth-1.55em,-\baselineskip); + \end{tikzpicture}% + } + \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 simplest possible style. Entries in this style, + regardless of the setting of \DescRef{\LabelBase.counter.tocdepth}% + \IndexCounter{tocdepth}\important{\DescRef{\LabelBase.counter.tocdepth}}, + 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 \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 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}{!}{% + \begin{tikzpicture} + \draw[color=lightgray] (0,2\baselineskip) -- (0,-2.5\baselineskip); + \draw[color=lightgray] (\linewidth,2\baselineskip) -- + (\linewidth,-2.5\baselineskip); + \node (largetocline) at (0,0) [anchor=west,inner sep=0,outer sep=0] {% + \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 the + \PValue{largetocline} style and more than one line% + \hfill + \makebox[0pt][l]{\normalsize\normalfont + \makebox[1.55em][r]{\large\bfseries 1}}% + }% + }; + \draw[|-|,color=gray] (0,\baselineskip) -- + node [anchor=south] { 3\,em } + (3em,\baselineskip); + \draw[|-|,color=gray,overlay] (\linewidth,\ht\strutbox) -- + node [anchor=south] { \Macro{@pnumwidth} } + (\linewidth-1.55em,\ht\strutbox); + \large\bfseries + \draw[|-|,color=gray,overlay] (\linewidth,-\baselineskip) -- + node [anchor=north,font=\normalfont\normalsize] { + \Macro{large}\Macro{@pnumwidth} + } + (\linewidth-1.55em,-\baselineskip); + \end{tikzpicture}% + } + \caption{Illustrations of some attributes of a TOC entry with style + \PValue{largetocline}} + \label{fig:tocbasic.largetocline} + \end{figure} +\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 20\important{\PValue{level}, \PValue{beforeskip}, + \PValue{breakafternumber}, \PValue{dynindent}, \PValue{dynnumwidth}, + \PValue{entryformat}, \PValue{entrynumberformat}, \PValue{indent}, + \PValue{indentfollows}, \PValue{linefill}, \PValue{numsep}, + \PValue{numwidth}, \PValue{onstarthigherlevel}, + \PValue{onstartlowerlevel}, \PValue{onstartsamelevel}, + \PValue{pagenumberbox}, \PValue{pagenumberformat}, + \PValue{pagenumberwidth}, \PValue{raggedentrytext}, + \PValue{raggedpagenumber}, \PValue{rightindent}} 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 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. The others are explained in + \autoref{tab:tocbasic.tocstyle.attributes} starting on + \autopageref{tab:tocbasic.tocstyle.attributes}. + \begin{figure} + \centering + \resizebox{.8\linewidth}{!}{% + \begin{tikzpicture} + \coordinate (subsection) at (0,0); + \coordinate (section) at ($(subsection)+(0,2\baselineskip)$); + \coordinate (chapter) at ($(section)+(0,2\baselineskip)$); + \coordinate (part) at ($(chapter)+(0,2.4\baselineskip+1em)$); + + \draw[color=lightgray] + ($(part)+(0,2\baselineskip)$) -- + (0,-2.5\baselineskip); + \draw[color=lightgray] + ($(part)+(\linewidth,2\baselineskip)$) -- + (\linewidth,-2.5\baselineskip); + + \coordinate (subsection) at (0,0); + + \node at (part) [anchor=west,inner sep=0,outer sep=0] + {% + \hspace*{3em}% + \parbox[t]{\dimexpr\linewidth-5.55em}{% + \setlength{\parindent}{-3em}% + \addtolength{\parfillskip}{-2.55em}% + \makebox[3em][l]{\large\bfseries I.}% + \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 + }% + }; + \draw[|-|,color=gray,overlay] + (part) -- + ($(part)+(3em,0)$) + node [anchor=north east,font=\small] { + \PValue{numwidth} + }; + \draw[|-|,color=gray,overlay] + ($(part)+(\linewidth,\ht\strutbox)$) + node [anchor=north,font=\small] { + \Macro{@tocrmarg} + } -- + ($(part)+(\linewidth-2.55em,\ht\strutbox)$); + \draw[|-|,color=gray,overlay] + ($(part)+(\linewidth,-\baselineskip)$) -- + node [anchor=north,font=\small] { + \Macro{@pnumwidth} + } + ($(part)+(\linewidth-1.55em,-\baselineskip)$); + \node at (chapter) [anchor=west,inner sep=0,outer sep=0] + {% + \hspace*{1.5em}% + \parbox[t]{\dimexpr\linewidth-4.05em}{% + \setlength{\parindent}{-1.5em}% + \addtolength{\parfillskip}{-2.55em}% + \makebox[1.5em][l]{\bfseries 1.}% + \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}% + }% + }; + \draw[|-|,color=gray,overlay] + ($(chapter)+(3em,\baselineskip)$) -- + node [anchor=west,font=\small] { + \PValue{beforeskip} + } + ($(part)+(3em,-\baselineskip)$); + \draw[|-|,color=gray,overlay] + (chapter) -- + ($(chapter)+(1.5em,0)$) + node [anchor=north east,font=\small] { + \PValue{numwidth} + }; + \draw[|-|,color=gray,overlay] + ($(chapter)+(\linewidth,\ht\strutbox)$) + node [anchor=north,font=\small] { + \Macro{@tocrmarg} + } -- + ($(chapter)+(\linewidth-2.55em,\ht\strutbox)$); + \draw[|-|,color=gray,overlay] + ($(chapter)+(\linewidth,-\baselineskip)$) + node [anchor=north,font=\small] { + \Macro{@pnumwidth} + } -- + ($(chapter)+(\linewidth-1.55em,-\baselineskip)$); + \node at (section) [anchor=west,inner sep=0,outer sep=0] + { + \hspace*{3.8em}% + \parbox[t]{\dimexpr\linewidth-6.35em}{% + \setlength{\parindent}{-2.3em}% + \addtolength{\parfillskip}{-2.55em}% + \makebox[2.3em][l]{1.1.}% + 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}% + }% + }; + \node at (subsection) [anchor=west,inner sep=0,outer sep=0] + {% + \hspace*{7em}% + \parbox[t]{\dimexpr\linewidth-9.55em}{% + \setlength{\parindent}{-3.2em}% + \addtolength{\parfillskip}{-2.55em}% + \makebox[3.2em][l]{1.1.10.}% + 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}% + }% + }; + \draw[|-|,color=gray,overlay] + ($(subsection)+(0,\ht\strutbox)$) -- + node [anchor=north,font=\small] { + \PValue{indent} + } + ($(subsection)+(3.8em,\ht\strutbox)$); + \draw[|-|,color=gray,overlay] + ($(subsection)+(3.8em,0)$) -- + ($(subsection)+(7em,0)$) + node [anchor=north east,font=\small] { + \PValue{numwidth} + }; + \draw[|-|,color=gray,overlay] + ($(subsection)+(\linewidth,\ht\strutbox)$) + node [anchor=north,font=\small] { + \Macro{@tocrmarg} + } -- + ($(subsection)+(\linewidth-2.55em,\ht\strutbox)$); + \draw[|-|,color=gray,overlay] + ($(subsection)+(\linewidth,-\baselineskip)$) -- + node [anchor=north,font=\small] { + \Macro{@pnumwidth} + } + ($(subsection)+(\linewidth-1.55em,-\baselineskip)$); + \end{tikzpicture}% + } + \caption{Illustrations of some attributes of a TOC entry with the + \PValue{tocline} style} + \label{fig:tocbasic.tocline} + \end{figure} +\item[\PValue{toctext}]\ChangedAt{v3.27}{\Package{tocbasic}}% + is a special feature. While all other styles produce one paragraph per + entry, this one produces one paragraph for all successive entries of this + style. With 14\important{\PValue{afterpar}, \PValue{beforeskip}, + \PValue{entryformat}, + \PValue{entrynumberformat}, \PValue{indent}, \PValue{numsep}, + \PValue{onendentry}, \PValue{onendlastentry}, \PValue{onstartentry}, + \PValue{onstartfirstentry}, \PValue{pagenumberformat}, + \PValue{prepagenumber}, \PValue{raggedright}, \PValue{rightindent}} + attributes in addition to the default \PValue{level} attribute, there are + almost as many options as for \PValue{tocline}. However, this style + depends on the fact that an unfinished paragraph will be concluded at the + beginning of the entry for all other styles, as well as at the end of the + current content list. So it should never be combined with entries or content + lists that are generated outside of \Package{tocbasic}. +\item[\PValue{undottedtocline}] is similar to the style used by the standard + \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} + \centering + \resizebox{.8\linewidth}{!}{% + \begin{tikzpicture} + \draw[color=lightgray] (0,2\baselineskip) -- (0,-2.5\baselineskip); + \draw[color=lightgray] (\linewidth,2\baselineskip) -- + (\linewidth,-2.5\baselineskip); + \node (undottedtocline) at (0,0) [anchor=west,inner sep=0,outer sep=0] + {% + \makebox[1.5em][l]{\bfseries 1}% + \parbox[t]{\dimexpr \linewidth-4.05em\relax}{% + \bfseries + 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}}% + }; + \draw[|-|,color=gray,overlay] (0,\baselineskip) -- + node [anchor=south,font=\small] { + \PValue{numwidth} + } + (1.5em,\baselineskip); + \draw[|-|,color=gray,overlay] (\linewidth,\ht\strutbox) -- + node [anchor=south,font=\small] { + \Macro{@tocrmarg} + } + (\linewidth-2.55em,\ht\strutbox); + \draw[|-|,color=gray,overlay] (\linewidth,-\baselineskip) -- + node [anchor=north,font=\small] { + \Macro{@pnumwidth} + } + (\linewidth-1.55em,-\baselineskip); + \end{tikzpicture}% + } + \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} +You can find an explanation of the attributes of all styles that +\Package{tocbasic} defines in \autoref{tab:tocbasic.tocstyle.attributes}. +In\ChangedAt{v3.27}{\Package{tocbasic}} addition to the usual assignment with +\Option{\PName{key}=\PName{value}}, both commands understand an assignment in +the form \Option{\PName{key}:=\PName{entry level}} for all options of the +\KOMAScript{} styles. In this case, the current setting of \PName{key} for the +\PName{entry level} will be copied. For example, you can copy the current +indent of the \PValue{figure} level using \OptionValue{indent:}{figure}. For +options that expect a length or integer value, you can also use +\Option{\PName{key}+=\PName{value}} to add \PName{value} to the current setting +of the \PName{key}. To subtract simply, you can use a negative \PName{value}. +For example, with \OptionValue{indent+}{1cm} you can increase the indent by +1\Unit{cm}. For options that expect a list value, you can use +\Option{\PName{key}+=\PName{value}} to append \PName{value} to the current +setting of the \PName{key}. + +If\ChangedAt{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 +attributes with \PValue{tocentry}, e\,g., \PValue{level} becomes +\Option{tocentrylevel}. The copy operation with \Option{:=} described above is +also available here. However, addition with \Option{+=} is not currently +supported. + +If\ChangedAt{v3.20}{\Package{tocbasic}} you 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}. +At this time, neither the copy operation with \Option{:=} nor the +addition operation with \Option{+=} is supported. + +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{continued})% + }% + \entry{\OptionVName{afterpar}{code}}{% + \ChangedAt{v3.27}{\Package{tocbasic}}% + The specified \PName{code} will be executed after the end of the paragraph + in which an entry with the \PValue{toctext} style is printed. If several + entries have such settings, their code will be executed in the order of + the entries.% + }% + \entry{\OptionVName{beforeskip}{length}}{% + 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}.% + + In\ChangedAt{v3.31}{\Package{tocbasic}} the style \PValue{toctext} the + vertical space is inserted before the paragraph if it is the first entry + in the paragraph. It is ignored for all other entries in the paragraph. If + the initialization takes place via this style, \texttt{0pt} is used as + default.% + }% + \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 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 flush left with the number. The default is + false for the \PValue{tocline} style. + + 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~=\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{dynindent}{switch}}{% + \ChangedAt{v3.31}{\Package{tocbasic}}% + \PName{switch} is one of the values for simple switches from + \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. If the + switch is active with the \PValue{tocline} style, the \PValue{indent} + attribute only specifies a minimum value. The maximum value is determined + by the number width and the indentation of the levels specified via + \PValue{indentfollows}.% + }% + \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 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}}{% + 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}}{% + 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}. + + The initial \PName{command} prints the argument unchanged. This means the + entry number will be printed as it is. + + 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~=\textKValue{numberline}} option, the unnumbered entries + will execute the \PName{command} as well.% + }% + \entry{% + \OptionVName{indent}{length}% + {\phantomsection\label{tab:tocbasic.tocstyle.attributes.indent}}% + }{% + For\ChangedAt{v3.27}{\Package{tocbasic}} the \PValue{toctext} style, the + \PName{length} is the horizontal distance of the paragraph from the left + margin. If different entries within the paragraph have different settings, + the last one is used. For the remaining styles, the \PName{length} is the + horizontal distance of the entry from the left margin (see + \autoref{fig:tocbasic.dottedtocline} and \autoref{fig:tocbasic.tocline}). + + For the styles \PValue{tocline} and \PValue{toctext}, 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. + + If the \PValue{noindent} attribute is set for a content list via + \DescRef{\LabelBase.cmd.setuptoc}, the entries of all styles provided by + \KOMAScript{} enforce the value 0\Unit{pt} to deactivate the indent.% + }% + \entry{\OptionVName{level}{integer}}{% + 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} + counter are printed. + + This attribute is mandatory for all styles and will be defined + automatically when the style is declared. + + For the \PValue{tocline} and \PValue{toctext} styles, 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}, + \PValue{toctext}, 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.% + }% + \entry{\OptionVName{indentfollows}{list of levels}}{% + \ChangedAt{v3.31}{\Package{tocbasic}}% + If \Option{dynindent} is set with style \PValue{tocline}, the + comma-separated list of level names specified here is used to determine + the actual indentation. Levels whose names begin with ``\texttt{sub}'' + will be initialized with the name without this prefix. The \KOMAScript{} + classes also automatically set appropriate values for the levels + \PValue{section} and \PValue{paragraph}.% + }% + \entry{\OptionVName{linefill}{code}}{% + 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}). + + 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}}{% + 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 not + met. + + The\ChangedAt{v3.27}{\Package{tocbasic}} \PValue{toctext} style, on the + other hand, always adds a horizontal space of width \PName{length} after + the number of the entry. + + The initial \PName{length} is 0.4\Unit{em}.% + }% + \entry{\OptionVName{numwidth}{length}}{% + 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{onendentry}{code}}{% + \ChangedAt{v3.27}{\Package{tocbasic}}% + The \PName{code} is executed immediately after an entry with the + \PValue{toctext} style, if this entry is not the last one of the + paragraph. The user must ensure that the \PName{code} does not result in + the paragraph ending. + + Note: In reality the \PName{code} is not executed at the end of the entry + but before the next entry with style \PValue{toctext}.% + }% + \entry{\OptionVName{onendlastentry}{code}}{% + \ChangedAt{v3.27}{\Package{tocbasic}}% + The \PName{code} is executed immediately before the end of the paragraph + with an entry in the \PValue{toctext} style, as long as this entry is the + last one in the paragraph. The user must ensure that the \PName{code} does + not result in the paragraph ending.% + }% + \entry{\OptionVName{onstartentry}{code}}{% + \ChangedAt{v3.27}{\Package{tocbasic}}% + The \PName{code} is executed immediately before an entry with the + \PValue{toctext} style, unless it is the first one in the paragraph. The + user must ensure that the \PName{code} does not result in the paragraph + ending.% + }% + \entry{\OptionVName{onstartfirstentry}{code}}{% + \ChangedAt{v3.27}{\Package{tocbasic}}% + The \PName{code} is executed immediately before an entry with the + \PValue{toctext} style if this entry is the first one of the paragraph. The + user must ensure that the \PName{code} does not result in the paragraph + ending.% + }% + \entry{\OptionVName{onstarthigherlevel}{code}}{% + 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. + + 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}}{% + 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}}{% + 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 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}}{% + 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} and of entry level + \PValue{chapter} in \Macro{bfseries}. For classes without + \Macro{l@chapter} \PValue{section} also uses \Macro{bfseries}. The initial + \PName{command} of all other levels prints the argument in + \Macro{normalfont}\Macro{normalcolor}.% + }% + \entry{\OptionVName{pagenumberwidth}{length}}{% + \ChangedAt{v3.27}{\Package{tocbasic}}% + You can use this attribute to locally change the width of the default box + for the page number of an entry with the style \PValue{tocline} from + \Macro{@pnumwidth} to the specified \PName{length}. Note that if you + change the default page number box with the \Option{pagenumberbox} + attribute, the specified \PName{length} will no longer be used + automatically.% + }% + \entry{\OptionVName{prepagenumber}{code}}{% + \ChangedAt{v3.27}{\Package{tocbasic}}% + The \PValue{toctext} style executes the \PName{code} between the text and + the page number of the entry. Usually this is used to add a horizontal + space or separator between text and page number.% + + The default is a non-breaking space using \Macro{nonbreakspace}.% + }% + \entry{\OptionVName{raggedentrytext}{switch}}{% + 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}}{% + The \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 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.% + }% + \entry{\OptionVName{raggedright}{switch}}{% + \ChangedAt{v3.27}{\Package{tocbasic}}% + The \PName{switch} is one of the values for simple switches from + \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. If the + switch is active for any entry with the \PValue{toctext} style inside the + same paragraph, the whole paragraph is printed ragged right. + }% + \entry{\OptionVName{rightindent}{length}}{% + \ChangedAt{v3.27}{\Package{tocbasic}}% + You can use this attribute to locally change the right indent for the text + of an entry with the \PValue{tocline} style from \Macro{@tocrmarg} to the + specified \PName{length}.% + }% +\end{desclist} + +While \Macro{DeclareTOCStyleEntry} defines only one \PName{entry level}, +\Macro{DeclareTOCStyleEntries}\ChangedAt{v3.26}{\Package{tocbasic}} can define +an entire list of \PName{entry level}s in one command. Each entry level in the +comma-separated \PName{entry-level list} is defined with the same \PName{style} +and settings of the given \PName{option list}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{DeclareTOCEntryStyle}\Parameter{style}% + \OParameter{initial code}% + \Parameter{command code}% + \Macro{DefineTOCEntryOption}\Parameter{option}\OParameter{default value}% + \Parameter{code}% + \Macro{DefineTOCEntryBooleanOption}\Parameter{option}% + \OParameter{default value}% + \Parameter{prefix}% + \Parameter{postfix}% + \Parameter{description}%% + %\OParameter{initial code}% + \Macro{DefineTOCEntryCommandOption}\Parameter{option}% + \OParameter{default value}% + \Parameter{prefix}% + \Parameter{postfix}% + \Parameter{description}%% + %\OParameter{initial code}% + \Macro{DefineTOCEntryIfOption}\Parameter{option}% + \OParameter{default value}% + \Parameter{prefix}% + \Parameter{postfix}% + \Parameter{description}%% + %\OParameter{initial code}% + \Macro{DefineTOCEntryLengthOption}\Parameter{option}% + \OParameter{default value}% + \Parameter{prefix}% + \Parameter{postfix}% + \Parameter{description}%% + %\OParameter{initial code}% + \Macro{DefineTOCEntryNumberOption}\Parameter{option}% + \OParameter{default value}% + \Parameter{prefix}% + \Parameter{postfix}% + \Parameter{description}% + %\OParameter{initial code}% +\end{Declaration} +\Macro{DeclareTOCEntryStyle}\ChangedAt{v3.20}{\Package{tocbasic}} is +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} 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}. 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. + +In\ChangedAt{v3.27}{\Package{tocbasic}} addition to the usual options of the +form \Option{\PName{key}=\PName{value}}, the five +\Macro{DefineTOCEntry\dots Option} commands automatically define options of +the form \Option{\PName{key}:=\PName{entry level}}. These copy the value of +another \PName{entry level} if the value is stored in a macro with the same +\PName{prefix} and \PName{postfix}. For the styles predefined by +\Package{tocbasic}, this is the case for all options of the same name +independent of the name of the style. The commands +\Macro{DefineTOCEntryLengthOption} and \Macro{DefineTOCEntryNumberOption} also +define options of the form \Option{\PName{key}:=\PName{value}}, which are used +to add the new \PName{value} to the value already stored in +\Macro{\PName{prefix}\PName{entry level}\PName{postfix}}. + +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 simplest style of \Package{tocbasic}, \PValue{gobble}, is defined +using: +\begin{lstcode} + \DeclareTOCEntryStyle{gobble}{}% +\end{lstcode} +If you now define an entry level \PValue{dummy} in this style using: +\begin{lstcode} + \DeclareTOCStyleEntry[level=1]{gobble}{dummy} +\end{lstcode} +this would correspond, among other things, to: +\begin{lstcode} + \def\dummytocdepth{1} + \def\l@dummy#1#2{} +\end{lstcode} + +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 the \Option{linefill} option. By specifying +\DescRef{\LabelBase.cmd.TOCLineLeaderFill} as the \PName{default value}, +a call such as +\begin{lstcode} + \DeclareTOCStyleEntry[linefill]{tocline}{part} +\end{lstcode} +would, among other things, create the definition +\begin{lstcode} + \def\scr@tso@part@linefill{\TOCLineLeaderFill} +\end{lstcode} + +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. + +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 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 + + +\begin{Declaration} + \Macro{CloneTOCEntryStyle}\Parameter{style}\Parameter{new style}% +\end{Declaration} +With\ChangedAt{v3.20}{\Package{tocbasic}} this command you can clone +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 + + +\begin{Declaration} + \Macro{TOCEntryStyleInitCode}\Parameter{style}% + \Parameter{initial code}% + \Macro{TOCEntryStyleStartInitCode}\Parameter{style}% + \Parameter{initial code} +\end{Declaration} +Every\ChangedAt{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 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 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}{% + \expandafter\providecommand% + \csname scr@tso@#1@linefill\endcsname + {\TOCLineLeaderFill\relax}% + } +\end{lstcode} +to define \PValue{section} as a modified clone of \PValue{tocline}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{LastTOCLevelWasHigher}% + \Macro{LastTOCLevelWasSame}% + \Macro{LastTOCLevelWasLower} +\end{Declaration} +At\ChangedAt{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{leader} +\end{Declaration} +This\ChangedAt{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 +\EndIndexGroup + + +\section{Internal Commands for Class and Package Authors} +\seclabel{internals} + +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} +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 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}}, +\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 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 + + +\begin{Declaration} + \Macro{tocbasic@@before@hook}% + \Macro{tocbasic@@after@hook} +\end{Declaration} +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 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 to output the content list, the hooks should be executed explicitly.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{tocbasic@\PName{extension}@before@hook}% + \Macro{tocbasic@\PName{extension}@after@hook} +\end{Declaration} +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 to output a content list, the hooks should nevertheless be called, if +they are defined. These commands can be undefined.% +\iffalse % With current LaTeX you can simply use \@ifundefined +For an appropriate test, see \DescRef{scrbase.cmd.Ifundefinedorrelax}% +\IndexCmd{Ifundefinedorrelax} in \autoref{sec:scrbase.if}, +\DescPageRef{scrbase.cmd.Ifundefinedorrelax}.% +\fi% +\EndIndexGroup + + +\begin{Declaration} + \Macro{tocbasic@listhead}\Parameter{title} +\end{Declaration} +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 +\Macro{tocbasic@listhead}.% +\EndIndexGroup + + +\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 +is defined. Otherwise, \DescRef{\LabelBase.cmd.tocbasic@listhead} defines them +before their use.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{tocbasic@addxcontentsline}% + \Parameter{extension}\Parameter{level}\Parameter{number}\Parameter{text}% + \Macro{nonumberline} +\end{Declaration} +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 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 + + +\begin{Declaration} + \Macro{tocbasic@DependOnPenaltyAndTOCLevel}\Parameter{entry level}% + \Macro{tocbasic@SetPenaltyByTOCLevel}\Parameter{entry level} +\end{Declaration} +The\ChangedAt{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 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}, we need a new floating environment. +That's easy with the following: +\begin{lstcode} + \newenvironment{remarkbox}{% + \@float{remarkbox}% + }{% + \end@float + } +\end{lstcode} +The new environment is named \Environment{remarkbox}. + +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} +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} +The new environment has floating type~4, so it may pass figures and floats and +may be passed by those. + +The\textnote{number} captions of floating environment also have numbers. +\begin{lstcode} + \newcounter{remarkbox} + \newcommand*{\remarkboxformat}{% + Remark~\theremarkbox\csname autodot\endcsname} + \newcommand*{\fnum@remarkbox}{\remarkboxformat} +\end{lstcode} +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 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} +As the file extension, we use ``\File{lor}''. + +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. Class or package authors would use +\begin{lstcode} + \RequirePackage{tocbasic} +\end{lstcode} +instead. + +Now\textnote{extension} we register the file name extension with the +\Package{tocbasic} package: +\begin{lstcode} + \addtotoclist[float]{lor} +\end{lstcode} +We use \PValue{float} as the owner so that all options of \KOMAScript{} +classes that relate to lists of floating environments also apply to the new +content list. + +Next\textnote{title} we define a title or heading for this content list: +\begin{lstcode} + \newcommand*{\listoflorname}{List of Remarks} +\end{lstcode} +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} +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} + +You\textnote{chapter entry} also want chapter entries to affect the content +list. +\begin{lstcode} + \setuptoc{lor}{chapteratlist} +\end{lstcode} +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} +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} +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 Only One Command} +\label{sec:tocbasic.declarenewtoc} + +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}} 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} (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{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{v3.20}{\Package{tocbasic}}% +\ChangedAt{v3.21}{\Package{tocbasic}} on the style of the entries to +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 +\autoref{sec:tocbasic.tocstyle}, +\DescPageRef{\LabelBase.cmd.DeclareTOCStyleEntry} for more information about +the styles.% +% +\begin{desclist} + \renewcommand*{\abovecaptionskipcorrection}{-\normalbaselineskip}% + \desccaption[{Options for command \Macro{DeclareNewTOC}}]{% + Options for the + \Macro{DeclareNewTOC}\ChangedAt{v3.06}{\Package{tocbasic}} command% + \label{tab:tocbasic.DeclareNewTOC-options}% + }{% + Options for the \Macro{DeclareNewTOC} command (\emph{continued})% + }% + \entry{\OptionVName{atbegin}{commands}% + \ChangedAt{v3.09}{\Package{tocbasic}}}{% + The \PName{commands} will be executed at the begin of the floating or + non-floating environment.% + }% + \entry{\OptionVName{atend}{commands}% + \ChangedAt{v3.09}{\Package{tocbasic}}}{% + The \PName{commands} will be executed at the end of the floating or + non-floating environment.% + }% + \entry{\OptionVName{category}{string}}{% + \ChangedAt{v3.27}{\Package{tocbasic}}% + This option can be used as a synonym for \OptionVName{owner}{string}.% + }% + \entry{\OptionVName{counterwithin}{\LaTeX{} counter}}{% + 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 dependent on another + \PName{\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. A\ChangedAt{v3.35}{\Package{tocbasic}} setting + \OptionValue{counterwithin}{chapter} is used for classes with + \DescRef{maincls.cmd.chapter}\IndexCmd{chapter} only in the main matter + (see \DescRef{maincls.cmd.frontmatter}\IndexCmd{frontmatter}, + \DescRef{maincls.cmd.mainmatter} and + \DescRef{maincls.cmd.backmatter}\IndexCmd{backmatter} in + \autoref{sec:maincls.separation}, \DescPageRef{maincls.cmd.frontmatter}) + and only if the counter \Counter{chapter}\IndexCounter{chapter} is greater + than zero at output. For classes without \DescRef{maincls.cmd.chapter} + this applies accordingly to the \OptionValue{counterwithin}{section} + setting and counter + \Counter{section}\IndexCounter{section}\IndexCmd{section}.% + }% + \entry{\Option{float}}{% + 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}}{% + 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}}{% + 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 defined even if they were already defined + before.% + }% + \entry{\OptionVName{hang}{length}}{% + \ChangedAt{v3.20}{\Package{tocbasic}}% + \ChangedAt{v3.21}{\Package{tocbasic}}% + 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{v3.20}{\Package{tocbasic}}% + \ChangedAt{v3.21}{\Package{tocbasic}}% + 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{v3.20}{\Package{tocbasic}}% + \ChangedAt{v3.21}{\Package{tocbasic}}% + 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}{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}{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, 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}}{% + 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{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{tocentry}. 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}}{% + \ChangedAt{v3.20}{\Package{tocbasic}}% + Additional options depending on the \PName{TOC-entry style} given by + \Option{tocentrystyle}. See \autoref{sec:tocbasic.tocstyle}, + \autopageref{sec:tocbasic.tocstyle} for additional information about + 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}.% + }% + \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}}{% + 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} significantly shortens the example from + \autoref{sec:tocbasic.example}: +\begin{lstcode} + \DeclareNewTOC[% + type=remarkbox,% + types=remarkboxes,% + float,% define a floating environment + floattype=4,% + name=Remark,% + listname={List of Remarks}% + ]{lor} + \setuptoc{lor}{chapteratlist} +\end{lstcode} + 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 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}} + compares the commands, counters, and environments of the + example \Environment{remarkbox} environment to the commands, counters, + and environments of figures.% + \begin{table} + \centering + \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 + \Environment{remarkbox} & \Environment{figure} + & options of \Macro{DeclareNewTOC} & short description \\[1ex] + \midrule + \Environment{remarkbox} & \Environment{figure} + & \Option{type}, \Option{float} + & floating environments of the respective types\\[1ex] + \Environment{remarkbox*} & \Environment{figure*} + & \Option{type}, \Option{float} + & columns spanning floating environments of the respective types\\[1ex] + \Counter{remarkbox} & \Counter{figure} + & \Option{type}, \Option{float} + & counter used by \DescRef{maincls.cmd.caption}\\[1ex] + \Macro{theremarkbox} & \Macro{thefigure} + & \Option{type}, \Option{float} + & output command to the respective counters\\[1ex] + \Macro{remarkboxformat} & \DescRef{maincls.cmd.figureformat} + & \Option{type}, \Option{float} + & formatting command to the respective counters used by + \DescRef{maincls.cmd.caption}\\[1ex] + \Macro{remarkboxname} & \Macro{figurename} + & \Option{type}, \Option{float}, \Option{name} + & names used in the label of \DescRef{maincls.cmd.caption}\\[1ex] + \Macro{listofremarkboxes} & \DescRef{maincls.cmd.listoffigures} + & \Option{types}, \Option{float} + & command to show the list of the respective environments\\[1ex] + \Macro{listremarboxname} & \Macro{listfigurename} + & \Option{type}, \Option{float}, \Option{listname} + & heading text of the respective list \\[1ex] + \Macro{fps@remarkbox} & \Macro{fps@figure} + & \Option{type}, \Option{float}, \Option{floattype} + & numeric float type for order perpetuation\\[1ex] + \File{lor} & \File{lof} + & + & file name extension of the TOC file of the respective list \\ + \bottomrule + \end{tabularx} + \end{table} + + And here is a possible use of the example environment: +\begin{lstcode} + \begin{remarkbox} + \centering + 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 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 + 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 Law of Typography + }\\ + \end{tabular}% + \end{center}% +\end{Example} + +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 + + +\section{Obsolete Befehle} +\seclabel{obsolete} + +% TODO: new translation +Prior releases of \Package{tocbasic} provide some commands that has been +renamed, because of a statement of The \LaTeX{} Project Team. Those deprecated +commands should not be used any longer. +% :ODOT + +\LoadNonFree{tocbasic}{0}% +% +\EndIndexGroup +% +\endinput + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "scrguide-en.tex" +%%% coding: utf-8 +%%% ispell-local-dictionary: "en_GB" +%%% eval: (flyspell-mode 1) +%%% End: + +% LocalWords: Multiline multiline |