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