summaryrefslogtreecommitdiff
path: root/Documentation/conf.py
diff options
context:
space:
mode:
authorAkira Yokosawa <akiyks@gmail.com>2022-02-01 08:59:58 +0900
committerJonathan Corbet <corbet@lwn.net>2022-02-15 16:35:53 -0700
commit8716ef413aa55d9a25481f84eb54f9d571a1f421 (patch)
treed06d8d30f3584d55ee0ed90a0a9ff82cadd4eb9f /Documentation/conf.py
parent4fbe7b19a9485db0a53efc018fe88db25846c89f (diff)
docs: pdfdocs: Tweak width params of TOC
Sphinx has its own set of width parameters of Table of Contents (TOC) for LaTeX defined in its class definition of sphinxmanual.cls. It also inherits parameters for chapter entries from report.cls of original LaTeX base. However, they are optimized assuming small documents with tens of pages and chapters/sections of less than 10. To cope with some of kernel-doc documents with more than 1000 pages and several tens of chapters/sections, definitions of those parameters need to be adjusted. Unfortunately, those parameters are hard coded in the class definitions and need low-level LaTeX coding tricks to redefine. As Sphinx 1.7.9 does not have \sphinxtableofcontentshook, which defines those parameters in later Sphinx versions, for compatibility with both pre-1.8 and later Sphinx versions, empty the hook altogether and redefine \@pnumwidth, \l@chapter, \l@section, and \@subsection commands originally defined in report.cls. Summary of parameter changes: Width of page number (\@pnumwidth): 1.55em -> 2.7em Width of chapter number: 1.5em -> 1.8em Indent of section number: 1.5em -> 1.8em Width of section number: 2.6em -> 3.2em Indent of subsection number: 4.1em -> 5em Width of subsection number: 3.5em -> 4.3em Notes: 1. Parameters for subsection become relevant only when ":maxdepth: 3" is specified under "toctree::" (e.g., RCU/index.rst). They can hold subsection numbers up to 5 digits such as "18.7.13" (in RCU.pdf). 2. Number of chapters in driver-api.pdf is getting closer to 100. When it reaches 100, another set of tweaks will be necessary. 3. The low-level LaTeX trick is mentioned in "Unofficial LaTeX2e reference manual" at: http://latexref.xyz/Table-of-contents-etc_002e.html Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/e52b4718-7909-25be-fbc1-76800aa62ae3@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'Documentation/conf.py')
-rw-r--r--Documentation/conf.py31
1 files changed, 31 insertions, 0 deletions
diff --git a/Documentation/conf.py b/Documentation/conf.py
index f07f2e9b9f2c..e5c13dee2de8 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -409,6 +409,37 @@ latex_elements = {
# Additional stuff for the LaTeX preamble.
'preamble': '''
+ % Custom width parameters for TOC --- Redefine low-level commands
+ % defined in report.cls
+ \\makeatletter
+ %% Redefine \\@pnumwidth (page number width)
+ \\renewcommand*\\@pnumwidth{2.7em}
+ %% Redefine \\l@chapter (chapter list entry)
+ \\renewcommand*\\l@chapter[2]{%
+ \\ifnum \\c@tocdepth >\\m@ne
+ \\addpenalty{-\\@highpenalty}%
+ \\vskip 1.0em \\@plus\\p@
+ \\setlength\\@tempdima{1.8em}%
+ \\begingroup
+ \\parindent \\z@ \\rightskip \\@pnumwidth
+ \\parfillskip -\\@pnumwidth
+ \\leavevmode \\bfseries
+ \\advance\\leftskip\\@tempdima
+ \\hskip -\\leftskip
+ #1\\nobreak\\hfil
+ \\nobreak\\hb@xt@\\@pnumwidth{\\hss #2%
+ \\kern-\\p@\\kern\\p@}\\par
+ \\penalty\\@highpenalty
+ \\endgroup
+ \\fi}
+ %% Redefine \\l@section and \\l@subsection
+ \\renewcommand*\\l@section{\\@dottedtocline{1}{1.8em}{3.2em}}
+ \\renewcommand*\\l@subsection{\\@dottedtocline{2}{5em}{4.3em}}
+ \\makeatother
+ %% Sphinx < 1.8 doesn't have \\sphinxtableofcontentshook
+ \\providecommand{\\sphinxtableofcontentshook}{}
+ %% Undefine it for compatibility with Sphinx 1.7.9
+ \\renewcommand{\\sphinxtableofcontentshook}{} % Empty the hook
% Prevent column squeezing of tabulary.
\\setlength{\\tymin}{20em}
% Use some font with UTF-8 support with XeLaTeX