[PATCH 1/3] docs: pdfdocs: Pull LaTeX preamble part out of conf.py

[PATCH 1/3] docs: pdfdocs: Pull LaTeX preamble part out of conf.py

[Akira Yokosawa]

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 3b4c963243b1 ("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:

  - f7ebe6b76940 ("docs: Activate exCJK only in CJK chapters")
  - 0afd4df0d16a ("docs: pdfdocs: Prevent column squeezing by tabulary")
  - 659653c9e546 ("docs: pdfdocs: Refactor config for CJK document")
  - e291ff6f5a03 ("docs: pdfdocs: Add CJK-language-specific font settings")
  - 7eb368cc319b ("docs: pdfdocs: Choose Serif font as CJK mainfont if possible")
  - 35382965bdd2 ("docs: pdfdocs: Preserve inter-phrase space in Korean translations")
  - 77abc2c230b1 ("docs: pdfdocs: One-half spacing for CJK translations")
  - 788d28a25799 ("docs: pdfdocs: Permit AutoFakeSlant for CJK fonts")
  - 29ac9822358f ("docs: pdfdocs: Teach xeCJK about character classes of quotation marks")
  - 7c5c18bdb656 ("docs: pdfdocs: Fix typo in CJK-language specific font settings")
  - aa872e0647dc ("docs: pdfdocs: Adjust \headheight for fancyhdr")
  - 8716ef413aa5 ("docs: pdfdocs: Tweak width params of TOC")
  - 66939df53948 ("docs: pdfdocs: Switch default CJK font to KR variants")
  - 7b686a2ea1e4 ("docs: pdfdocs: Enable CJKspace in TOC for Korean titles")
  - 5d9158e3c762 ("docs/translations: Skip CJK contents if suitable fonts not found")
  - b774cc46313b ("docs: pdfdocs: Move CJK monospace font setting to main conf.py")

[1]: https://lore.kernel.org/all/87zgmr66cn.fsf@meer.lwn.net/

Suggested-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
Hi Jon,

Pulling LaTeX preamble code out of conf.py becomes a set of three
patches.
1/3 is the essential change, 2/3 and 3/3 are comments and note message
changes.

If you don't like the way I quoted your message, please feel free to
amend/remove it.

If there arises the need to rebase some of the changes listed above,
their hashes need be amended.

        Thanks, Akira
--
 Documentation/conf.py                       | 184 ++------------------
 Documentation/sphinx/kerneldoc-preamble.sty | 184 ++++++++++++++++++++
 2 files changed, 197 insertions(+), 171 deletions(-)
 create mode 100644 Documentation/sphinx/kerneldoc-preamble.sty

diff --git a/Documentation/conf.py b/Documentation/conf.py
index fb8f69fc4d38..072ee31a301d 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -409,188 +409,25 @@ 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
         \\usepackage{fontspec}
         \\setsansfont{DejaVu Sans}
         \\setromanfont{DejaVu Serif}
         \\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
 if major == 1:
     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
 # by using:
 #	\definecolor{sphinxnoteBgColor}{RGB}{204,255,255}
@@ -652,6 +489,11 @@ for fn in os.listdir('.'):
 # If false, no module index is generated.
 #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 ---------------------------------------
 
diff --git a/Documentation/sphinx/kerneldoc-preamble.sty b/Documentation/sphinx/kerneldoc-preamble.sty
new file mode 100644
index 000000000000..4e56ccea1dbd
--- /dev/null
+++ b/Documentation/sphinx/kerneldoc-preamble.sty
@@ -0,0 +1,184 @@
+% -*- 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}{}
+}

base-commit: b62ef3a1cca0553613adce16515f3640400725b4
-- 
2.17.1

[PATCH 2/3] docs: kerneldoc-preamble.sty: Expand comments in LaTeX code

[Akira Yokosawa]

Expand comments in LaTeX code and mention some of important points
told in changelogs of conf.py changes.
Hopefully they can help future contributors in this area.

No code change involved.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/sphinx/kerneldoc-preamble.sty | 61 ++++++++++++++++-----
 1 file changed, 48 insertions(+), 13 deletions(-)

diff --git a/Documentation/sphinx/kerneldoc-preamble.sty b/Documentation/sphinx/kerneldoc-preamble.sty
index 4e56ccea1dbd..5e59900e994d 100644
--- a/Documentation/sphinx/kerneldoc-preamble.sty
+++ b/Documentation/sphinx/kerneldoc-preamble.sty
@@ -15,8 +15,20 @@
 %
 % Copyright (C) 2022  Akira Yokosawa
 
-% Custom width parameters for TOC --- Redefine low-level commands
-% defined in report.cls
+% Custom width parameters for TOC
+%  - Redefine low-level commands defined in report.cls.
+%  - Indent of 2 chars is preserved for ease of comparison.
+% Summary of changes from default params:
+%   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 sebsection number:        4.1em  -> 5em
+%   Width of subsection number:         3.5em  -> 4.3em
+%
+% These params can have 4 digit page counts, 2 digit chapter counts,
+% section counts of 4 digits + 1 period (e.g., 18.10), and subsection counts
+% of 5 digits + 2 periods (e.g., 18.7.13).
 \makeatletter
 %% Redefine \@pnumwidth (page number width)
 \renewcommand*\@pnumwidth{2.7em}
@@ -46,7 +58,10 @@
 \providecommand{\sphinxtableofcontentshook}{}
 %% Undefine it for compatibility with Sphinx 1.7.9
 \renewcommand{\sphinxtableofcontentshook}{} % Empty the hook
-% Prevent column squeezing of tabulary.
+
+% Prevent column squeezing of tabulary.  \tymin is set by Sphinx as:
+%   \setlength{\tymin}{3\fontcharwd\font`0 }
+% , which is too short.
 \setlength{\tymin}{20em}
 
 % Adjust \headheight for fancyhdr
@@ -56,8 +71,12 @@
 % Translations have Asian (CJK) characters which are only displayed if
 % xeCJK is used
 \IfFontExistsTF{Noto Sans CJK SC}{
-    % This is needed for translations
+    % Load xeCJK when CJK font is available
     \usepackage{xeCJK}
+    % Noto CJK fonts don't provide slant shape. [AutoFakeSlant] permits
+    % its emulation.
+    % Select KR variant at the beginning of each document so that quotation
+    % and apostorph symbols of half-width is used in TOC of Latin documents.
     \IfFontExistsTF{Noto Serif CJK KR}{
 	\setCJKmainfont{Noto Serif CJK KR}[AutoFakeSlant]
     }{
@@ -65,9 +84,11 @@
     }
     \setCJKsansfont{Noto Sans CJK KR}[AutoFakeSlant]
     \setCJKmonofont{Noto Sans Mono CJK KR}[AutoFakeSlant]
+    % Teach xeCJK of half-width symbols
     \xeCJKDeclareCharClass{HalfLeft}{`“,`‘}
     \xeCJKDeclareCharClass{HalfRight}{`”,`’}
     % CJK Language-specific font choices
+    %% for Simplified Chinese
     \IfFontExistsTF{Noto Serif CJK SC}{
 	\newCJKfontfamily[SCmain]\scmain{Noto Serif CJK SC}[AutoFakeSlant]
 	\newCJKfontfamily[SCserif]\scserif{Noto Serif CJK SC}[AutoFakeSlant]
@@ -77,6 +98,7 @@
     }
     \newCJKfontfamily[SCsans]\scsans{Noto Sans CJK SC}[AutoFakeSlant]
     \newCJKfontfamily[SCmono]\scmono{Noto Sans Mono CJK SC}[AutoFakeSlant]
+    %% for Traditional Chinese
     \IfFontExistsTF{Noto Serif CJK TC}{
 	\newCJKfontfamily[TCmain]\tcmain{Noto Serif CJK TC}[AutoFakeSlant]
 	\newCJKfontfamily[TCserif]\tcserif{Noto Serif CJK TC}[AutoFakeSlant]
@@ -86,6 +108,7 @@
     }
     \newCJKfontfamily[TCsans]\tcsans{Noto Sans CJK TC}[AutoFakeSlant]
     \newCJKfontfamily[TCmono]\tcmono{Noto Sans Mono CJK TC}[AutoFakeSlant]
+    %% for Korean
     \IfFontExistsTF{Noto Serif CJK KR}{
 	\newCJKfontfamily[KRmain]\krmain{Noto Serif CJK KR}[AutoFakeSlant]
 	\newCJKfontfamily[KRserif]\krserif{Noto Serif CJK KR}[AutoFakeSlant]
@@ -95,6 +118,7 @@
     }
     \newCJKfontfamily[KRsans]\krsans{Noto Sans CJK KR}[AutoFakeSlant]
     \newCJKfontfamily[KRmono]\krmono{Noto Sans Mono CJK KR}[AutoFakeSlant]
+    %% for Japanese
     \IfFontExistsTF{Noto Serif CJK JP}{
 	\newCJKfontfamily[JPmain]\jpmain{Noto Serif CJK JP}[AutoFakeSlant]
 	\newCJKfontfamily[JPserif]\jpserif{Noto Serif CJK JP}[AutoFakeSlant]
@@ -108,34 +132,39 @@
     \providecommand{\onehalfspacing}{}
     \providecommand{\singlespacing}{}
     % Define custom macros to on/off CJK
+    %% One and half spacing for CJK contents
     \newcommand{\kerneldocCJKon}{\makexeCJKactive\onehalfspacing}
     \newcommand{\kerneldocCJKoff}{\makexeCJKinactive\singlespacing}
+    % Define custom macros for switching CJK font setting
+    %% for Simplified Chinese
     \newcommand{\kerneldocBeginSC}{%
 	\begingroup%
 	\scmain%
-	\xeCJKDeclareCharClass{FullLeft}{`“,`‘}%
-	\xeCJKDeclareCharClass{FullRight}{`”,`’}%
+	\xeCJKDeclareCharClass{FullLeft}{`“,`‘}% Full-width in SC
+	\xeCJKDeclareCharClass{FullRight}{`”,`’}% Full-width in SC
 	\renewcommand{\CJKrmdefault}{SCserif}%
 	\renewcommand{\CJKsfdefault}{SCsans}%
 	\renewcommand{\CJKttdefault}{SCmono}%
-	\xeCJKsetup{CJKspace = false}%
+	\xeCJKsetup{CJKspace = false}% gobble white spaces by ' '
 	% For CJK ascii-art alignment
 	\setmonofont{Noto Sans Mono CJK SC}[AutoFakeSlant]%
     }
     \newcommand{\kerneldocEndSC}{\endgroup}
+    %% for Traditional Chinese
     \newcommand{\kerneldocBeginTC}{%
 	\begingroup%
 	\tcmain%
-	\xeCJKDeclareCharClass{FullLeft}{`“,`‘}%
-	\xeCJKDeclareCharClass{FullRight}{`”,`’}%
+	\xeCJKDeclareCharClass{FullLeft}{`“,`‘}% Full-width in TC
+	\xeCJKDeclareCharClass{FullRight}{`”,`’}% Full-width in TC
 	\renewcommand{\CJKrmdefault}{TCserif}%
 	\renewcommand{\CJKsfdefault}{TCsans}%
 	\renewcommand{\CJKttdefault}{TCmono}%
-	\xeCJKsetup{CJKspace = false}%
+	\xeCJKsetup{CJKspace = false}% gobble white spaces by ' '
 	% For CJK ascii-art alignment
 	\setmonofont{Noto Sans Mono CJK TC}[AutoFakeSlant]%
     }
     \newcommand{\kerneldocEndTC}{\endgroup}
+    %% for Korean
     \newcommand{\kerneldocBeginKR}{%
 	\begingroup%
 	\krmain%
@@ -147,29 +176,35 @@
 	\setmonofont{Noto Sans Mono CJK KR}[AutoFakeSlant]%
     }
     \newcommand{\kerneldocEndKR}{\endgroup}
+    %% for Japanese
     \newcommand{\kerneldocBeginJP}{%
 	\begingroup%
 	\jpmain%
 	\renewcommand{\CJKrmdefault}{JPserif}%
 	\renewcommand{\CJKsfdefault}{JPsans}%
 	\renewcommand{\CJKttdefault}{JPmono}%
-	\xeCJKsetup{CJKspace = false}%
+	\xeCJKsetup{CJKspace = false}% gobble white space by ' '
 	% 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
+    \xeCJKsetup{CJKspace = true}% For inter-phrase space of Korean TOC
 }{ % No CJK font found
-    % Custom macros to on/off CJK (Dummy)
+    % Custom macros to on/off CJK and switch CJK fonts (Dummy)
     \newcommand{\kerneldocCJKon}{}
     \newcommand{\kerneldocCJKoff}{}
+    %% By defining \kerneldocBegin(SC|TC|KR|JP) as commands with an argument
+    %% and ignore the argument (#1) in their definitions, whole contents of
+    %% CJK chapters can be ignored.
     \newcommand{\kerneldocBeginSC}[1]{%
+	%% Put a note on missing CJK fonts in place of zh_CN translation.
 	\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.
-- 
2.17.1

[PATCH 3/3] Reword note on missing CJK fonts

[Akira Yokosawa]

Use past tense as the fonts can be installed after the fact.
Add suggestion to install "Noto Sans CJK" and "Noto Serif CJK"
font families. ("Noto Serif CJK" is optional.)

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
---
This note won't be seen by many, but feedback from a native
speaker would be much appreciated.

To see this note, you need a system without the "Noto Sans CJK"
font.  (Not expecting you'd actually do it.)

    Thanks, Akira
--
 Documentation/sphinx/kerneldoc-preamble.sty | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/Documentation/sphinx/kerneldoc-preamble.sty b/Documentation/sphinx/kerneldoc-preamble.sty
index 5e59900e994d..9d0204dc38be 100644
--- a/Documentation/sphinx/kerneldoc-preamble.sty
+++ b/Documentation/sphinx/kerneldoc-preamble.sty
@@ -205,9 +205,16 @@
     %% CJK chapters can be ignored.
     \newcommand{\kerneldocBeginSC}[1]{%
 	%% Put a note on missing CJK fonts in place of zh_CN translation.
-	\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.
+	\begin{sphinxadmonition}{note}{Note on missing fonts:}
+	    Translations of Simplified Chinese (zh\_CN), Traditional Chinese
+	    (zh\_TW), Korean (ko\_KR), and Japanese (ja\_JP) were skipped
+	    due to the lack of suitable font families.
+
+	    If you want them, please install ``Noto Sans CJK'' font families
+	    by following instructions from
+	    \sphinxcode{./scripts/sphinx-pre-install}.
+	    Having optional ``Noto Serif CJK'' font families will improve
+	    the looks of those translations.
 	\end{sphinxadmonition}}
     \newcommand{\kerneldocEndSC}{}
     \newcommand{\kerneldocBeginTC}[1]{}
-- 
2.17.1

Re: [PATCH 1/3] docs: pdfdocs: Pull LaTeX preamble part out of conf.py

[Jonathan Corbet]

Akira Yokosawa <akiyks@gmail.com> writes:

> 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 3b4c963243b1 ("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.

I've applied the set, thanks.  Still testing the pdfdocs build (and will
be for some time, naturally)

One little note, since you mentioned the need for backslash escapes:

> +# Load kerneldoc specific LaTeX settings
> +latex_elements['preamble'] += '''
> +        % Load kerneldoc specific LaTeX settings
> +	\\input{kerneldoc-preamble.sty}
> +'''

You can avoid that problem in Python code with the use of raw strings:

latex_elements['preamble'] += r'''
       % Load kerneldoc specific LaTeX settings
       \input{kerneldoc-preamble.sty}
'''

(note the "r" on the first line).  Something for future reference.

Thanks,

jon

Re: [PATCH 1/3] docs: pdfdocs: Pull LaTeX preamble part out of conf.py

[Akira Yokosawa]

On Thu, 24 Feb 2022 12:33:25 -0700,
Jonathan Corbet wrote:
> Akira Yokosawa <akiyks@gmail.com> writes:
> 
>> 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 3b4c963243b1 ("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.
> 
> I've applied the set, thanks.  Still testing the pdfdocs build (and will
> be for some time, naturally)
> 
> One little note, since you mentioned the need for backslash escapes:
> 
>> +# Load kerneldoc specific LaTeX settings
>> +latex_elements['preamble'] += '''
>> +        % Load kerneldoc specific LaTeX settings
>> +	\\input{kerneldoc-preamble.sty}
>> +'''
> 
> You can avoid that problem in Python code with the use of raw strings:
> 
> latex_elements['preamble'] += r'''
>        % Load kerneldoc specific LaTeX settings
>        \input{kerneldoc-preamble.sty}
> '''
> 
> (note the "r" on the first line).  Something for future reference.

Thank you for the tip.

It turns out that I unknowingly used a raw string in commit
77abc2c230b1 ("docs: pdfdocs: One-half spacing for CJK translations").

I think I copy-pasted an example from "extrapackages" key documentation.

Now I understand the use of raw string.
I will convert remaining LaTeX code in conf.py to raw string(s)
when I need to edit it in the future.

        Thanks, Akira

> 
> Thanks,
> 
> jon