Documentation/sphinx/kerneldoc-preamble.sty

   1 % -*- coding: utf-8 -*-
   2 % SPDX-License-Identifier: GPL-2.0
   3 %
   4 % LaTeX preamble for "make latexdocs" or "make pdfdocs" including:
   5 %   - TOC width settings
   6 %   - Setting of tabulary (\tymin)
   7 %   - Headheight setting for fancyhdr
   8 %   - Fontfamily settings for CJK (Chinese, Japanese, and Korean) translations
   9 %
  10 % Note on the suffix of .sty:
  11 %   This is not implemented as a LaTeX style file, but as a file containing
  12 %   plain LaTeX code to be included into preamble.
  13 %   ".sty" is chosen because ".tex" would cause the build scripts to confuse
  14 %   this file with a LaTeX main file.
  15 %
  16 % Copyright (C) 2022  Akira Yokosawa
  17
  18 % Custom width parameters for TOC
  19 %  - Redefine low-level commands defined in report.cls.
  20 %  - Indent of 2 chars is preserved for ease of comparison.
  21 % Summary of changes from default params:
  22 %   Width of page number (\@pnumwidth): 1.55em -> 2.7em
  23 %   Width of chapter number:            1.5em  -> 2.4em
  24 %   Indent of section number:           1.5em  -> 2.4em
  25 %   Width of section number:            2.6em  -> 3.2em
  26 %   Indent of subsection number:        4.1em  -> 5.6em
  27 %   Width of subsection number:         3.5em  -> 4.3em
  28 %
  29 % These params can have 4 digit page counts, 3 digit chapter counts,
  30 % section counts of 4 digits + 1 period (e.g., 18.10), and subsection counts
  31 % of 5 digits + 2 periods (e.g., 18.7.13).
  32 \makeatletter
  33 %% Redefine \@pnumwidth (page number width)
  34 \renewcommand*\@pnumwidth{2.7em}
  35 %% Redefine \l@chapter (chapter list entry)
  36 \renewcommand*\l@chapter[2]{%
  37   \ifnum \c@tocdepth >\m@ne
  38     \addpenalty{-\@highpenalty}%
  39     \vskip 1.0em \@plus\p@
  40     \setlength\@tempdima{2.4em}%
  41     \begingroup
  42       \parindent \z@ \rightskip \@pnumwidth
  43       \parfillskip -\@pnumwidth
  44       \leavevmode \bfseries
  45       \advance\leftskip\@tempdima
  46       \hskip -\leftskip
  47       #1\nobreak\hfil
  48       \nobreak\hb@xt@\@pnumwidth{\hss #2%
  49                                  \kern-\p@\kern\p@}\par
  50       \penalty\@highpenalty
  51     \endgroup
  52   \fi}
  53 %% Redefine \l@section and \l@subsection
  54 \renewcommand*\l@section{\@dottedtocline{1}{2.4em}{3.2em}}
  55 \renewcommand*\l@subsection{\@dottedtocline{2}{5.6em}{4.3em}}
  56 \makeatother
  57 %% Prevent default \sphinxtableofcontentshook from overwriting above tweaks.
  58 \renewcommand{\sphinxtableofcontentshook}{} % Empty the hook
  59
  60 % Prevent column squeezing of tabulary.  \tymin is set by Sphinx as:
  61 %   \setlength{\tymin}{3\fontcharwd\font`0 }
  62 % , which is too short.
  63 \setlength{\tymin}{20em}
  64
  65 % Adjust \headheight for fancyhdr
  66 \addtolength{\headheight}{1.6pt}
  67 \addtolength{\topmargin}{-1.6pt}
  68
  69 % Translations have Asian (CJK) characters which are only displayed if
  70 % xeCJK is used
  71 \usepackage{ifthen}
  72 \newboolean{enablecjk}
  73 \setboolean{enablecjk}{false}
  74 \IfFontExistsTF{Noto Sans CJK SC}{
  75     \IfFileExists{xeCJK.sty}{
  76         \setboolean{enablecjk}{true}
  77     }{}
  78 }{}
  79 \ifthenelse{\boolean{enablecjk}}{
  80     % Load xeCJK when both the Noto Sans CJK font and xeCJK.sty are available.
  81     \usepackage{xeCJK}
  82     % Noto CJK fonts don't provide slant shape. [AutoFakeSlant] permits
  83     % its emulation.
  84     % Select KR variant at the beginning of each document so that quotation
  85     % and apostorph symbols of half-width is used in TOC of Latin documents.
  86     \IfFontExistsTF{Noto Serif CJK KR}{
  87         \setCJKmainfont{Noto Serif CJK KR}[AutoFakeSlant]
  88     }{
  89         \setCJKmainfont{Noto Sans CJK KR}[AutoFakeSlant]
  90     }
  91     \setCJKsansfont{Noto Sans CJK KR}[AutoFakeSlant]
  92     \setCJKmonofont{Noto Sans Mono CJK KR}[AutoFakeSlant]
  93     % Teach xeCJK of half-width symbols
  94     \xeCJKDeclareCharClass{HalfLeft}{`“,`‘}
  95     \xeCJKDeclareCharClass{HalfRight}{`”,`’}
  96     % CJK Language-specific font choices
  97     %% for Simplified Chinese
  98     \IfFontExistsTF{Noto Serif CJK SC}{
  99         \newCJKfontfamily[SCmain]\scmain{Noto Serif CJK SC}[AutoFakeSlant]
 100         \newCJKfontfamily[SCserif]\scserif{Noto Serif CJK SC}[AutoFakeSlant]
 101     }{
 102         \newCJKfontfamily[SCmain]\scmain{Noto Sans CJK SC}[AutoFakeSlant]
 103         \newCJKfontfamily[SCserif]\scserif{Noto Sans CJK SC}[AutoFakeSlant]
 104     }
 105     \newCJKfontfamily[SCsans]\scsans{Noto Sans CJK SC}[AutoFakeSlant]
 106     \newCJKfontfamily[SCmono]\scmono{Noto Sans Mono CJK SC}[AutoFakeSlant]
 107     %% for Traditional Chinese
 108     \IfFontExistsTF{Noto Serif CJK TC}{
 109         \newCJKfontfamily[TCmain]\tcmain{Noto Serif CJK TC}[AutoFakeSlant]
 110         \newCJKfontfamily[TCserif]\tcserif{Noto Serif CJK TC}[AutoFakeSlant]
 111     }{
 112         \newCJKfontfamily[TCmain]\tcmain{Noto Sans CJK TC}[AutoFakeSlant]
 113         \newCJKfontfamily[TCserif]\tcserif{Noto Sans CJK TC}[AutoFakeSlant]
 114     }
 115     \newCJKfontfamily[TCsans]\tcsans{Noto Sans CJK TC}[AutoFakeSlant]
 116     \newCJKfontfamily[TCmono]\tcmono{Noto Sans Mono CJK TC}[AutoFakeSlant]
 117     %% for Korean
 118     \IfFontExistsTF{Noto Serif CJK KR}{
 119         \newCJKfontfamily[KRmain]\krmain{Noto Serif CJK KR}[AutoFakeSlant]
 120         \newCJKfontfamily[KRserif]\krserif{Noto Serif CJK KR}[AutoFakeSlant]
 121     }{
 122         \newCJKfontfamily[KRmain]\krmain{Noto Sans CJK KR}[AutoFakeSlant]
 123         \newCJKfontfamily[KRserif]\krserif{Noto Sans CJK KR}[AutoFakeSlant]
 124     }
 125     \newCJKfontfamily[KRsans]\krsans{Noto Sans CJK KR}[AutoFakeSlant]
 126     \newCJKfontfamily[KRmono]\krmono{Noto Sans Mono CJK KR}[AutoFakeSlant]
 127     %% for Japanese
 128     \IfFontExistsTF{Noto Serif CJK JP}{
 129         \newCJKfontfamily[JPmain]\jpmain{Noto Serif CJK JP}[AutoFakeSlant]
 130         \newCJKfontfamily[JPserif]\jpserif{Noto Serif CJK JP}[AutoFakeSlant]
 131     }{
 132         \newCJKfontfamily[JPmain]\jpmain{Noto Sans CJK JP}[AutoFakeSlant]
 133         \newCJKfontfamily[JPserif]\jpserif{Noto Sans CJK JP}[AutoFakeSlant]
 134     }
 135     \newCJKfontfamily[JPsans]\jpsans{Noto Sans CJK JP}[AutoFakeSlant]
 136     \newCJKfontfamily[JPmono]\jpmono{Noto Sans Mono CJK JP}[AutoFakeSlant]
 137     % Define custom macros to on/off CJK
 138     %% One and half spacing for CJK contents
 139     \newcommand{\kerneldocCJKon}{\makexeCJKactive\onehalfspacing}
 140     \newcommand{\kerneldocCJKoff}{\makexeCJKinactive\singlespacing}
 141     % Define custom macros for switching CJK font setting
 142     %% for Simplified Chinese
 143     \newcommand{\kerneldocBeginSC}{%
 144         \begingroup%
 145         \scmain%
 146         \xeCJKDeclareCharClass{FullLeft}{`“,`‘}% Full-width in SC
 147         \xeCJKDeclareCharClass{FullRight}{`”,`’}% Full-width in SC
 148         \renewcommand{\CJKrmdefault}{SCserif}%
 149         \renewcommand{\CJKsfdefault}{SCsans}%
 150         \renewcommand{\CJKttdefault}{SCmono}%
 151         \xeCJKsetup{CJKspace = false}% gobble white spaces by ' '
 152         % For CJK ascii-art alignment
 153         \setmonofont{Noto Sans Mono CJK SC}[AutoFakeSlant]%
 154     }
 155     \newcommand{\kerneldocEndSC}{\endgroup}
 156     %% for Traditional Chinese
 157     \newcommand{\kerneldocBeginTC}{%
 158         \begingroup%
 159         \tcmain%
 160         \xeCJKDeclareCharClass{FullLeft}{`“,`‘}% Full-width in TC
 161         \xeCJKDeclareCharClass{FullRight}{`”,`’}% Full-width in TC
 162         \renewcommand{\CJKrmdefault}{TCserif}%
 163         \renewcommand{\CJKsfdefault}{TCsans}%
 164         \renewcommand{\CJKttdefault}{TCmono}%
 165         \xeCJKsetup{CJKspace = false}% gobble white spaces by ' '
 166         % For CJK ascii-art alignment
 167         \setmonofont{Noto Sans Mono CJK TC}[AutoFakeSlant]%
 168     }
 169     \newcommand{\kerneldocEndTC}{\endgroup}
 170     %% for Korean
 171     \newcommand{\kerneldocBeginKR}{%
 172         \begingroup%
 173         \krmain%
 174         \renewcommand{\CJKrmdefault}{KRserif}%
 175         \renewcommand{\CJKsfdefault}{KRsans}%
 176         \renewcommand{\CJKttdefault}{KRmono}%
 177         % \xeCJKsetup{CJKspace = true} % true by default
 178         % For CJK ascii-art alignment (still misaligned for Hangul)
 179         \setmonofont{Noto Sans Mono CJK KR}[AutoFakeSlant]%
 180     }
 181     \newcommand{\kerneldocEndKR}{\endgroup}
 182     %% for Japanese
 183     \newcommand{\kerneldocBeginJP}{%
 184         \begingroup%
 185         \jpmain%
 186         \renewcommand{\CJKrmdefault}{JPserif}%
 187         \renewcommand{\CJKsfdefault}{JPsans}%
 188         \renewcommand{\CJKttdefault}{JPmono}%
 189         \xeCJKsetup{CJKspace = false}% gobble white space by ' '
 190         % For CJK ascii-art alignment
 191         \setmonofont{Noto Sans Mono CJK JP}[AutoFakeSlant]%
 192     }
 193     \newcommand{\kerneldocEndJP}{\endgroup}
 194
 195     % Single spacing in literal blocks
 196     \fvset{baselinestretch=1}
 197     % To customize \sphinxtableofcontents
 198     \usepackage{etoolbox}
 199     % Inactivate CJK after tableofcontents
 200     \apptocmd{\sphinxtableofcontents}{\kerneldocCJKoff}{}{}
 201     \xeCJKsetup{CJKspace = true}% For inter-phrase space of Korean TOC
 202 }{ % Don't enable CJK
 203     % Custom macros to on/off CJK and switch CJK fonts (Dummy)
 204     \newcommand{\kerneldocCJKon}{}
 205     \newcommand{\kerneldocCJKoff}{}
 206     %% By defining \kerneldocBegin(SC|TC|KR|JP) as commands with an argument
 207     %% and ignore the argument (#1) in their definitions, whole contents of
 208     %% CJK chapters can be ignored.
 209     \newcommand{\kerneldocBeginSC}[1]{%
 210         %% Put a note on missing CJK fonts or the xecjk package in place of
 211         %% zh_CN translation.
 212         \begin{sphinxadmonition}{note}{Note on missing fonts and a package:}
 213             Translations of Simplified Chinese (zh\_CN), Traditional Chinese
 214             (zh\_TW), Korean (ko\_KR), and Japanese (ja\_JP) were skipped
 215             due to the lack of suitable font families and/or the texlive-xecjk
 216             package.
 217
 218             If you want them, please install ``Noto Sans CJK'' font families
 219             along with the texlive-xecjk package by following instructions from
 220             \sphinxcode{./scripts/sphinx-pre-install}.
 221             Having optional ``Noto Serif CJK'' font families will improve
 222             the looks of those translations.
 223         \end{sphinxadmonition}}
 224     \newcommand{\kerneldocEndSC}{}
 225     \newcommand{\kerneldocBeginTC}[1]{}
 226     \newcommand{\kerneldocEndTC}{}
 227     \newcommand{\kerneldocBeginKR}[1]{}
 228     \newcommand{\kerneldocEndKR}{}
 229     \newcommand{\kerneldocBeginJP}[1]{}
 230     \newcommand{\kerneldocEndJP}{}
 231 }