Documentation/sphinx/kerneldoc-preamble.sty

0001 % -*- coding: utf-8 -*-
0002 % SPDX-License-Identifier: GPL-2.0
0003 %
0004 % LaTeX preamble for "make latexdocs" or "make pdfdocs" including:
0005 %   - TOC width settings
0006 %   - Setting of tabulary (\tymin)
0007 %   - Headheight setting for fancyhdr
0008 %   - Fontfamily settings for CJK (Chinese, Japanese, and Korean) translations
0009 %
0010 % Note on the suffix of .sty:
0011 %   This is not implemented as a LaTeX style file, but as a file containing
0012 %   plain LaTeX code to be included into preamble.
0013 %   ".sty" is chosen because ".tex" would cause the build scripts to confuse
0014 %   this file with a LaTeX main file.
0015 %
0016 % Copyright (C) 2022  Akira Yokosawa
0017
0018 % Custom width parameters for TOC
0019 %  - Redefine low-level commands defined in report.cls.
0020 %  - Indent of 2 chars is preserved for ease of comparison.
0021 % Summary of changes from default params:
0022 %   Width of page number (\@pnumwidth): 1.55em -> 2.7em
0023 %   Width of chapter number:            1.5em  -> 2.4em
0024 %   Indent of section number:           1.5em  -> 2.4em
0025 %   Width of section number:            2.6em  -> 3.2em
0026 %   Indent of subsection number:        4.1em  -> 5.6em
0027 %   Width of subsection number:         3.5em  -> 4.3em
0028 %
0029 % These params can have 4 digit page counts, 3 digit chapter counts,
0030 % section counts of 4 digits + 1 period (e.g., 18.10), and subsection counts
0031 % of 5 digits + 2 periods (e.g., 18.7.13).
0032 \makeatletter
0033 %% Redefine \@pnumwidth (page number width)
0034 \renewcommand*\@pnumwidth{2.7em}
0035 %% Redefine \l@chapter (chapter list entry)
0036 \renewcommand*\l@chapter[2]{%
0037   \ifnum \c@tocdepth >\m@ne
0038     \addpenalty{-\@highpenalty}%
0039     \vskip 1.0em \@plus\p@
0040     \setlength\@tempdima{2.4em}%
0041     \begingroup
0042       \parindent \z@ \rightskip \@pnumwidth
0043       \parfillskip -\@pnumwidth
0044       \leavevmode \bfseries
0045       \advance\leftskip\@tempdima
0046       \hskip -\leftskip
0047       #1\nobreak\hfil
0048       \nobreak\hb@xt@\@pnumwidth{\hss #2%
0049                                  \kern-\p@\kern\p@}\par
0050       \penalty\@highpenalty
0051     \endgroup
0052   \fi}
0053 %% Redefine \l@section and \l@subsection
0054 \renewcommand*\l@section{\@dottedtocline{1}{2.4em}{3.2em}}
0055 \renewcommand*\l@subsection{\@dottedtocline{2}{5.6em}{4.3em}}
0056 \makeatother
0057 %% Sphinx < 1.8 doesn't have \sphinxtableofcontentshook
0058 \providecommand{\sphinxtableofcontentshook}{}
0059 %% Undefine it for compatibility with Sphinx 1.7.9
0060 \renewcommand{\sphinxtableofcontentshook}{} % Empty the hook
0061
0062 % Prevent column squeezing of tabulary.  \tymin is set by Sphinx as:
0063 %   \setlength{\tymin}{3\fontcharwd\font`0 }
0064 % , which is too short.
0065 \setlength{\tymin}{20em}
0066
0067 % Adjust \headheight for fancyhdr
0068 \addtolength{\headheight}{1.6pt}
0069 \addtolength{\topmargin}{-1.6pt}
0070
0071 % Translations have Asian (CJK) characters which are only displayed if
0072 % xeCJK is used
0073 \usepackage{ifthen}
0074 \newboolean{enablecjk}
0075 \setboolean{enablecjk}{false}
0076 \IfFontExistsTF{Noto Sans CJK SC}{
0077     \IfFileExists{xeCJK.sty}{
0078         \setboolean{enablecjk}{true}
0079     }{}
0080 }{}
0081 \ifthenelse{\boolean{enablecjk}}{
0082     % Load xeCJK when both the Noto Sans CJK font and xeCJK.sty are available.
0083     \usepackage{xeCJK}
0084     % Noto CJK fonts don't provide slant shape. [AutoFakeSlant] permits
0085     % its emulation.
0086     % Select KR variant at the beginning of each document so that quotation
0087     % and apostorph symbols of half-width is used in TOC of Latin documents.
0088     \IfFontExistsTF{Noto Serif CJK KR}{
0089         \setCJKmainfont{Noto Serif CJK KR}[AutoFakeSlant]
0090     }{
0091         \setCJKmainfont{Noto Sans CJK KR}[AutoFakeSlant]
0092     }
0093     \setCJKsansfont{Noto Sans CJK KR}[AutoFakeSlant]
0094     \setCJKmonofont{Noto Sans Mono CJK KR}[AutoFakeSlant]
0095     % Teach xeCJK of half-width symbols
0096     \xeCJKDeclareCharClass{HalfLeft}{`“,`‘}
0097     \xeCJKDeclareCharClass{HalfRight}{`”,`’}
0098     % CJK Language-specific font choices
0099     %% for Simplified Chinese
0100     \IfFontExistsTF{Noto Serif CJK SC}{
0101         \newCJKfontfamily[SCmain]\scmain{Noto Serif CJK SC}[AutoFakeSlant]
0102         \newCJKfontfamily[SCserif]\scserif{Noto Serif CJK SC}[AutoFakeSlant]
0103     }{
0104         \newCJKfontfamily[SCmain]\scmain{Noto Sans CJK SC}[AutoFakeSlant]
0105         \newCJKfontfamily[SCserif]\scserif{Noto Sans CJK SC}[AutoFakeSlant]
0106     }
0107     \newCJKfontfamily[SCsans]\scsans{Noto Sans CJK SC}[AutoFakeSlant]
0108     \newCJKfontfamily[SCmono]\scmono{Noto Sans Mono CJK SC}[AutoFakeSlant]
0109     %% for Traditional Chinese
0110     \IfFontExistsTF{Noto Serif CJK TC}{
0111         \newCJKfontfamily[TCmain]\tcmain{Noto Serif CJK TC}[AutoFakeSlant]
0112         \newCJKfontfamily[TCserif]\tcserif{Noto Serif CJK TC}[AutoFakeSlant]
0113     }{
0114         \newCJKfontfamily[TCmain]\tcmain{Noto Sans CJK TC}[AutoFakeSlant]
0115         \newCJKfontfamily[TCserif]\tcserif{Noto Sans CJK TC}[AutoFakeSlant]
0116     }
0117     \newCJKfontfamily[TCsans]\tcsans{Noto Sans CJK TC}[AutoFakeSlant]
0118     \newCJKfontfamily[TCmono]\tcmono{Noto Sans Mono CJK TC}[AutoFakeSlant]
0119     %% for Korean
0120     \IfFontExistsTF{Noto Serif CJK KR}{
0121         \newCJKfontfamily[KRmain]\krmain{Noto Serif CJK KR}[AutoFakeSlant]
0122         \newCJKfontfamily[KRserif]\krserif{Noto Serif CJK KR}[AutoFakeSlant]
0123     }{
0124         \newCJKfontfamily[KRmain]\krmain{Noto Sans CJK KR}[AutoFakeSlant]
0125         \newCJKfontfamily[KRserif]\krserif{Noto Sans CJK KR}[AutoFakeSlant]
0126     }
0127     \newCJKfontfamily[KRsans]\krsans{Noto Sans CJK KR}[AutoFakeSlant]
0128     \newCJKfontfamily[KRmono]\krmono{Noto Sans Mono CJK KR}[AutoFakeSlant]
0129     %% for Japanese
0130     \IfFontExistsTF{Noto Serif CJK JP}{
0131         \newCJKfontfamily[JPmain]\jpmain{Noto Serif CJK JP}[AutoFakeSlant]
0132         \newCJKfontfamily[JPserif]\jpserif{Noto Serif CJK JP}[AutoFakeSlant]
0133     }{
0134         \newCJKfontfamily[JPmain]\jpmain{Noto Sans CJK JP}[AutoFakeSlant]
0135         \newCJKfontfamily[JPserif]\jpserif{Noto Sans CJK JP}[AutoFakeSlant]
0136     }
0137     \newCJKfontfamily[JPsans]\jpsans{Noto Sans CJK JP}[AutoFakeSlant]
0138     \newCJKfontfamily[JPmono]\jpmono{Noto Sans Mono CJK JP}[AutoFakeSlant]
0139     % Dummy commands for Sphinx < 2.3 (no 'extrapackages' support)
0140     \providecommand{\onehalfspacing}{}
0141     \providecommand{\singlespacing}{}
0142     % Define custom macros to on/off CJK
0143     %% One and half spacing for CJK contents
0144     \newcommand{\kerneldocCJKon}{\makexeCJKactive\onehalfspacing}
0145     \newcommand{\kerneldocCJKoff}{\makexeCJKinactive\singlespacing}
0146     % Define custom macros for switching CJK font setting
0147     %% for Simplified Chinese
0148     \newcommand{\kerneldocBeginSC}{%
0149         \begingroup%
0150         \scmain%
0151         \xeCJKDeclareCharClass{FullLeft}{`“,`‘}% Full-width in SC
0152         \xeCJKDeclareCharClass{FullRight}{`”,`’}% Full-width in SC
0153         \renewcommand{\CJKrmdefault}{SCserif}%
0154         \renewcommand{\CJKsfdefault}{SCsans}%
0155         \renewcommand{\CJKttdefault}{SCmono}%
0156         \xeCJKsetup{CJKspace = false}% gobble white spaces by ' '
0157         % For CJK ascii-art alignment
0158         \setmonofont{Noto Sans Mono CJK SC}[AutoFakeSlant]%
0159     }
0160     \newcommand{\kerneldocEndSC}{\endgroup}
0161     %% for Traditional Chinese
0162     \newcommand{\kerneldocBeginTC}{%
0163         \begingroup%
0164         \tcmain%
0165         \xeCJKDeclareCharClass{FullLeft}{`“,`‘}% Full-width in TC
0166         \xeCJKDeclareCharClass{FullRight}{`”,`’}% Full-width in TC
0167         \renewcommand{\CJKrmdefault}{TCserif}%
0168         \renewcommand{\CJKsfdefault}{TCsans}%
0169         \renewcommand{\CJKttdefault}{TCmono}%
0170         \xeCJKsetup{CJKspace = false}% gobble white spaces by ' '
0171         % For CJK ascii-art alignment
0172         \setmonofont{Noto Sans Mono CJK TC}[AutoFakeSlant]%
0173     }
0174     \newcommand{\kerneldocEndTC}{\endgroup}
0175     %% for Korean
0176     \newcommand{\kerneldocBeginKR}{%
0177         \begingroup%
0178         \krmain%
0179         \renewcommand{\CJKrmdefault}{KRserif}%
0180         \renewcommand{\CJKsfdefault}{KRsans}%
0181         \renewcommand{\CJKttdefault}{KRmono}%
0182         % \xeCJKsetup{CJKspace = true} % true by default
0183         % For CJK ascii-art alignment (still misaligned for Hangul)
0184         \setmonofont{Noto Sans Mono CJK KR}[AutoFakeSlant]%
0185     }
0186     \newcommand{\kerneldocEndKR}{\endgroup}
0187     %% for Japanese
0188     \newcommand{\kerneldocBeginJP}{%
0189         \begingroup%
0190         \jpmain%
0191         \renewcommand{\CJKrmdefault}{JPserif}%
0192         \renewcommand{\CJKsfdefault}{JPsans}%
0193         \renewcommand{\CJKttdefault}{JPmono}%
0194         \xeCJKsetup{CJKspace = false}% gobble white space by ' '
0195         % For CJK ascii-art alignment
0196         \setmonofont{Noto Sans Mono CJK JP}[AutoFakeSlant]%
0197     }
0198     \newcommand{\kerneldocEndJP}{\endgroup}
0199
0200     % Single spacing in literal blocks
0201     \fvset{baselinestretch=1}
0202     % To customize \sphinxtableofcontents
0203     \usepackage{etoolbox}
0204     % Inactivate CJK after tableofcontents
0205     \apptocmd{\sphinxtableofcontents}{\kerneldocCJKoff}{}{}
0206     \xeCJKsetup{CJKspace = true}% For inter-phrase space of Korean TOC
0207 }{ % Don't enable CJK
0208     % Custom macros to on/off CJK and switch CJK fonts (Dummy)
0209     \newcommand{\kerneldocCJKon}{}
0210     \newcommand{\kerneldocCJKoff}{}
0211     %% By defining \kerneldocBegin(SC|TC|KR|JP) as commands with an argument
0212     %% and ignore the argument (#1) in their definitions, whole contents of
0213     %% CJK chapters can be ignored.
0214     \newcommand{\kerneldocBeginSC}[1]{%
0215         %% Put a note on missing CJK fonts or the xecjk package in place of
0216         %% zh_CN translation.
0217         \begin{sphinxadmonition}{note}{Note on missing fonts and a package:}
0218             Translations of Simplified Chinese (zh\_CN), Traditional Chinese
0219             (zh\_TW), Korean (ko\_KR), and Japanese (ja\_JP) were skipped
0220             due to the lack of suitable font families and/or the texlive-xecjk
0221             package.
0222
0223             If you want them, please install ``Noto Sans CJK'' font families
0224             along with the texlive-xecjk package by following instructions from
0225             \sphinxcode{./scripts/sphinx-pre-install}.
0226             Having optional ``Noto Serif CJK'' font families will improve
0227             the looks of those translations.
0228         \end{sphinxadmonition}}
0229     \newcommand{\kerneldocEndSC}{}
0230     \newcommand{\kerneldocBeginTC}[1]{}
0231     \newcommand{\kerneldocEndTC}{}
0232     \newcommand{\kerneldocBeginKR}[1]{}
0233     \newcommand{\kerneldocEndKR}{}
0234     \newcommand{\kerneldocBeginJP}[1]{}
0235     \newcommand{\kerneldocEndJP}{}
0236 }