korg/linux
0
0
Fork 0
mirror of https://mirrors.bfsu.edu.cn/git/linux.git synced 2024-11-11 04:18:39 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: pdfdocs: Tweak width params of TOC

Browse Source 
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>
This commit is contained in:
Akira Yokosawa 2022-02-01 08:59:58 +09:00 committed by Jonathan Corbet
parent 4fbe7b19a9
commit 8716ef413a
1 changed files with 31 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
Documentation/conf.py
View File

@ -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