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 %% Sphinx < 1.8 doesn't have \sphinxtableofcontentshook
  58 \providecommand{\sphinxtableofcontentshook}{}
  59 %% Undefine it for compatibility with Sphinx 1.7.9
  60 \renewcommand{\sphinxtableofcontentshook}{} % Empty the hook
  61
  62 % Prevent column squeezing of tabulary.  \tymin is set by Sphinx as:
  63 %   \setlength{\tymin}{3\fontcharwd\font`0 }
  64 % , which is too short.
  65 \setlength{\tymin}{20em}
  66
  67 % Adjust \headheight for fancyhdr
  68 \addtolength{\headheight}{1.6pt}
  69 \addtolength{\topmargin}{-1.6pt}
  70
  71 % Translations have Asian (CJK) characters which are only displayed if
  72 % xeCJK is used
  73 \IfFontExistsTF{Noto Sans CJK SC}{
  74     % Load xeCJK when CJK font is available
  75     \usepackage{xeCJK}
  76     % Noto CJK fonts don't provide slant shape. [AutoFakeSlant] permits
  77     % its emulation.
  78     % Select KR variant at the beginning of each document so that quotation
  79     % and apostorph symbols of half-width is used in TOC of Latin documents.
  80     \IfFontExistsTF{Noto Serif CJK KR}{
  81         \setCJKmainfont{Noto Serif CJK KR}[AutoFakeSlant]
  82     }{
  83         \setCJKmainfont{Noto Sans CJK KR}[AutoFakeSlant]
  84     }
  85     \setCJKsansfont{Noto Sans CJK KR}[AutoFakeSlant]
  86     \setCJKmonofont{Noto Sans Mono CJK KR}[AutoFakeSlant]
  87     % Teach xeCJK of half-width symbols
  88     \xeCJKDeclareCharClass{HalfLeft}{`“,`‘}
  89     \xeCJKDeclareCharClass{HalfRight}{`”,`’}
  90     % CJK Language-specific font choices
  91     %% for Simplified Chinese
  92     \IfFontExistsTF{Noto Serif CJK SC}{
  93         \newCJKfontfamily[SCmain]\scmain{Noto Serif CJK SC}[AutoFakeSlant]
  94         \newCJKfontfamily[SCserif]\scserif{Noto Serif CJK SC}[AutoFakeSlant]
  95     }{
  96         \newCJKfontfamily[SCmain]\scmain{Noto Sans CJK SC}[AutoFakeSlant]
  97         \newCJKfontfamily[SCserif]\scserif{Noto Sans CJK SC}[AutoFakeSlant]
  98     }
  99     \newCJKfontfamily[SCsans]\scsans{Noto Sans CJK SC}[AutoFakeSlant]
 100     \newCJKfontfamily[SCmono]\scmono{Noto Sans Mono CJK SC}[AutoFakeSlant]
 101     %% for Traditional Chinese
 102     \IfFontExistsTF{Noto Serif CJK TC}{
 103         \newCJKfontfamily[TCmain]\tcmain{Noto Serif CJK TC}[AutoFakeSlant]
 104         \newCJKfontfamily[TCserif]\tcserif{Noto Serif CJK TC}[AutoFakeSlant]
 105     }{
 106         \newCJKfontfamily[TCmain]\tcmain{Noto Sans CJK TC}[AutoFakeSlant]
 107         \newCJKfontfamily[TCserif]\tcserif{Noto Sans CJK TC}[AutoFakeSlant]
 108     }
 109     \newCJKfontfamily[TCsans]\tcsans{Noto Sans CJK TC}[AutoFakeSlant]
 110     \newCJKfontfamily[TCmono]\tcmono{Noto Sans Mono CJK TC}[AutoFakeSlant]
 111     %% for Korean
 112     \IfFontExistsTF{Noto Serif CJK KR}{
 113         \newCJKfontfamily[KRmain]\krmain{Noto Serif CJK KR}[AutoFakeSlant]
 114         \newCJKfontfamily[KRserif]\krserif{Noto Serif CJK KR}[AutoFakeSlant]
 115     }{
 116         \newCJKfontfamily[KRmain]\krmain{Noto Sans CJK KR}[AutoFakeSlant]
 117         \newCJKfontfamily[KRserif]\krserif{Noto Sans CJK KR}[AutoFakeSlant]
 118     }
 119     \newCJKfontfamily[KRsans]\krsans{Noto Sans CJK KR}[AutoFakeSlant]
 120     \newCJKfontfamily[KRmono]\krmono{Noto Sans Mono CJK KR}[AutoFakeSlant]
 121     %% for Japanese
 122     \IfFontExistsTF{Noto Serif CJK JP}{
 123         \newCJKfontfamily[JPmain]\jpmain{Noto Serif CJK JP}[AutoFakeSlant]
 124         \newCJKfontfamily[JPserif]\jpserif{Noto Serif CJK JP}[AutoFakeSlant]
 125     }{
 126         \newCJKfontfamily[JPmain]\jpmain{Noto Sans CJK JP}[AutoFakeSlant]
 127         \newCJKfontfamily[JPserif]\jpserif{Noto Sans CJK JP}[AutoFakeSlant]
 128     }
 129     \newCJKfontfamily[JPsans]\jpsans{Noto Sans CJK JP}[AutoFakeSlant]
 130     \newCJKfontfamily[JPmono]\jpmono{Noto Sans Mono CJK JP}[AutoFakeSlant]
 131     % Dummy commands for Sphinx < 2.3 (no 'extrapackages' support)
 132     \providecommand{\onehalfspacing}{}
 133     \providecommand{\singlespacing}{}
 134     % Define custom macros to on/off CJK
 135     %% One and half spacing for CJK contents
 136     \newcommand{\kerneldocCJKon}{\makexeCJKactive\onehalfspacing}
 137     \newcommand{\kerneldocCJKoff}{\makexeCJKinactive\singlespacing}
 138     % Define custom macros for switching CJK font setting
 139     %% for Simplified Chinese
 140     \newcommand{\kerneldocBeginSC}{%
 141         \begingroup%
 142         \scmain%
 143         \xeCJKDeclareCharClass{FullLeft}{`“,`‘}% Full-width in SC
 144         \xeCJKDeclareCharClass{FullRight}{`”,`’}% Full-width in SC
 145         \renewcommand{\CJKrmdefault}{SCserif}%
 146         \renewcommand{\CJKsfdefault}{SCsans}%
 147         \renewcommand{\CJKttdefault}{SCmono}%
 148         \xeCJKsetup{CJKspace = false}% gobble white spaces by ' '
 149         % For CJK ascii-art alignment
 150         \setmonofont{Noto Sans Mono CJK SC}[AutoFakeSlant]%
 151     }
 152     \newcommand{\kerneldocEndSC}{\endgroup}
 153     %% for Traditional Chinese
 154     \newcommand{\kerneldocBeginTC}{%
 155         \begingroup%
 156         \tcmain%
 157         \xeCJKDeclareCharClass{FullLeft}{`“,`‘}% Full-width in TC
 158         \xeCJKDeclareCharClass{FullRight}{`”,`’}% Full-width in TC
 159         \renewcommand{\CJKrmdefault}{TCserif}%
 160         \renewcommand{\CJKsfdefault}{TCsans}%
 161         \renewcommand{\CJKttdefault}{TCmono}%
 162         \xeCJKsetup{CJKspace = false}% gobble white spaces by ' '
 163         % For CJK ascii-art alignment
 164         \setmonofont{Noto Sans Mono CJK TC}[AutoFakeSlant]%
 165     }
 166     \newcommand{\kerneldocEndTC}{\endgroup}
 167     %% for Korean
 168     \newcommand{\kerneldocBeginKR}{%
 169         \begingroup%
 170         \krmain%
 171         \renewcommand{\CJKrmdefault}{KRserif}%
 172         \renewcommand{\CJKsfdefault}{KRsans}%
 173         \renewcommand{\CJKttdefault}{KRmono}%
 174         % \xeCJKsetup{CJKspace = true} % true by default
 175         % For CJK ascii-art alignment (still misaligned for Hangul)
 176         \setmonofont{Noto Sans Mono CJK KR}[AutoFakeSlant]%
 177     }
 178     \newcommand{\kerneldocEndKR}{\endgroup}
 179     %% for Japanese
 180     \newcommand{\kerneldocBeginJP}{%
 181         \begingroup%
 182         \jpmain%
 183         \renewcommand{\CJKrmdefault}{JPserif}%
 184         \renewcommand{\CJKsfdefault}{JPsans}%
 185         \renewcommand{\CJKttdefault}{JPmono}%
 186         \xeCJKsetup{CJKspace = false}% gobble white space by ' '
 187         % For CJK ascii-art alignment
 188         \setmonofont{Noto Sans Mono CJK JP}[AutoFakeSlant]%
 189     }
 190     \newcommand{\kerneldocEndJP}{\endgroup}
 191
 192     % Single spacing in literal blocks
 193     \fvset{baselinestretch=1}
 194     % To customize \sphinxtableofcontents
 195     \usepackage{etoolbox}
 196     % Inactivate CJK after tableofcontents
 197     \apptocmd{\sphinxtableofcontents}{\kerneldocCJKoff}{}{}
 198     \xeCJKsetup{CJKspace = true}% For inter-phrase space of Korean TOC
 199 }{ % No CJK font found
 200     % Custom macros to on/off CJK and switch CJK fonts (Dummy)
 201     \newcommand{\kerneldocCJKon}{}
 202     \newcommand{\kerneldocCJKoff}{}
 203     %% By defining \kerneldocBegin(SC|TC|KR|JP) as commands with an argument
 204     %% and ignore the argument (#1) in their definitions, whole contents of
 205     %% CJK chapters can be ignored.
 206     \newcommand{\kerneldocBeginSC}[1]{%
 207         %% Put a note on missing CJK fonts in place of zh_CN translation.
 208         \begin{sphinxadmonition}{note}{Note on missing fonts:}
 209             Translations of Simplified Chinese (zh\_CN), Traditional Chinese
 210             (zh\_TW), Korean (ko\_KR), and Japanese (ja\_JP) were skipped
 211             due to the lack of suitable font families.
 212
 213             If you want them, please install ``Noto Sans CJK'' font families
 214             by following instructions from
 215             \sphinxcode{./scripts/sphinx-pre-install}.
 216             Having optional ``Noto Serif CJK'' font families will improve
 217             the looks of those translations.
 218         \end{sphinxadmonition}}
 219     \newcommand{\kerneldocEndSC}{}
 220     \newcommand{\kerneldocBeginTC}[1]{}
 221     \newcommand{\kerneldocEndTC}{}
 222     \newcommand{\kerneldocBeginKR}[1]{}
 223     \newcommand{\kerneldocEndKR}{}
 224     \newcommand{\kerneldocBeginJP}[1]{}
 225     \newcommand{\kerneldocEndJP}{}
 226 }