Commit 398f7abd authored by Akira Yokosawa's avatar Akira Yokosawa Committed by Jonathan Corbet

docs: pdfdocs: Pull LaTeX preamble part out of conf.py

Quote from Jon's remark [1]:

    I do notice that Documentation/conf.py is getting large and
    unapproachable.  At some future point, it might be nice to pull
    all of the latex stuff out into a separate file where it won't
    scare people who stumble into it by accident.

Pull LaTeX preamble settings added since commit 3b4c9632 ("docs:
conf.py: adjust the LaTeX document output") out into
sphinx/kerneldoc-preamble.sty.

It will be copied to the build directory by the added
"latex_additional_files" setting in conf.py.

As a bonus, LaTeX/TeX code can be maintained without escaping backslashes.

To compensate the loss of change history in sphinx/kerneldoc-preamble.sty,
here is a list of changes made in conf.py:

  - f7ebe6b7 ("docs: Activate exCJK only in CJK chapters")
  - 0afd4df0 ("docs: pdfdocs: Prevent column squeezing by tabulary")
  - 659653c9 ("docs: pdfdocs: Refactor config for CJK document")
  - e291ff6f ("docs: pdfdocs: Add CJK-language-specific font settings")
  - 7eb368cc ("docs: pdfdocs: Choose Serif font as CJK mainfont if possible")
  - 35382965 ("docs: pdfdocs: Preserve inter-phrase space in Korean translations")
  - 77abc2c2 ("docs: pdfdocs: One-half spacing for CJK translations")
  - 788d28a2 ("docs: pdfdocs: Permit AutoFakeSlant for CJK fonts")
  - 29ac9822 ("docs: pdfdocs: Teach xeCJK about character classes of quotation marks")
  - 7c5c18bd ("docs: pdfdocs: Fix typo in CJK-language specific font settings")
  - aa872e06 ("docs: pdfdocs: Adjust \headheight for fancyhdr")
  - 8716ef41 ("docs: pdfdocs: Tweak width params of TOC")
  - 66939df5 ("docs: pdfdocs: Switch default CJK font to KR variants")
  - 7b686a2e ("docs: pdfdocs: Enable CJKspace in TOC for Korean titles")
  - 5d9158e3 ("docs/translations: Skip CJK contents if suitable fonts not found")
  - b774cc46 ("docs: pdfdocs: Move CJK monospace font setting to main conf.py")

[1]: https://lore.kernel.org/all/87zgmr66cn.fsf@meer.lwn.net/Suggested-by: default avatarJonathan Corbet <corbet@lwn.net>
Signed-off-by: default avatarAkira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/aaa9dca1-27c0-c414-77f3-c5587db0cc5b@gmail.comSigned-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent b089f167
...@@ -409,188 +409,25 @@ latex_elements = { ...@@ -409,188 +409,25 @@ latex_elements = {
# Additional stuff for the LaTeX preamble. # Additional stuff for the LaTeX preamble.
'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 % Use some font with UTF-8 support with XeLaTeX
\\usepackage{fontspec} \\usepackage{fontspec}
\\setsansfont{DejaVu Sans} \\setsansfont{DejaVu Sans}
\\setromanfont{DejaVu Serif} \\setromanfont{DejaVu Serif}
\\setmonofont{DejaVu Sans Mono} \\setmonofont{DejaVu Sans Mono}
% Adjust \\headheight for fancyhdr ''',
\\addtolength{\\headheight}{1.6pt}
\\addtolength{\\topmargin}{-1.6pt}
''',
} }
# Translations have Asian (CJK) characters which are only displayed if
# xeCJK is used
latex_elements['preamble'] += '''
\\IfFontExistsTF{Noto Sans CJK SC}{
% This is needed for translations
\\usepackage{xeCJK}
\\IfFontExistsTF{Noto Serif CJK KR}{
\\setCJKmainfont{Noto Serif CJK KR}[AutoFakeSlant]
}{
\\setCJKmainfont{Noto Sans CJK KR}[AutoFakeSlant]
}
\\setCJKsansfont{Noto Sans CJK KR}[AutoFakeSlant]
\\setCJKmonofont{Noto Sans Mono CJK KR}[AutoFakeSlant]
\\xeCJKDeclareCharClass{HalfLeft}{`“,`‘}
\\xeCJKDeclareCharClass{HalfRight}{`”,`’}
% CJK Language-specific font choices
\\IfFontExistsTF{Noto Serif CJK SC}{
\\newCJKfontfamily[SCmain]\\scmain{Noto Serif CJK SC}[AutoFakeSlant]
\\newCJKfontfamily[SCserif]\\scserif{Noto Serif CJK SC}[AutoFakeSlant]
}{
\\newCJKfontfamily[SCmain]\\scmain{Noto Sans CJK SC}[AutoFakeSlant]
\\newCJKfontfamily[SCserif]\\scserif{Noto Sans CJK SC}[AutoFakeSlant]
}
\\newCJKfontfamily[SCsans]\\scsans{Noto Sans CJK SC}[AutoFakeSlant]
\\newCJKfontfamily[SCmono]\\scmono{Noto Sans Mono CJK SC}[AutoFakeSlant]
\\IfFontExistsTF{Noto Serif CJK TC}{
\\newCJKfontfamily[TCmain]\\tcmain{Noto Serif CJK TC}[AutoFakeSlant]
\\newCJKfontfamily[TCserif]\\tcserif{Noto Serif CJK TC}[AutoFakeSlant]
}{
\\newCJKfontfamily[TCmain]\\tcmain{Noto Sans CJK TC}[AutoFakeSlant]
\\newCJKfontfamily[TCserif]\\tcserif{Noto Sans CJK TC}[AutoFakeSlant]
}
\\newCJKfontfamily[TCsans]\\tcsans{Noto Sans CJK TC}[AutoFakeSlant]
\\newCJKfontfamily[TCmono]\\tcmono{Noto Sans Mono CJK TC}[AutoFakeSlant]
\\IfFontExistsTF{Noto Serif CJK KR}{
\\newCJKfontfamily[KRmain]\\krmain{Noto Serif CJK KR}[AutoFakeSlant]
\\newCJKfontfamily[KRserif]\\krserif{Noto Serif CJK KR}[AutoFakeSlant]
}{
\\newCJKfontfamily[KRmain]\\krmain{Noto Sans CJK KR}[AutoFakeSlant]
\\newCJKfontfamily[KRserif]\\krserif{Noto Sans CJK KR}[AutoFakeSlant]
}
\\newCJKfontfamily[KRsans]\\krsans{Noto Sans CJK KR}[AutoFakeSlant]
\\newCJKfontfamily[KRmono]\\krmono{Noto Sans Mono CJK KR}[AutoFakeSlant]
\\IfFontExistsTF{Noto Serif CJK JP}{
\\newCJKfontfamily[JPmain]\\jpmain{Noto Serif CJK JP}[AutoFakeSlant]
\\newCJKfontfamily[JPserif]\\jpserif{Noto Serif CJK JP}[AutoFakeSlant]
}{
\\newCJKfontfamily[JPmain]\\jpmain{Noto Sans CJK JP}[AutoFakeSlant]
\\newCJKfontfamily[JPserif]\\jpserif{Noto Sans CJK JP}[AutoFakeSlant]
}
\\newCJKfontfamily[JPsans]\\jpsans{Noto Sans CJK JP}[AutoFakeSlant]
\\newCJKfontfamily[JPmono]\\jpmono{Noto Sans Mono CJK JP}[AutoFakeSlant]
% Dummy commands for Sphinx < 2.3 (no 'extrapackages' support)
\\providecommand{\\onehalfspacing}{}
\\providecommand{\\singlespacing}{}
% Define custom macros to on/off CJK
\\newcommand{\\kerneldocCJKon}{\\makexeCJKactive\\onehalfspacing}
\\newcommand{\\kerneldocCJKoff}{\\makexeCJKinactive\\singlespacing}
\\newcommand{\\kerneldocBeginSC}{%
\\begingroup%
\\scmain%
\\xeCJKDeclareCharClass{FullLeft}{`“,`‘}%
\\xeCJKDeclareCharClass{FullRight}{`”,`’}%
\\renewcommand{\\CJKrmdefault}{SCserif}%
\\renewcommand{\\CJKsfdefault}{SCsans}%
\\renewcommand{\\CJKttdefault}{SCmono}%
\\xeCJKsetup{CJKspace = false}%
% For CJK ascii-art alignment
\\setmonofont{Noto Sans Mono CJK SC}[AutoFakeSlant]%
}
\\newcommand{\\kerneldocEndSC}{\\endgroup}
\\newcommand{\\kerneldocBeginTC}{%
\\begingroup%
\\tcmain%
\\xeCJKDeclareCharClass{FullLeft}{`“,`‘}%
\\xeCJKDeclareCharClass{FullRight}{`”,`’}%
\\renewcommand{\\CJKrmdefault}{TCserif}%
\\renewcommand{\\CJKsfdefault}{TCsans}%
\\renewcommand{\\CJKttdefault}{TCmono}%
\\xeCJKsetup{CJKspace = false}%
% For CJK ascii-art alignment
\\setmonofont{Noto Sans Mono CJK TC}[AutoFakeSlant]%
}
\\newcommand{\\kerneldocEndTC}{\\endgroup}
\\newcommand{\\kerneldocBeginKR}{%
\\begingroup%
\\krmain%
\\renewcommand{\\CJKrmdefault}{KRserif}%
\\renewcommand{\\CJKsfdefault}{KRsans}%
\\renewcommand{\\CJKttdefault}{KRmono}%
% \\xeCJKsetup{CJKspace = true} % true by default
% For CJK ascii-art alignment (still misaligned for Hangul)
\\setmonofont{Noto Sans Mono CJK KR}[AutoFakeSlant]%
}
\\newcommand{\\kerneldocEndKR}{\\endgroup}
\\newcommand{\\kerneldocBeginJP}{%
\\begingroup%
\\jpmain%
\\renewcommand{\\CJKrmdefault}{JPserif}%
\\renewcommand{\\CJKsfdefault}{JPsans}%
\\renewcommand{\\CJKttdefault}{JPmono}%
\\xeCJKsetup{CJKspace = false}%
% For CJK ascii-art alignment
\\setmonofont{Noto Sans Mono CJK JP}[AutoFakeSlant]%
}
\\newcommand{\\kerneldocEndJP}{\\endgroup}
% Single spacing in literal blocks
\\fvset{baselinestretch=1}
% To customize \\sphinxtableofcontents
\\usepackage{etoolbox}
% Inactivate CJK after tableofcontents
\\apptocmd{\\sphinxtableofcontents}{\\kerneldocCJKoff}{}{}
\\xeCJKsetup{CJKspace = true} % For inter-phrase space of Korean TOC
}{ % No CJK font found
% Custom macros to on/off CJK (Dummy)
\\newcommand{\\kerneldocCJKon}{}
\\newcommand{\\kerneldocCJKoff}{}
\\newcommand{\\kerneldocBeginSC}[1]{%
\\begin{sphinxadmonition}{note}{Note:}
``Noto Sans CJK'' fonts are not found while building this PDF\\@.
Translations of zh\\_CN, zh\\_TW, ko\\_KR, and ja\\_JP are
skipped.
\\end{sphinxadmonition}}
\\newcommand{\\kerneldocEndSC}{}
\\newcommand{\\kerneldocBeginTC}[1]{}
\\newcommand{\\kerneldocEndTC}{}
\\newcommand{\\kerneldocBeginKR}[1]{}
\\newcommand{\\kerneldocEndKR}{}
\\newcommand{\\kerneldocBeginJP}[1]{}
\\newcommand{\\kerneldocEndJP}{}
}
'''
# Fix reference escape troubles with Sphinx 1.4.x # Fix reference escape troubles with Sphinx 1.4.x
if major == 1: if major == 1:
latex_elements['preamble'] += '\\renewcommand*{\\DUrole}[2]{ #2 }\n' latex_elements['preamble'] += '\\renewcommand*{\\DUrole}[2]{ #2 }\n'
# Load kerneldoc specific LaTeX settings
latex_elements['preamble'] += '''
% Load kerneldoc specific LaTeX settings
\\input{kerneldoc-preamble.sty}
'''
# With Sphinx 1.6, it is possible to change the Bg color directly # With Sphinx 1.6, it is possible to change the Bg color directly
# by using: # by using:
# \definecolor{sphinxnoteBgColor}{RGB}{204,255,255} # \definecolor{sphinxnoteBgColor}{RGB}{204,255,255}
...@@ -652,6 +489,11 @@ for fn in os.listdir('.'): ...@@ -652,6 +489,11 @@ for fn in os.listdir('.'):
# If false, no module index is generated. # If false, no module index is generated.
#latex_domain_indices = True #latex_domain_indices = True
# Additional LaTeX stuff to be copied to build directory
latex_additional_files = [
'sphinx/kerneldoc-preamble.sty',
]
# -- Options for manual page output --------------------------------------- # -- Options for manual page output ---------------------------------------
......
% -*- coding: utf-8 -*-
% SPDX-License-Identifier: GPL-2.0
%
% LaTeX preamble for "make latexdocs" or "make pdfdocs" including:
% - TOC width settings
% - Setting of tabulary (\tymin)
% - Headheight setting for fancyhdr
% - Fontfamily settings for CJK (Chinese, Japanese, and Korean) translations
%
% Note on the suffix of .sty:
% This is not implemented as a LaTeX style file, but as a file containing
% plain LaTeX code to be included into preamble.
% ".sty" is chosen because ".tex" would cause the build scripts to confuse
% this file with a LaTeX main file.
%
% Copyright (C) 2022 Akira Yokosawa
% 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}
% Adjust \headheight for fancyhdr
\addtolength{\headheight}{1.6pt}
\addtolength{\topmargin}{-1.6pt}
% Translations have Asian (CJK) characters which are only displayed if
% xeCJK is used
\IfFontExistsTF{Noto Sans CJK SC}{
% This is needed for translations
\usepackage{xeCJK}
\IfFontExistsTF{Noto Serif CJK KR}{
\setCJKmainfont{Noto Serif CJK KR}[AutoFakeSlant]
}{
\setCJKmainfont{Noto Sans CJK KR}[AutoFakeSlant]
}
\setCJKsansfont{Noto Sans CJK KR}[AutoFakeSlant]
\setCJKmonofont{Noto Sans Mono CJK KR}[AutoFakeSlant]
\xeCJKDeclareCharClass{HalfLeft}{`“,`‘}
\xeCJKDeclareCharClass{HalfRight}{`”,`’}
% CJK Language-specific font choices
\IfFontExistsTF{Noto Serif CJK SC}{
\newCJKfontfamily[SCmain]\scmain{Noto Serif CJK SC}[AutoFakeSlant]
\newCJKfontfamily[SCserif]\scserif{Noto Serif CJK SC}[AutoFakeSlant]
}{
\newCJKfontfamily[SCmain]\scmain{Noto Sans CJK SC}[AutoFakeSlant]
\newCJKfontfamily[SCserif]\scserif{Noto Sans CJK SC}[AutoFakeSlant]
}
\newCJKfontfamily[SCsans]\scsans{Noto Sans CJK SC}[AutoFakeSlant]
\newCJKfontfamily[SCmono]\scmono{Noto Sans Mono CJK SC}[AutoFakeSlant]
\IfFontExistsTF{Noto Serif CJK TC}{
\newCJKfontfamily[TCmain]\tcmain{Noto Serif CJK TC}[AutoFakeSlant]
\newCJKfontfamily[TCserif]\tcserif{Noto Serif CJK TC}[AutoFakeSlant]
}{
\newCJKfontfamily[TCmain]\tcmain{Noto Sans CJK TC}[AutoFakeSlant]
\newCJKfontfamily[TCserif]\tcserif{Noto Sans CJK TC}[AutoFakeSlant]
}
\newCJKfontfamily[TCsans]\tcsans{Noto Sans CJK TC}[AutoFakeSlant]
\newCJKfontfamily[TCmono]\tcmono{Noto Sans Mono CJK TC}[AutoFakeSlant]
\IfFontExistsTF{Noto Serif CJK KR}{
\newCJKfontfamily[KRmain]\krmain{Noto Serif CJK KR}[AutoFakeSlant]
\newCJKfontfamily[KRserif]\krserif{Noto Serif CJK KR}[AutoFakeSlant]
}{
\newCJKfontfamily[KRmain]\krmain{Noto Sans CJK KR}[AutoFakeSlant]
\newCJKfontfamily[KRserif]\krserif{Noto Sans CJK KR}[AutoFakeSlant]
}
\newCJKfontfamily[KRsans]\krsans{Noto Sans CJK KR}[AutoFakeSlant]
\newCJKfontfamily[KRmono]\krmono{Noto Sans Mono CJK KR}[AutoFakeSlant]
\IfFontExistsTF{Noto Serif CJK JP}{
\newCJKfontfamily[JPmain]\jpmain{Noto Serif CJK JP}[AutoFakeSlant]
\newCJKfontfamily[JPserif]\jpserif{Noto Serif CJK JP}[AutoFakeSlant]
}{
\newCJKfontfamily[JPmain]\jpmain{Noto Sans CJK JP}[AutoFakeSlant]
\newCJKfontfamily[JPserif]\jpserif{Noto Sans CJK JP}[AutoFakeSlant]
}
\newCJKfontfamily[JPsans]\jpsans{Noto Sans CJK JP}[AutoFakeSlant]
\newCJKfontfamily[JPmono]\jpmono{Noto Sans Mono CJK JP}[AutoFakeSlant]
% Dummy commands for Sphinx < 2.3 (no 'extrapackages' support)
\providecommand{\onehalfspacing}{}
\providecommand{\singlespacing}{}
% Define custom macros to on/off CJK
\newcommand{\kerneldocCJKon}{\makexeCJKactive\onehalfspacing}
\newcommand{\kerneldocCJKoff}{\makexeCJKinactive\singlespacing}
\newcommand{\kerneldocBeginSC}{%
\begingroup%
\scmain%
\xeCJKDeclareCharClass{FullLeft}{`“,`‘}%
\xeCJKDeclareCharClass{FullRight}{`”,`’}%
\renewcommand{\CJKrmdefault}{SCserif}%
\renewcommand{\CJKsfdefault}{SCsans}%
\renewcommand{\CJKttdefault}{SCmono}%
\xeCJKsetup{CJKspace = false}%
% For CJK ascii-art alignment
\setmonofont{Noto Sans Mono CJK SC}[AutoFakeSlant]%
}
\newcommand{\kerneldocEndSC}{\endgroup}
\newcommand{\kerneldocBeginTC}{%
\begingroup%
\tcmain%
\xeCJKDeclareCharClass{FullLeft}{`“,`‘}%
\xeCJKDeclareCharClass{FullRight}{`”,`’}%
\renewcommand{\CJKrmdefault}{TCserif}%
\renewcommand{\CJKsfdefault}{TCsans}%
\renewcommand{\CJKttdefault}{TCmono}%
\xeCJKsetup{CJKspace = false}%
% For CJK ascii-art alignment
\setmonofont{Noto Sans Mono CJK TC}[AutoFakeSlant]%
}
\newcommand{\kerneldocEndTC}{\endgroup}
\newcommand{\kerneldocBeginKR}{%
\begingroup%
\krmain%
\renewcommand{\CJKrmdefault}{KRserif}%
\renewcommand{\CJKsfdefault}{KRsans}%
\renewcommand{\CJKttdefault}{KRmono}%
% \xeCJKsetup{CJKspace = true} % true by default
% For CJK ascii-art alignment (still misaligned for Hangul)
\setmonofont{Noto Sans Mono CJK KR}[AutoFakeSlant]%
}
\newcommand{\kerneldocEndKR}{\endgroup}
\newcommand{\kerneldocBeginJP}{%
\begingroup%
\jpmain%
\renewcommand{\CJKrmdefault}{JPserif}%
\renewcommand{\CJKsfdefault}{JPsans}%
\renewcommand{\CJKttdefault}{JPmono}%
\xeCJKsetup{CJKspace = false}%
% For CJK ascii-art alignment
\setmonofont{Noto Sans Mono CJK JP}[AutoFakeSlant]%
}
\newcommand{\kerneldocEndJP}{\endgroup}
% Single spacing in literal blocks
\fvset{baselinestretch=1}
% To customize \sphinxtableofcontents
\usepackage{etoolbox}
% Inactivate CJK after tableofcontents
\apptocmd{\sphinxtableofcontents}{\kerneldocCJKoff}{}{}
\xeCJKsetup{CJKspace = true} % For inter-phrase space of Korean TOC
}{ % No CJK font found
% Custom macros to on/off CJK (Dummy)
\newcommand{\kerneldocCJKon}{}
\newcommand{\kerneldocCJKoff}{}
\newcommand{\kerneldocBeginSC}[1]{%
\begin{sphinxadmonition}{note}{Note:}
``Noto Sans CJK'' fonts are not found while building this PDF\@.
Translations of zh\_CN, zh\_TW, ko\_KR, and ja\_JP are skipped.
\end{sphinxadmonition}}
\newcommand{\kerneldocEndSC}{}
\newcommand{\kerneldocBeginTC}[1]{}
\newcommand{\kerneldocEndTC}{}
\newcommand{\kerneldocBeginKR}[1]{}
\newcommand{\kerneldocEndKR}{}
\newcommand{\kerneldocBeginJP}[1]{}
\newcommand{\kerneldocEndJP}{}
}
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment