summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/koma-script/source-doc/english/tocbasic.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/koma-script/source-doc/english/tocbasic.tex')
-rw-r--r--macros/latex/contrib/koma-script/source-doc/english/tocbasic.tex338
1 files changed, 240 insertions, 98 deletions
diff --git a/macros/latex/contrib/koma-script/source-doc/english/tocbasic.tex b/macros/latex/contrib/koma-script/source-doc/english/tocbasic.tex
index 36681ff609..bd34f48969 100644
--- a/macros/latex/contrib/koma-script/source-doc/english/tocbasic.tex
+++ b/macros/latex/contrib/koma-script/source-doc/english/tocbasic.tex
@@ -1,6 +1,6 @@
% ======================================================================
% tocbasic.tex
-% Copyright (c) Markus Kohm, 2002-2018
+% Copyright (c) Markus Kohm, 2002-2019
%
% 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-2018
+% Copyright (c) Markus Kohm, 2002-2019
%
% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz,
% Version 1.3c, verteilt und/oder veraendert werden.
@@ -46,10 +46,10 @@
% ======================================================================
\KOMAProvidesFile{tocbasic.tex}
- [$Date: 2018-08-31 09:11:20 +0200 (Fri, 31 Aug 2018) $
+ [$Date: 2019-10-10 09:50:23 +0200 (Thu, 10 Oct 2019) $
KOMA-Script guide (package tocbasic)]
-% Date of the translated German file: 2018-08-31
+% Date of the translated German file: 2019-10-09
\translator{Markus Kohm\and Arndt Schubert\and Karl Hagen}
@@ -83,26 +83,26 @@ contents but also for the already mentioned lists of figures and tables.
\label{sec:tocbasic.basics}
The basic commands are primarily used to handle a list of all known file
-extensions\textnote{file extension, content lists} that
-represent a table or list of contents. We call these auxiliary
-files\Index{auxiliary file}\footnote{The term \emph{auxiliary file} here
- refers not to the main \File{aux} file but to the other internal files used
- indirectly via the \File{aux} file, e.\,g. the \File{toc} file, the
- \File{lof} file, or the \File{lot} file.} TOC files\textnote{TOC
- file}\Index[indexmain]{TOC file} regardless of the file extension that is
-actually used. Entries to such files are typically written using
+extensions\textnote{file extension, content lists} that represent a table or
+list of contents. We call these auxiliary files\Index{auxiliary
+ file}\footnote{The term \emph{auxiliary file} here refers not to the main
+ \File{aux} file but to the other internal files used indirectly via the
+ \File{aux} file, e.\,g. the \File{toc} file, the \File{lof} file, or the
+ \File{lot} file.} TOC files\textnote{TOC file}\Index[indexmain]{TOC file}
+regardless of the file extension that is actually used. Entries to such files
+are typically written using
\Macro{addtocontents}\important{\Macro{addtocontents},
-\DescRef{\LabelBase.cmd.addxcontentsline}}, or
+ \DescRef{\LabelBase.cmd.addxcontentsline}}, 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.
+may be a class or package, or an identifier of a category that the author of
+the class or package using \Package{tocbasic} has chosen independently. For
+example, \KOMAScript{} uses the category \texttt{float} as owner for the
+\File{lof} and \File{lot} file extensions that are associated with the list of
+figures and list of tables, respectively. For the table of contents,
+\KOMAScript{} uses the file name of the class.
\begin{Declaration}
\Macro{ifattoclist}\Parameter{extension}\Parameter{then code}%
@@ -198,8 +198,8 @@ brackets. An empty argument would also result in an empty owner.
\end{Example}
You can specify any \PName{owner} you want, but it must be unique. For
example, if you were the author of the \Package{float} package, you could
-specify ``\PValue{float}'' instead of ``\PValue{float.sty}'' as the
-\PName{owner}. In this case, the \KOMAScript{}
+specify the category ``\PValue{float}'' instead of ``\PValue{float.sty}'' as
+the \PName{owner}. In this case, the \KOMAScript{}
options\important{\DescRef{maincls.option.listof}}%
\IndexOption{listof~=\PName{setting}} for the list of figures and the list of
tables would also affect your content lists because these lists are already
@@ -383,7 +383,7 @@ 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},
+\autoref{sec:maincls-experts.toc},
\DescPageRef{maincls-experts.cmd.addparttocentry}). If the corresponding
command is undefined, the internal command
\DescRef{\LabelBase.cmd.tocbasic@addxcontentsline} is used instead. This takes
@@ -623,7 +623,12 @@ 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.%
+that \PValue{\#1} will be replaced by the title of this content list.
+
+Obviously, the \PName{definition} is also responsible for the interpretation
+of additional features related to the title. This is especially true
+for the features \PValue{leveldown}, \PValue{numbered} and \PValue{totoc},
+that are be explained next.%
\EndIndexGroup
@@ -636,7 +641,7 @@ You can use these two commands to set and clear features for a TOC file
list} is a comma-separated list of features. The \Package{tocbasic} package
recognizes following features:
\begin{description}
-\item[\texttt{leveldown}] means that the content list's heading is created not
+\item[\PValue{leveldown}] means that the content list's heading is created not
with the highest sectioning level below
\DescRef{maincls.cmd.part}\,---\,\DescRef{maincls.cmd.chapter} if available,
\DescRef{maincls.cmd.section} otherwise\,---\,but with a heading of the next
@@ -648,7 +653,7 @@ recognizes following features:
important{\OptionValueRef{maincls}{listof}{leveldown}}%
\IndexOption{listof~=\textKValue{leveldown}} option for all file extensions
with the owner \PValue{float}.
-\item[\texttt{nobabel}] prevents using the language-switching features of
+\item[\PValue{nobabel}] prevents using the language-switching features of
\Package{babel}\IndexPackage{babel} for the TOC file associated with the
this file \PName{extension}. This feature should be used only for content
lists that are created in a fixed language, which means that changes of the
@@ -660,14 +665,20 @@ recognizes following features:
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}}
+\item[\PValue{noindent}]\ChangedAt{v3.27}{\Package{tocbasic}}%
+ causes all content-list entry styles provided by \KOMAScript{} to ignore
+ the \PValue{indent} attribute (see
+ \autoref{tab:tocbasic.tocstyle.attributes},
+ \autopageref{tab:tocbasic.tocstyle.attributes.indent}) and instead to
+ deactivate the indentation.%
+\item[\PValue{noparskipfake}] prevents\ChangedAt{v3.17}{\Package{tocbasic}}
the insertion of a final \Length{parskip} before switched off paragraph
spacing for content lists. In general, this will cause documents that use
spacing between paragraphs to have less vertical space between the list
heading and first entry than between normal headings and normal text.
Normally, therefore, you will obtain a more uniform formatting without this
feature.
-\item[\texttt{noprotrusion}] prevents\ChangedAt{v3.10}{\Package{tocbasic}}
+\item[\PValue{noprotrusion}] prevents\ChangedAt{v3.10}{\Package{tocbasic}}
character protrusion, which allows optical margin alignment, from being
disabled in the content lists. By default, character protrusion is disabled
when the \Package{microtype}\IndexPackage{microtype} package, or another
@@ -676,7 +687,7 @@ recognizes following features:
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
+\item[\PValue{numbered}] means that the heading for the content list should
be numbered and included in the table of contents. This feature is evaluated
by the internal heading command. However, if a user-defined heading command
has been created with \DescRef{\LabelBase.cmd.deftocheading}, the person
@@ -686,7 +697,7 @@ recognizes following features:
\important{\OptionValueRef{maincls}{listof}{numbered}}%
\IndexOption{listof~=\textKValue{numbered}} option for all file extensions
with the owner \PValue{float}.
-\item[\texttt{numberline}] \leavevmode\ChangedAt{v3.12}{\Package{tocbasic}}%
+\item[\PValue{numberline}] \leavevmode\ChangedAt{v3.12}{\Package{tocbasic}}%
means that any entries made using \DescRef{\LabelBase.cmd.addxcontentsline}
or \DescRef{\LabelBase.cmd.addxcontentslinetoeachtocfile}, where the
optional argument for the number is missing or empty, will be provided with
@@ -714,7 +725,7 @@ recognizes following features:
\OptionValueRef{maincls}{toc}{nonumberline}%
\important{\OptionValueRef{maincls}{toc}{nonumberline}}%
\IndexOption{toc~=\textKValue{nonumberline}}.
-\item[\texttt{onecolumn}] \leavevmode\ChangedAt{v3.01}{\Package{tocbasic}}%
+\item[\PValue{onecolumn}] \leavevmode\ChangedAt{v3.01}{\Package{tocbasic}}%
means that this content list will automatically use \LaTeX's internal
one-column mode with \Macro{onecolumn}\IndexCmd{onecolumn}.
However\textnote{Attention!}, this applies only if this content list does
@@ -728,7 +739,7 @@ recognizes following features:
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
+\item[\PValue{totoc}] means that the title of content list should be included
in the table of contents. This feature will be evaluated by the internal
heading command. However, if an user-defined heading command has been
created with \DescRef{\LabelBase.cmd.deftocheading}, the person defining
@@ -740,7 +751,7 @@ recognizes following features:
\end{description}
The \KOMAScript{} classes recognize an additional feature:
\begin{description}
-\item[\texttt{chapteratlist}] ensures that an optional subdivision is added
+\item[\PValue{chapteratlist}] ensures that an optional subdivision is added
to the content list for each new chapter. By default, this subdivision is a
vertical space. See \DescRef{maincls.option.listof}%
\IndexOption{listof}\important{\DescRef{maincls.option.listof}} in
@@ -804,7 +815,7 @@ you define your own heading command using
\BeginIndex{}{table of contents>entry}%
\Index{list of contents|\see{table of contents}}
-Since\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} version~3.20, the
+Since\ChangedAt{v3.20}{\Package{tocbasic}} version~3.20, the
\Package{tocbasic} package has been able not only to configure the tables or
lists of contents and their auxiliary files but also to influence their
entries. To do so, you can define new styles or you can use and configure one
@@ -839,7 +850,7 @@ later in this section}) observe \Counter{tocdepth}.%
\Macro{numberline}\Parameter{entry number}%
\Macro{usetocbasicnumberline}\OParameter{code}
\end{Declaration}
-Although\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} the \LaTeX{} kernel
+Although\ChangedAt{v3.20}{\Package{tocbasic}} the \LaTeX{} kernel
already defines a \Macro{numberline} command, the definition is not sufficient
for \Package{tocbasic}. Therefore \Package{tocbasic} defines its own commands
and sets \Macro{numberline} as needed using \Macro{usetocbasicnumberline} for
@@ -1016,18 +1027,19 @@ Currently, \Package{tocbasic} defines the following entry styles:
\PValue{section} and \PValue{subsection} using this style, but add extra
\PName{initial code} to the clones to change their defaults.
- The style supports 16\important{\PValue{level}, \PValue{beforeskip},
+ The style supports 18\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
+ \PValue{pagenumberwidth}, \PValue{raggedentrytext},
+ \PValue{raggedpagenumber}, \PValue{rightindent}} additional attributes in
+ addition to the default \PValue{level} attribute. The defaults of all these
+ attributes depend on the name of the \PName{entry level} and correspond to
+ the results of the standard classes. So after loading \Package{tocbasic},
+ you can change the style of the entries in the table of contents of the
+ standard classes into \PValue{tocline} using
\DescRef{\LabelBase.cmd.DeclareTOCEntryStyle} without this leading directly
to major changes in their appearance. Thus you can precisely change only
those attributes that are necessary for the desired changes. The same
@@ -1190,6 +1202,20 @@ Currently, \Package{tocbasic} defines the following entry styles:
\PValue{tocline} style}
\label{fig:tocbasic.tocline}
\end{figure}
+\item[\PValue{toctext}]\ChangedAt{v3.27}{\Package{tocbasic}}%
+ is a special feature. While all other styles produce one paragraph per
+ entry, this one produces one paragraph for all successive entries of this
+ style. With 13\important{\PValue{afterpar}, \PValue{entryformat},
+ \PValue{entrynumberformat}, \PValue{indent}, \PValue{numsep},
+ \PValue{onendentry}, \PValue{onendlastentry}, \PValue{onstartentry},
+ \PValue{onstartfirstentry}, \PValue{pagenumberformat},
+ \PValue{prepagenumber}, \PValue{raggedright}, \PValue{rightindent}}
+ attributes in addition to the default \PValue{level} attribute, there are
+ almost as many options as for \PValue{tocline}. However, this style
+ depends on the fact that an unfinished paragraph will be concluded at the
+ beginning of the entry for all other styles, as well as at the end of the
+ current content list. So it should never be combined with entries or content
+ lists that are generated outside of \Package{tocbasic}.
\item[\PValue{undottedtocline}] is similar to the style used by the standard
\Class{book} and \Class{report} classes for the \PValue{chapter} entry
level, or by \Class{article} for the \PValue{section} entry level in the
@@ -1246,11 +1272,27 @@ Currently, \Package{tocbasic} defines the following entry styles:
\end{description}
You can find an explanation of the attributes of all styles that
\Package{tocbasic} defines in \autoref{tab:tocbasic.tocstyle.attributes}.
+In\ChangedAt{v3.27}{\Package{tocbasic}} addition to the usual assignment with
+\Option{\PName{key}=\PName{value}}, both commands understand an assignment in
+the form \Option{\PName{key}:=\PName{entry level}} for all options of the
+\KOMAScript{} styles. In this case, the current setting of \PName{key} for the
+\PName{entry level} will be copied. For example, you can copy the current
+indent of the \PValue{figure} level using \OptionValue{indent:}{figure}. For
+options that expect a length or integer value, you can also use
+\Option{\PName{key}+=\PName{value}} to add\PName{value} to the current setting
+of the \PName{key}. To subtract simply, you can use a negative \PName{value}.
+For example, with \OptionValue{indent+}{1cm} you can increase the indent by
+1\Unit{cm}.
+
If\ChangedAt{v3.21}{\Package{tocbasic}} you use these attributes as
options to \DescRef{\LabelBase.cmd.DeclareNewTOC} (see
\DescPageRef{\LabelBase.cmd.DeclareNewTOC}), you must prefix the names of the
-attribute by \PValue{tocentry}, e\,g. \PValue{level} becomes
-\Option{tocentrylevel}. If\ChangedAt{v3.20}{\Package{tocbasic}} use
+attributes with \PValue{tocentry}, e\,g., \PValue{level} becomes
+\Option{tocentrylevel}. The copy operation with \Option{:=} described above is
+also available here. However, addition with \Option{+=} is not currently
+supported.
+
+If\ChangedAt{v3.20}{\Package{tocbasic}} you use
these attributes as options for
\DescRef{maincls-experts.cmd.DeclareSectionCommand}%
\IndexCmd{DeclareSectionCommand}\IndexCmd{DeclareNewSectionCommand}%
@@ -1258,6 +1300,8 @@ these attributes as options for
\DescPageRef{maincls-experts.cmd.DeclareSectionCommand}) and similar commands,
you must prefix the names of the attributes with \PValue{toc}, e\,g.
\PValue{level} becomes \Option{toclevel}.
+At this time, neither the copy operation with \Option{:=} nor the
+addition operation with \Option{+=} is supported.
Finally, using \Macro{DeclareTOCStyleEntry} will define the internal command
\Macro{l@\PName{entry level}}.
@@ -1269,6 +1313,13 @@ Finally, using \Macro{DeclareTOCStyleEntry} will define the internal command
}{%
Attributes of the TOC-entry styles (\emph{continued})%
}%
+ \entry{\OptionVName{afterpar}{code}}{%
+ \ChangedAt{v3.27}{\Package{tocbasic}}%
+ The specified \PName{code} will be executed after the end of the paragraph
+ in which an entry with the \PValue{toctext} style is printed. If several
+ entries have such settings, their code will be executed in the order of
+ the entries.%
+ }%
\entry{\OptionVName{beforeskip}{length}}{%
The vertical distance inserted before an entry of this level in the
\PValue{tocline} style (see \autoref{fig:tocbasic.tocline}). The distance
@@ -1342,12 +1393,19 @@ Finally, using \Macro{DeclareTOCStyleEntry} will define the internal command
\IndexOption{toc~=\textKValue{numberline}} option, the unnumbered entries
will execute the \PName{command} as well.%
}%
- \entry{\OptionVName{indent}{length}}{%
- The horizontal distance of the entry from the left margin (see
+ \entry{%
+ \OptionVName{indent}{length}%
+ {\phantomsection\label{tab:tocbasic.tocstyle.attributes.indent}}%
+ }{%
+ For\ChangedAt{v3.27}{\Package{tocbasic}} the \PValue{toctext} style, the
+ \PName{length} is the horizontal distance of the paragraph from the left
+ margin. If different entries within the paragraph have different settings,
+ the last one is used. For the remaining styles, the \PName{length} is the
+ horizontal distance of the entry from the left margin (see
\autoref{fig:tocbasic.dottedtocline} and \autoref{fig:tocbasic.tocline}).
-
- For the \PValue{tocline} style, all entry levels whose names start with
- ``\texttt{sub}'' are initialised with the
+
+ For the styles \PValue{tocline} and \PValue{toctext}, all entry levels
+ whose names start with ``\texttt{sub}'' are initialised with the
\PValue{indent}+\PValue{numwidth} of the entry level of the same name
without this prefix. For the \PValue{dottedtocline},
\PValue{undottedtocline}, and \PValue{tocline} styles, the initial values
@@ -1355,7 +1413,11 @@ Finally, using \Macro{DeclareTOCStyleEntry} will define the internal command
\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.%
+ time.
+
+ If the \PValue{noindent} attribute is set for a content list via
+ \DescRef{\LabelBase.cmd.setuptoc}, the entries of all styles provided by
+ \KOMAScript{} enforce the value 0\Unit{pt} to deactivate the indent.%
}%
\entry{\OptionVName{level}{integer}}{%
The numerical value of the \PName{entry level}. Only those entries whose
@@ -1367,15 +1429,15 @@ Finally, using \Macro{DeclareTOCStyleEntry} will define the internal command
This attribute is mandatory for all styles and will be defined
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.%
+ For the \PValue{tocline} and \PValue{toctext} styles, all entry levels
+ whose name starts with ``\texttt{sub}'' are initialised with the value of
+ the entry level of the same name without this prefix plus one. For the
+ \PValue{dottedtocline}, \PValue{largetocline}, \PValue{tocline},
+ \PValue{toctext}, and \PValue{undottedtocline} styles, the entry levels
+ from \PValue{part} to \PValue{subparagraph}, as well as \PValue{figure}
+ and \PValue{table}, are initialised to be compatible with the standard
+ classes. For all other levels, the initialisation is done with the value
+ of \Macro{\PName{entry level}numdepth}, if this is defined.%
}%
\entry{\OptionVName{linefill}{code}}{%
With the \PValue{tocline} style, you can change what is used to fill the
@@ -1395,9 +1457,14 @@ Finally, using \Macro{DeclareTOCStyleEntry} will define the internal command
\entry{\OptionVName{numsep}{length}}{%
The \PValue{tocline} style tries to ensure a minimum distance of
\PName{length} between the entry number and the entry text. If
- \PValue{dynnumwidth} is active, it will correct the number width to achieve
- this. Otherwise it simply throws a warning, if the condition is not met.
+ \PValue{dynnumwidth} is active, it will correct the number width to
+ achieve this. Otherwise it simply throws a warning if the condition is not
+ met.
+ The\ChangedAt{v3.27}{\Package{tocbasic}} \PValue{toctext} style, on the
+ other hand, always adds a horizontal space of width \PName{length} after
+ the number of the entry.
+
The initial \PName{length} is 0.4\Unit{em}.%
}%
\entry{\OptionVName{numwidth}{length}}{%
@@ -1419,6 +1486,37 @@ Finally, using \Macro{DeclareTOCStyleEntry} will define the internal command
you must set \PValue{numwidth} explicitly when the entry level is first
used.%
}%
+ \entry{\OptionVName{onendentry}{code}}{%
+ \ChangedAt{v3.27}{\Package{tocbasic}}%
+ The \PName{code} is executed immediately after an entry with the
+ \PValue{toctext} style, if this entry is not the last one of the
+ paragraph. The user must ensure that the \PName{code} does not result in
+ the paragraph ending.
+
+ Note: In reality the \PName{code} is not executed at the end of the entry
+ but before the next entry with style \PValue{toctext}.%
+ }%
+ \entry{\OptionVName{onendlastentry}{code}}{%
+ \ChangedAt{v3.27}{\Package{tocbasic}}%
+ The \PName{code} is executed immediately before the end of the paragraph
+ with an entry in the \PValue{toctext} style, as long as this entry is the
+ last one in the paragraph. The user must ensure that the \PName{code} does
+ not result in the paragraph ending.%
+ }%
+ \entry{\OptionVName{onstartentry}{code}}{%
+ \ChangedAt{v3.27}{\Package{tocbasic}}%
+ The \PName{code} is executed immediately before an entry with the
+ \PValue{toctext} style, unless it is the first one in the paragraph. The
+ user must ensure that the \PName{code} does not result in the paragraph
+ ending.%
+ }%
+ \entry{\OptionVName{onstartfirstentry}{code}}{%
+ \ChangedAt{v3.27}{\Package{tocbasic}}%
+ The \PName{code} is executed immediately before an entry with the
+ \PValue{toctext} style if this entry is the first one of the paragraph. The
+ user must ensure that the \PName{code} does not result in the paragraph
+ ending.%
+ }%
\entry{\OptionVName{onstarthigherlevel}{code}}{%
The \PValue{tocline} style can execute \PName{code} at the start of an
entry, depending on whether the previous entry had numerical level greater
@@ -1482,6 +1580,23 @@ Finally, using \Macro{DeclareTOCStyleEntry} will define the internal command
all other levels prints the argument in
\Macro{normalfont}\Macro{normalcolor}.%
}%
+ \entry{\OptionVName{pagenumberwidth}{length}}{%
+ \ChangedAt{v3.27}{\Package{tocbasic}}%
+ You can use this attribute to locally change the width of the default box
+ for the page number of an entry with the style \PValue{tocline} from
+ \Macro{@pnumwidth} to the specified \PName{length}. Note that if you
+ change the default page number box with the \Option{pagenumberbox}
+ attribute, the specified \PName{length} will no longer be used
+ automatically.%
+ }%
+ \entry{\OptionVName{prepagenumber}{code}}{%
+ \ChangedAt{v3.27}{\Package{tocbasic}}%
+ The \PValue{toctext} style executes the \PName{code} between the text and
+ the page number of the entry. Usually this is used to add a horizontal
+ space or separator between text and page number.%
+
+ The default is a non-breaking space using \Macro{nonbreakspace}.%
+ }%
\entry{\OptionVName{raggedentrytext}{switch}}{%
The\ChangedAt{v3.21}{\Package{tocbasic}} \PName{switch} is one of the
values for simple switches from \autoref{tab:truefalseswitch},
@@ -1508,16 +1623,26 @@ Finally, using \Macro{DeclareTOCStyleEntry} will define the internal command
\DescRef{\LabelBase.cmd.TOCLineLeaderFill} for the \PValue{linefill}
attribute.%
}%
+ \entry{\OptionVName{raggedright}{switch}}{%
+ \ChangedAt{v3.27}{\Package{tocbasic}}%
+ The \PName{switch} is one of the values for simple switches from
+ \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. If the
+ switch is active for any entry with the \PValue{toctext} style inside the
+ same paragraph, the whole paragraph is printed ragged right.
+ }%
+ \entry{\OptionVName{rightindent}{length}}{%
+ \ChangedAt{v3.27}{\Package{tocbasic}}%
+ You can use this attribute to locally change the right indent for the text
+ of an entry with the \PValue{tocline} style from \Macro{@tocrmarg} to the
+ specified \PName{length}.%
+ }%
\end{desclist}
-% New translation by Markus Kohm (please fix it!):
-\Macro{DeclareTOCStyleEntries}\ChangedAt{v3.26}{\Package{tocbasic}} uses
-\Macro{DeclareTOCStyleEntry} to define not only one \PName{entry level} but
-several entry levels. Each of the entry levels, given by the comma-separated
-\PName{entry level list}, is defined with the same \PName{style} and the
-settings of the given \PName{option list}.%
-% End of new translation.
-%
+While \Macro{DeclareTOCStyleEntry} defines only one \PName{entry level},
+\Macro{DeclareTOCStyleEntries}\ChangedAt{v3.26}{\Package{tocbasic}} can define
+an entire list of \PName{entry level}s in one command. Each entry level in the
+comma-separated \PName{entry-level list} is defined with the same \PName{style}
+and settings of the given \PName{option list}.%
\EndIndexGroup
@@ -1558,7 +1683,7 @@ settings of the given \PName{option list}.%
\Parameter{description}%
%\OParameter{initial code}%
\end{Declaration}
-\Macro{DeclareTOCEntryStyle}\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} is
+\Macro{DeclareTOCEntryStyle}\ChangedAt{v3.20}{\Package{tocbasic}} is
one of the most complex commands in \KOMAScript. It is therefore explicitly
intended for \LaTeX{} developers and not for ordinary \LaTeX{} users. It lets
you define new a \PName{style} for content-list entries. Usually, entries to
@@ -1592,20 +1717,33 @@ automatically. The value of the \Option{level} can be queried within the
\important{\Macro{\PName{entry level}tocdepth}}, for example, to compare it
with the \DescRef{\LabelBase.counter.tocdepth}\IndexCounter{tocdepth} counter.
-To define options for the attributes of the
-\PName{style} inside the \PName{initial code}, you can use the commands \Macro{DefineTOCEntryBooleanOption},
-\Macro{DefineTOCEntryCommandOption}, \Macro{DefineTOCEntryIfOption},
-\Macro{DefineTOCEntryLengthOption}, and \Macro{DefineTOCEntryNumberOption}.
-These commands each define an \PName{option} that, when called,
-defines a macro named \Macro{\PName{prefix}\PName{entry
- level}\PName{postfix}} set to the given value or to the
-\PName{default value} of the option. The
-\Macro{DefineTOCEntryIfOption} command is a somewhat special case. It defines \Macro{\PName{prefix}\PName{entry
- level}\PName{postfix}} as a command with two arguments. If the value passed to
-the option is one of the activation (true) values from \autoref{tab:truefalseswitch},
-\autopageref{tab:truefalseswitch}, the command expands to the first
-argument. If the value to the option is a deactivation (false) value, the command
-expands to the second argument.
+To define options for the attributes of the \PName{style} inside the
+\PName{initial code}, you can use the commands
+\Macro{DefineTOCEntryBooleanOption}, \Macro{DefineTOCEntryCommandOption},
+\Macro{DefineTOCEntryIfOption}, \Macro{DefineTOCEntryLengthOption}, and
+\Macro{DefineTOCEntryNumberOption}. These commands each define an
+\PName{option} that, when called, defines a macro named
+\Macro{\PName{prefix}\PName{entry level}\PName{postfix}} set to the given
+value or to the \PName{default value} of the option. The
+\Macro{DefineTOCEntryIfOption} command is a somewhat special case. It defines
+\Macro{\PName{prefix}\PName{entry level}\PName{postfix}} as a command with two
+arguments. If the value passed to the option is one of the activation (true)
+values from \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch},
+the command expands to the first argument. If the value to the option is a
+deactivation (false) value, the command expands to the second argument.
+
+In\ChangedAt{v3.27}{\Package{tocbasic}} addition to the usual options of the
+form \Option{\PName{key}=\PName{value}}, the five
+\Macro{DefineTOCEntry\dots Option} commands automatically define options of
+the form \Option{\PName{key}:=\PName{entry level}}. These copy the value of
+another \PName{entry level} if the value is stored in a macro with the same
+\PName{prefix} and \PName{postfix}. For the styles predefined by
+\Package{tocbasic}, this is the case for all options of the same name
+independent of the name of the style. The commands
+\Macro{DefineTOCEntryLengthOption} and \Macro{DefineTOCEntryNumberOption} also
+define options of the form \Option{\PName{key}:=\PName{value}}, which are used
+to add the new \PName{value} to the value already stored in
+\Macro{\PName{prefix}\PName{entry level}\PName{postfix}}.
The \PName{description} should be a brief message that describes the sense
of the option with some keywords. The \Package{tocbasic} package uses this text
@@ -1662,7 +1800,7 @@ mentioned here only for the sake of completeness.%
\begin{Declaration}
\Macro{CloneTOCEntryStyle}\Parameter{style}\Parameter{new style}%
\end{Declaration}
-With\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} this command you can clone
+With\ChangedAt{v3.20}{\Package{tocbasic}} this command you can clone
an existing \PName{style}. It defines a \PName{new style} with the same
attributes and settings as the existing \PName{style}. The package itself uses
\Macro{CloneTOCEntryStyle} to declare the \PValue{default} style as a clone of
@@ -1683,7 +1821,7 @@ of \PValue{section}, and \Class{scrartcl} declares it as a clone of
\Macro{TOCEntryStyleStartInitCode}\Parameter{style}%
\Parameter{initial code}
\end{Declaration}
-Every\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} TOC-entry style has an
+Every\ChangedAt{v3.20}{\Package{tocbasic}} TOC-entry style has an
initialisation code. This is used whenever a \PName{style} is assigned to an
TOC entry using \DescRef{\LabelBase.cmd.DeclareTOCEntryStyle}. This
\PName{initial code} should not have global side effects, because it is also
@@ -1718,7 +1856,7 @@ to define \PValue{section} as a modified clone of \PValue{tocline}.%
\Macro{LastTOCLevelWasSame}%
\Macro{LastTOCLevelWasLower}
\end{Declaration}
-At\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} the beginning of entries
+At\ChangedAt{v3.20}{\Package{tocbasic}} the beginning of entries
using the \PValue{tocline} style, \Package{tocbasic} executes one of these
three commands depending on \Macro{lastpenalty}. \Macro{LastTOCLevelWasHigher}
and \Macro{LastTOCLevelWasSame} used in vertical mode add
@@ -1736,7 +1874,7 @@ behaviour of single entry levels using the \PValue{onstartlowerlevel},
\begin{Declaration}
\Macro{TOCLineLeaderFill}\OParameter{leader}
\end{Declaration}
-This\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} command is intended to be
+This\ChangedAt{v3.20}{\Package{tocbasic}} command is intended to be
used as a value for the \Option{linefill} option of the \PName{tocline}
TOC-entry style. It creates a connection between the end of the entry text and
the entry's page number. You can specify the \PName{leader}, which is repeated
@@ -1925,7 +2063,7 @@ run.%
\Macro{tocbasic@DependOnPenaltyAndTOCLevel}\Parameter{entry level}%
\Macro{tocbasic@SetPenaltyByTOCLevel}\Parameter{entry level}
\end{Declaration}
-The\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} \PValue{tocline}
+The\ChangedAt{v3.20}{\Package{tocbasic}} \PValue{tocline}
content-list style (see \autoref{sec:tocbasic.tocstyle}) sets a
\Macro{penalty} at the end of each entry via
\Macro{tocbasic@SetPenaltyByTOCLevel} so that no page break can occur after an
@@ -2126,15 +2264,15 @@ 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}} the \Option{tocentrystyle}
+If\ChangedAt{v3.20}{\Package{tocbasic}} the \Option{tocentrystyle}
option is not used, the \PValue{default} style will be used if required. For
information about this style, see \autoref{sec:tocbasic.tocstyle}. If you do
not want to define a command for entries to the content list, you can use an
empty argument, i.\,e. \OptionValue{tocentrystyle}{} or
\OptionValue{tocentrystyle}{\PParameter{}}.
-Depending\ChangedAt[2015/12]{v3.20}{\Package{tocbasic}}%
-\ChangedAt[2016/06]{v3.21}{\Package{tocbasic}} on the style of the entries to
+Depending\ChangedAt{v3.20}{\Package{tocbasic}}%
+\ChangedAt{v3.21}{\Package{tocbasic}} on the style of the entries to
the content list, you can set all valid attributes of the selected style as
part of the \PName{options}. To do so, you must add the prefix
\PValue{tocentry} to the names of the attributes given in
@@ -2167,6 +2305,10 @@ the styles.%
The \PName{commands} will be executed at the end of the floating or
non-floating environment.%
}%
+ \entry{\OptionVName{category}{string}}{%
+ \ChangedAt{v3.27}{\Package{tocbasic}}%
+ This option can be used as a synonym for \OptionVName{owner}{string}.%
+ }%
\entry{\OptionVName{counterwithin}{\LaTeX{} counter}}{%
If you define a new floating or non-floating environment, a new counter
\Counter{\PName{type}} will be created as well (see option
@@ -2201,8 +2343,8 @@ the styles.%
before.%
}%
\entry{\OptionVName{hang}{length}}{%
- \ChangedAt[2015/12]{v3.20}{\Package{tocbasic}}%
- \ChangedAt[2015/12]{v3.21}{\Package{tocbasic}}%
+ \ChangedAt{v3.20}{\Package{tocbasic}}%
+ \ChangedAt{v3.21}{\Package{tocbasic}}%
This option has been deprecated since \KOMAScript~3.20. Instead, the
amount of the hanging indent of entries to the content list\index{content
list>entry} depends on attributes of the TOC-entry style given by the
@@ -2214,8 +2356,8 @@ the styles.%
example, use \OptionValue{tocentrynumwidth}{2.3em}.%
}%
\entry{\OptionVName{indent}{length}}{%
- \ChangedAt[2015/12]{v3.20}{\Package{tocbasic}}%
- \ChangedAt[2015/12]{v3.21}{\Package{tocbasic}}%
+ \ChangedAt{v3.20}{\Package{tocbasic}}%
+ \ChangedAt{v3.21}{\Package{tocbasic}}%
This option has been deprecated since \KOMAScript~3.20. Instead, the
amount that entries to the content list\index{content list>entry} are
indented depends on attributes of the TOC-entry style given by the
@@ -2227,8 +2369,8 @@ the styles.%
use \OptionValue{tocentrynumwidth}{1.5em}.%
}%
\entry{\OptionVName{level}{number}}{%
- \ChangedAt[2015/12]{v3.20}{\Package{tocbasic}}%
- \ChangedAt[2015/12]{v3.21}{\Package{tocbasic}}%
+ \ChangedAt{v3.20}{\Package{tocbasic}}%
+ \ChangedAt{v3.21}{\Package{tocbasic}}%
This option has been deprecated since \KOMAScript~3.20. Instead, the level
of the entries to the content list\index{content list>entry} depends on
attributes of the TOC-entry style given by the \Option{tocentrystyle}
@@ -2289,7 +2431,7 @@ the styles.%
\autopageref{sec:tocbasic.tocstyle}.%
}%
\entry{\OptionVName{tocentry\PName{style-option}}{value}}{%
- \ChangedAt[2015/12]{v3.20}{\Package{tocbasic}}%
+ \ChangedAt{v3.20}{\Package{tocbasic}}%
Additional options depending on the \PName{TOC-entry style} given by
\Option{tocentrystyle}. See \autoref{sec:tocbasic.tocstyle},
\autopageref{sec:tocbasic.tocstyle} for additional information about