From 398f7abdcb7e2307facebcbdae5639f7d35916cd Mon Sep 17 00:00:00 2001 From: Akira Yokosawa Date: Fri, 18 Feb 2022 23:11:17 +0900 Subject: 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 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 Signed-off-by: Akira Yokosawa Link: https://lore.kernel.org/r/aaa9dca1-27c0-c414-77f3-c5587db0cc5b@gmail.com Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 184 ++++---------------------------------------------- 1 file changed, 13 insertions(+), 171 deletions(-) (limited to 'Documentation/conf.py') 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 --------------------------------------- -- cgit v1.2.3