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