diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/etoc/README.md |
Initial commit
Diffstat (limited to 'macros/latex/contrib/etoc/README.md')
-rw-r--r-- | macros/latex/contrib/etoc/README.md | 248 |
1 files changed, 248 insertions, 0 deletions
diff --git a/macros/latex/contrib/etoc/README.md b/macros/latex/contrib/etoc/README.md new file mode 100644 index 0000000000..88f2d05bf8 --- /dev/null +++ b/macros/latex/contrib/etoc/README.md @@ -0,0 +1,248 @@ +<!-- --> + + Source: etoc.dtx (v1.09-2019/03/09) + Author: Jean-Francois Burnol + Author: Christine Roemer et al. (German tranlation) + Info: Completely customisable TOCs + License: LPPL 1.3c + Copyright (C) 2012-2019 Jean-Francois Burnol. + Copyright (C) 2014-2019 Christine Roemer and collaborators for + the translation into German of the documentation. + <jfbu at free dot fr> <Christine_Roemer at t-online dot de> + +ABSTRACT +======== + +The etoc package gives to the user complete control on how the entries +of the table of contents should be constituted from the *name*, +*number*, and *page number* of each sectioning unit. This goes via the +definition of *line styles* for each sectioning level used in the +document. The package provides its own custom line styles. Simpler +ones are given as examples in the documentation. The simplest usage +will be to take advantage of the layout facilities of packages dealing +with list environments. + +Regarding the *global toc display*, etoc provides pre-defined styles +based on a multi-column format, with, optionally, a ruled title or +framed contents. + +The `\tableofcontents` command may be used arbitrarily many times and +it has a variant `\localtableofcontents` which prints tables of +contents 'local' to the current surrounding document unit. An +extension of the `\label/\ref` syntax allows to reproduce (with +another layout) a local table of contents defined somewhere else in +the document. + +Via *depth tags*, one gets an even finer control for each table of +contents of which sectioning units it should, or not, display. + +The formatting inherited (and possibly customized by other packages) +from the document class will be used when in compatibility mode. + +The assignment of levels to the sectioning units can be changed at any +time, and etoc can thus be used in a quite general manner to create +custom ''lists of'', additionally to the tables of contents related to +the document sectioning units. No auxiliary file is used additionally +to the standard `.toc` file. + +INSTALLATION +============ + +The simplest is to download + +> <http://mirrors.ctan.org/install/macros/latex/contrib/etoc.tds.zip> + +and then run `unzip etoc.tds.zip -d <DEST>` where `<DEST>` is a +TDS-compliant repertory. + +Else, to extract the package (.sty) and driver (.tex) files from etoc.dtx: + +- if etoc.ins is present: etex etoc.ins +- without etoc.ins: etex etoc.dtx + +It is also possible to run latex or pdflatex directly on etoc.dtx. + +To produce etoc.pdf one can run pdflatex (thrice) directly on etoc.dtx or on +the file etoc.tex which was extracted from previous step. + +Options can be set in etoc.tex: + +- scrdoc class options (paper size, font size, ...) +- with or without source code, +- with dvipdfmx or with latex+dvips or pdflatex. + +Since release 1.08h pdflatex is the default in etoc.tex (prior it +was latex+dvipdfmx as it produces smaller PDFs) in order to allow +inclusion via the use of package `attachfile` of about 25 code +samples as file attachment annotations. + +Installation: + + etoc.sty -> TDS:tex/latex/etoc/etoc.sty + etoc.dtx -> TDS:source/latex/etoc/etoc.dtx + etoc.pdf -> TDS:doc/latex/etoc/etoc.pdf + etoc-DE.pdf -> TDS:doc/latex/etoc/etoc-DE.pdf + README.md -> TDS:doc/latex/etoc/README.md + +The other files may be discarded. + +LICENSE +======= + +This Work may be distributed and/or modified under the +conditions of the LaTeX Project Public License, in its +version 1.3c. This version of this license is in + +> <http://www.latex-project.org/lppl/lppl-1-3c.txt> + +and the latest version of this license is in + +> <http://www.latex-project.org/lppl.txt> + +and version 1.3 or later is part of all distributions of +LaTeX version 2005/12/01 or later. + +The Authors of this Work are: + +- Jean-Francois Burnol `<jfbu at free dot fr>` for the source code + and English documentation, and +- Christine Roemer `<Christine_Roemer at t-online dot de>` and + collaborators for the translation into German of the documentation. + +This Work consists of the main source file etoc.dtx and the +derived files etoc.sty, etoc.ins, etoc.tex, etoc-DE.tex, +etoc.pdf, etoc-DE.pdf, etoc.dvi, etoc-DE.dvi. + +RECENT CHANGES +============== + +v1.09 \[2019/03/09\] +-------------------- + +New features: `\etoclocaltop`, `\localtableofcontentswithrelativedepth`. +Thanks to Tony Roberts for feature request. + +Note to hackers: internal control sequence `\Etoc@localtop` is gone. + +etoc now requires e-TeX (`\numexpr`, `\unless`). + +v1.08p \[2018/07/04\] +--------------------- + +Fixed bug surfacing in case of `linktoc=page` option of hyperref. +Thanks to Denis Bitouzé for report (cf. +https://github.com/ho-tex/hyperref/issues/65, +https://github.com/dbitouze/yathesis/issues/61). + +v1.08o \[2018/06/15\] +--------------------- + +Fixed bug showing up if an unnumbered TOC entry starts with a brace, +and document uses hyperref. Caused by a typo in a macro name at +previous release. + +v1.08n \[2018/02/23\] +--------------------- + +Refactoring of core macros detecting `\numberline` and its variants. + +v1.08m \[2018/02/07\] +--------------------- + +Fix to `1.08k`'s introduced incompatibility with KOMA-script +and tocbasic's `\nonumberline`. + +v1.08l \[2017/10/23\] +--------------------- + +Workaround an issue with `Emacs/AUCTeX` wrongly reporting about +actually non-existent LaTeX errors, which was triggered by some +strings written (indirectly) to log file by etoc under some +circumstances. + +v1.08k \[2017/09/28\] +--------------------- + +Adds `\etocsetlocaltop.toc`. See corresponding manual section for +details. + +Adds `\etocsavedparttocline`, `\etocsavedchaptertocline`, +`\etocsavedsectiontocline`, ... They can be used in the context of +the technique explained in section "Another compatibility mode". + +Formerly, etoc redefined for the duration of the TOC the memoir +macro `\chapternumberline` and its likes to have same meaning as +`\numberline` (of course, not when executed in compatibility mode), +for the sake of extraction of `\etocnumber`. + +New method detects presence of any `\<foo>numberline` macro without +any change to originals; they can thus be used as is when applying +the approach of "Another compatibility mode" section from manual. + +v1.08j \[2017/09/21\] +--------------------- + +Since `1.08a-2015/03/13` `\etocname`, `\etocnumber`, `\etocpage` +contain, if hyperref is present and configured for using +hyperlinks in the TOC, the link destination in already expanded +form. This means one can use them even if the style closes a +group (for example from a `&` in a tabular), if `\etocglobaldefs` +was issued; also one can save their meaning for delayed usage +(with for example `\LetLtxMacro` as they are robust). + +But for some legacy reason `\etoclink`, contrarily to +`\etocthelink`, was handled differently. Now, `\etoclink` also +contains the link destination in already expanded form, and can +thus be used even if the line style issues a `&`, as long as +`\etocglobaldefs` is issued. + +Also, bugs dating back to the early days of the package, but +surfacing only under relatively rare conditions such as usage +of hyperref with its option "linktoc=page" got fixed. + +v1.08i \[2016/09/29\] +--------------------- + +This fixes an issue dating back to `1.08e-2015/04/17`: under +`\etocchecksemptiness` regime, some circumstances (such as adding to +an already compiled document a `\localtableofcontents` before the +main `\tableofcontents`) created an "`Undefined control sequence` +`\Etoc@localtop`" error. Thanks to Denis Bitouzé for reporting the +problem. + +On this occasion, `\etocdoesnotcheckemptiness` has been +added to unset the flag. + +A rather more exotic issue was fixed: the emptiness check for +local tocs could get confused if the `tocdepth` counter was varying +in some specific ways from inside the `toc` file. + +After adding to a document a `\localtableofcontents`, two LaTeX +passes are needed for etoc to get a chance to print the +correct local contents. Formerly, etoc issued a Warning on +the first pass; it now also induces LaTeX into +announcing "There were undefined references", as this is nearer +to the end of the log file and console output. + +v1.08h \[2016/09/25\] +--------------------- + +New functioning of `\etocsetnexttocdepth`: the tocdepth counter is +modified only at the time of the table of contents, not before. This +fixes an issue which arose when `\etocsetnexttocdepth` was used +multiple times with no intervening table of contents. Thanks to +Denis Bitouzé for reporting the problem. + +The PDF documentation includes about 25 LaTeX code snippets also +as file attachment annotations, additionally to their verbatim +typesetting. The ordering of the documentation contents has been +slightly re-organized. + +A previous documentation-only update on 2016/09/09 added a new +section with the (approximate) translation into etoc lingua of the +book class toc style, for easy customizability. + +The latest translation into German of the additions made to the +documentation dates back to v1.08d \[2015/04/09\]. + +Thanks to Christine Römer! |