[PATCH 0/5] docs: pdfdocs: Improve LaTeX preamble (TOC, CJK fonts)

[PATCH 0/5] docs: pdfdocs: Improve LaTeX preamble (TOC, CJK fonts)

[Akira Yokosawa]

Hi,

This is a follow-up series to the CJK font setting patch series [1]
upstreamed in v5.15.

[1]: https://lore.kernel.org/r/39d0fb0f-b248-bca4-2dac-df69e8d697b1@gmail.com

There is still a lot of room for improvement in the layout of PDF docs.

This series resolves issues listed below:

 1. Some of chapter and section counts in Table of Contents (TOC) in
    large PDF docs collide with chapter/section titles, e.g., Chapters 10,
    11, 12, and 13 and Section 10.10 in userspace-api.pdf.
 2. In docs of more than 99 pages, page counts in TOC are not aligned
    properly when maxdepth >= 2 is specified in toctree, e.g., Chapters 10,
    12, and 13 in userspace-api.pdf
 3. In TOC of Latin-script docs, quotation and apostrophe symbols look too
    wide, e.g., Section 2.2 in userspace-api.pdf.
 4. In TOC of translations, Korean chapter titles lose inter-phrase spaces.
 5. On systems without "Noto Sans CJK" fonts, CJK chapters in translations
    results in full of "TOFU" boxes, with a long build time and a large
    log file containing lots of missing-font warnings.
 6. In translations.pdf built by "make pdfdocs", ascii-art diagrams in CJK
    are not aligned properly.

Patch 1/5 resolves issues #1 and #2 by tweaking width parameters for TOC.

Patch 2/5 resolves issue #3 by switching CJK default font to the KR variant,
whose quotation and apostrophe symbols are half width.

Patch 3/5 resolves issue #4 by enabling CJKspace in TOC by default.

Patch 4/5 resolves issue #5 by conditionally skipping CJK contents in
PDF docs.

Patch 5/5 resolves issue #6 by moving font settings under
translations/conf.py to CJK-specific macros in main conf.py

This series is tested against Sphinx versions 1.7.9, 2.4.4, and 4.4.0.
It does not affect HTML docs.

        Thanks, Akira
--
Akira Yokosawa (5):
  docs: pdfdocs: Tweak width params of TOC
  docs: pdfdocs: Switch default CJK font to KR variants
  docs: pdfdocs: Enable CJKspace in TOC for Korean titles
  docs/translations: Skip CJK contents if suitable fonts not found
  docs: pdfdocs: Move CJK monospace font setting to main conf.py

 Documentation/conf.py                      | 81 ++++++++++++++++++----
 Documentation/translations/conf.py         | 12 ----
 Documentation/translations/ja_JP/index.rst |  4 +-
 Documentation/translations/ko_KR/index.rst |  5 +-
 Documentation/translations/zh_CN/index.rst |  4 +-
 Documentation/translations/zh_TW/index.rst |  4 +-
 6 files changed, 75 insertions(+), 35 deletions(-)
 delete mode 100644 Documentation/translations/conf.py


base-commit: 854d0982eef0e424e8108d09d9275aaf445b1597
-- 
2.17.1

[PATCH 1/5] docs: pdfdocs: Tweak width params of TOC

[Akira Yokosawa]

Sphinx has its own set of width parameters of Table of Contents (TOC)
for LaTeX defined in its class definition of sphinxmanual.cls.
It also inherits parameters for chapter entries from report.cls of
original LaTeX base.

However, they are optimized assuming small documents with tens of
pages and chapters/sections of less than 10.

To cope with some of kernel-doc documents with more than 1000
pages and several tens of chapters/sections, definitions of those
parameters need to be adjusted.

Unfortunately, those parameters are hard coded in the class
definitions and need low-level LaTeX coding tricks to redefine.

As Sphinx 1.7.9 does not have \sphinxtableofcontentshook,
which defines those parameters in later Sphinx versions,
for compatibility with both pre-1.8 and later Sphinx versions,
empty the hook altogether and redefine \@pnumwidth, \l@chapter,
\l@section, and \@subsection commands originally defined in
report.cls.

Summary of parameter changes:

  Width of page number (\@pnumwidth): 1.55em  -> 2.7em
  Width of chapter number:  1.5em -> 1.8em
  Indent of section number: 1.5em -> 1.8em
  Width of section number:  2.6em -> 3.2em
  Indent of subsection number: 4.1em -> 5em
  Width of subsection number:  3.5em -> 4.3em

Notes:
1. Parameters for subsection become relevant only when
   ":maxdepth: 3" is specified under "toctree::" (e.g., RCU/index.rst).
   They can hold subsection numbers up to 5 digits such as "18.7.13"
   (in RCU.pdf).

2. Number of chapters in driver-api.pdf is getting closer to 100.
   When it reaches 100, another set of tweaks will be necessary.

3. The low-level LaTeX trick is mentioned in "Unofficial LaTeX2e
   reference manual" at:
        http://latexref.xyz/Table-of-contents-etc_002e.html

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/conf.py | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index f07f2e9b9f2c..e5c13dee2de8 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -409,6 +409,37 @@ 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
-- 
2.17.1

[PATCH 2/5] docs: pdfdocs: Switch default CJK font to KR variants

[Akira Yokosawa]

xeCJK is enabled in Table of Contents (TOC) so that translations.pdf
built by top-level "make pdfdocs" can have its TOC typeset properly.

This causes quotation marks and apostrophe symbols appear too wide in
Latin-script docs.
This is because (1) Sphinx converts ASCII symbols into multi-byte
UTF-8 ones in LaTeX and (2) in the SC variant of "Noto CJK" font
families, those UTF-8 symbols have full-width glyph.

The KR variant of the font families has half-width glyph for those
symbols and TOC pages should look nicer when it is used instead.

Switch the default CJK font families to the KR variant and teach
xeCJK of those symbols' widths.
To compensate the switch, teach xeCJK of the width in the SC and
TC variants.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/conf.py | 23 ++++++++++++++---------
 1 file changed, 14 insertions(+), 9 deletions(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index e5c13dee2de8..e70aa5fd969f 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -460,13 +460,15 @@ latex_elements['preamble']  += '''
     \\IfFontExistsTF{Noto Sans CJK SC}{
 	% This is needed for translations
 	\\usepackage{xeCJK}
-	\\IfFontExistsTF{Noto Serif CJK SC}{
-	    \\setCJKmainfont{Noto Serif CJK SC}[AutoFakeSlant]
+	\\IfFontExistsTF{Noto Serif CJK KR}{
+	    \\setCJKmainfont{Noto Serif CJK KR}[AutoFakeSlant]
 	}{
-	    \\setCJKmainfont{Noto Sans CJK SC}[AutoFakeSlant]
+	    \\setCJKmainfont{Noto Sans CJK KR}[AutoFakeSlant]
 	}
-	\\setCJKsansfont{Noto Sans CJK SC}[AutoFakeSlant]
-	\\setCJKmonofont{Noto Sans Mono CJK SC}[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]
@@ -513,11 +515,18 @@ latex_elements['preamble']  += '''
 	\\newcommand{\\kerneldocBeginSC}{%
 	    \\begingroup%
 	    \\scmain%
+	    \\xeCJKDeclareCharClass{FullLeft}{`“,`‘}%
+	    \\xeCJKDeclareCharClass{FullRight}{`”,`’}%
+	    \\renewcommand{\\CJKrmdefault}{SCserif}%
+	    \\renewcommand{\\CJKsfdefault}{SCsans}%
+	    \\renewcommand{\\CJKttdefault}{SCmono}%
 	}
 	\\newcommand{\\kerneldocEndSC}{\\endgroup}
 	\\newcommand{\\kerneldocBeginTC}{%
 	    \\begingroup%
 	    \\tcmain%
+	    \\xeCJKDeclareCharClass{FullLeft}{`“,`‘}%
+	    \\xeCJKDeclareCharClass{FullRight}{`”,`’}%
 	    \\renewcommand{\\CJKrmdefault}{TCserif}%
 	    \\renewcommand{\\CJKsfdefault}{TCsans}%
 	    \\renewcommand{\\CJKttdefault}{TCmono}%
@@ -525,8 +534,6 @@ latex_elements['preamble']  += '''
 	\\newcommand{\\kerneldocEndTC}{\\endgroup}
 	\\newcommand{\\kerneldocBeginKR}{%
 	    \\begingroup%
-	    \\xeCJKDeclareCharClass{HalfLeft}{`“,`‘}%
-	    \\xeCJKDeclareCharClass{HalfRight}{`”,`’}%
 	    \\krmain%
 	    \\renewcommand{\\CJKrmdefault}{KRserif}%
 	    \\renewcommand{\\CJKsfdefault}{KRsans}%
@@ -536,8 +543,6 @@ latex_elements['preamble']  += '''
 	\\newcommand{\\kerneldocEndKR}{\\endgroup}
 	\\newcommand{\\kerneldocBeginJP}{%
 	    \\begingroup%
-	    \\xeCJKDeclareCharClass{HalfLeft}{`“,`‘}%
-	    \\xeCJKDeclareCharClass{HalfRight}{`”,`’}%
 	    \\jpmain%
 	    \\renewcommand{\\CJKrmdefault}{JPserif}%
 	    \\renewcommand{\\CJKsfdefault}{JPsans}%
-- 
2.17.1

[PATCH 3/5] docs: pdfdocs: Enable CJKspace in TOC for Korean titles

[Akira Yokosawa]

Korean (Hangul) titles in Table of Contents of translations.pdf
don't have inter-phrase spaces.

This is because the CJKspace option of xeCJK is disabled by
default.

Restore the spaces by enabling the option at the beginning of every
document and disable it in the \kerneldocBegin{SC|TC|JP} commands.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/conf.py | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index e70aa5fd969f..ded49b8e9bf6 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -520,6 +520,7 @@ latex_elements['preamble']  += '''
 	    \\renewcommand{\\CJKrmdefault}{SCserif}%
 	    \\renewcommand{\\CJKsfdefault}{SCsans}%
 	    \\renewcommand{\\CJKttdefault}{SCmono}%
+	    \\xeCJKsetup{CJKspace = false}%
 	}
 	\\newcommand{\\kerneldocEndSC}{\\endgroup}
 	\\newcommand{\\kerneldocBeginTC}{%
@@ -530,6 +531,7 @@ latex_elements['preamble']  += '''
 	    \\renewcommand{\\CJKrmdefault}{TCserif}%
 	    \\renewcommand{\\CJKsfdefault}{TCsans}%
 	    \\renewcommand{\\CJKttdefault}{TCmono}%
+	    \\xeCJKsetup{CJKspace = false}%
 	}
 	\\newcommand{\\kerneldocEndTC}{\\endgroup}
 	\\newcommand{\\kerneldocBeginKR}{%
@@ -538,7 +540,7 @@ latex_elements['preamble']  += '''
 	    \\renewcommand{\\CJKrmdefault}{KRserif}%
 	    \\renewcommand{\\CJKsfdefault}{KRsans}%
 	    \\renewcommand{\\CJKttdefault}{KRmono}%
-	    \\xeCJKsetup{CJKspace = true} % For inter-phrase space
+	    % \\xeCJKsetup{CJKspace = true} % true by default
 	}
 	\\newcommand{\\kerneldocEndKR}{\\endgroup}
 	\\newcommand{\\kerneldocBeginJP}{%
@@ -547,6 +549,7 @@ latex_elements['preamble']  += '''
 	    \\renewcommand{\\CJKrmdefault}{JPserif}%
 	    \\renewcommand{\\CJKsfdefault}{JPsans}%
 	    \\renewcommand{\\CJKttdefault}{JPmono}%
+	    \\xeCJKsetup{CJKspace = false}%
 	}
 	\\newcommand{\\kerneldocEndJP}{\\endgroup}
 	% Single spacing in literal blocks
@@ -555,6 +558,7 @@ latex_elements['preamble']  += '''
 	\\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}{}
-- 
2.17.1

[PATCH 4/5] docs/translations: Skip CJK contents if suitable fonts not found

[Akira Yokosawa]

On systems without "Noto Sans CJK" fonts, CJK chapters in
translations.pdf are full of "TOFU" boxes, with a long build time and
a large log file containing lots of missing-font warnings.

Avoid such waste of time and resources by skipping CJK chapters when
CJK fonts are not available.

To skip whole chapters, change the definition of
\kerneldocBegin{SC|TC|KR|JP} commands so that they can have an argument
to be ignored.
This works as far as the argument (#1) is not used in the command.
In place of skipped contents, put a note on skipped contents at the
beginning of the PDF.

Change the call sites in index.rst of CJK translations accordingly.

When CJK fonts are available, existing command definitions with
no argument just work.  LaTeX engine will see additional pairs of
"{" and "}", which add a level of grouping without having any effect
on typesetting.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/conf.py                      | 13 +++++++++----
 Documentation/translations/ja_JP/index.rst |  4 ++--
 Documentation/translations/ko_KR/index.rst |  5 ++---
 Documentation/translations/zh_CN/index.rst |  4 ++--
 Documentation/translations/zh_TW/index.rst |  4 ++--
 5 files changed, 17 insertions(+), 13 deletions(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index ded49b8e9bf6..62cd0e472b3b 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -563,13 +563,18 @@ latex_elements['preamble']  += '''
 	% Custom macros to on/off CJK (Dummy)
 	\\newcommand{\\kerneldocCJKon}{}
 	\\newcommand{\\kerneldocCJKoff}{}
-	\\newcommand{\\kerneldocBeginSC}{}
+	\\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}{}
+	\\newcommand{\\kerneldocBeginTC}[1]{}
 	\\newcommand{\\kerneldocEndTC}{}
-	\\newcommand{\\kerneldocBeginKR}{}
+	\\newcommand{\\kerneldocBeginKR}[1]{}
 	\\newcommand{\\kerneldocEndKR}{}
-	\\newcommand{\\kerneldocBeginJP}{}
+	\\newcommand{\\kerneldocBeginJP}[1]{}
 	\\newcommand{\\kerneldocEndJP}{}
     }
 '''
diff --git a/Documentation/translations/ja_JP/index.rst b/Documentation/translations/ja_JP/index.rst
index 88d4d98eed15..20738c931d02 100644
--- a/Documentation/translations/ja_JP/index.rst
+++ b/Documentation/translations/ja_JP/index.rst
@@ -3,7 +3,7 @@
 	\renewcommand\thesection*
 	\renewcommand\thesubsection*
 	\kerneldocCJKon
-	\kerneldocBeginJP
+	\kerneldocBeginJP{
 
 Japanese translations
 =====================
@@ -15,4 +15,4 @@ Japanese translations
 
 .. raw:: latex
 
-	\kerneldocEndJP
+	}\kerneldocEndJP
diff --git a/Documentation/translations/ko_KR/index.rst b/Documentation/translations/ko_KR/index.rst
index f636b482fb4c..4add6b2fe1f2 100644
--- a/Documentation/translations/ko_KR/index.rst
+++ b/Documentation/translations/ko_KR/index.rst
@@ -3,7 +3,7 @@
 	\renewcommand\thesection*
 	\renewcommand\thesubsection*
 	\kerneldocCJKon
-	\kerneldocBeginKR
+	\kerneldocBeginKR{
 
 한국어 번역
 ===========
@@ -26,5 +26,4 @@
 
 .. raw:: latex
 
-    \normalsize
-    \kerneldocEndKR
+    }\kerneldocEndKR
diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst
index 46e14ec9963d..3d8e130a5a92 100644
--- a/Documentation/translations/zh_CN/index.rst
+++ b/Documentation/translations/zh_CN/index.rst
@@ -5,7 +5,7 @@
 	\renewcommand\thesection*
 	\renewcommand\thesubsection*
 	\kerneldocCJKon
-	\kerneldocBeginSC
+	\kerneldocBeginSC{
 
 .. _linux_doc_zh:
 
@@ -198,4 +198,4 @@ TODOList:
 
 .. raw:: latex
 
-	\kerneldocEndSC
+	}\kerneldocEndSC
diff --git a/Documentation/translations/zh_TW/index.rst b/Documentation/translations/zh_TW/index.rst
index f56f78ba7860..e1ce9d8c06f8 100644
--- a/Documentation/translations/zh_TW/index.rst
+++ b/Documentation/translations/zh_TW/index.rst
@@ -5,7 +5,7 @@
 	\renewcommand\thesection*
 	\renewcommand\thesubsection*
 	\kerneldocCJKon
-	\kerneldocBeginTC
+	\kerneldocBeginTC{
 
 .. _linux_doc_zh_tw:
 
@@ -174,4 +174,4 @@ TODOList:
 
 .. raw:: latex
 
-	\kerneldocEndTC
+	}\kerneldocEndTC
-- 
2.17.1

[PATCH 5/5] docs: pdfdocs: Move CJK monospace font setting to main conf.py

[Akira Yokosawa]

As LaTeX macros for CJK font settings can have Latin-script font
settings as well, settings under Documentation/translations/ can
be moved to the main conf.py.

By this change, translations.pdf built by top-level "make pdfdocs"
can have properly aligned ascii-art diagrams except for Korean
ones.

For the reason of remaining misalignment in Korean diagrams, see
changelog of commit a90dad8f610a ("docs: pdfdocs: Add conf.py
local to translations for ascii-art alignment").

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/conf.py              |  8 ++++++++
 Documentation/translations/conf.py | 12 ------------
 2 files changed, 8 insertions(+), 12 deletions(-)
 delete mode 100644 Documentation/translations/conf.py

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 62cd0e472b3b..fb8f69fc4d38 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -521,6 +521,8 @@ latex_elements['preamble']  += '''
 	    \\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}{%
@@ -532,6 +534,8 @@ latex_elements['preamble']  += '''
 	    \\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}{%
@@ -541,6 +545,8 @@ latex_elements['preamble']  += '''
 	    \\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}{%
@@ -550,6 +556,8 @@ latex_elements['preamble']  += '''
 	    \\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
diff --git a/Documentation/translations/conf.py b/Documentation/translations/conf.py
deleted file mode 100644
index 92cdbba74229..000000000000
--- a/Documentation/translations/conf.py
+++ /dev/null
@@ -1,12 +0,0 @@
-# -*- coding: utf-8 -*-
-# SPDX-License-Identifier: GPL-2.0
-
-# -- Additinal options for LaTeX output ----------------------------------
-# font config for ascii-art alignment
-
-latex_elements['preamble']  += '''
-    \\IfFontExistsTF{Noto Sans CJK SC}{
-	% For CJK ascii-art alignment
-	\\setmonofont{Noto Sans Mono CJK SC}[AutoFakeSlant]
-    }{}
-'''
-- 
2.17.1

Re: [PATCH 0/5] docs: pdfdocs: Improve LaTeX preamble (TOC, CJK fonts)

[Jonathan Corbet]

Akira Yokosawa <akiyks@gmail.com> writes:

> Hi,
>
> This is a follow-up series to the CJK font setting patch series [1]
> upstreamed in v5.15.
>
> [1]: https://lore.kernel.org/r/39d0fb0f-b248-bca4-2dac-df69e8d697b1@gmail.com
>
> There is still a lot of room for improvement in the layout of PDF docs.
>
> This series resolves issues listed below:
>
>  1. Some of chapter and section counts in Table of Contents (TOC) in
>     large PDF docs collide with chapter/section titles, e.g., Chapters 10,
>     11, 12, and 13 and Section 10.10 in userspace-api.pdf.
>  2. In docs of more than 99 pages, page counts in TOC are not aligned
>     properly when maxdepth >= 2 is specified in toctree, e.g., Chapters 10,
>     12, and 13 in userspace-api.pdf
>  3. In TOC of Latin-script docs, quotation and apostrophe symbols look too
>     wide, e.g., Section 2.2 in userspace-api.pdf.
>  4. In TOC of translations, Korean chapter titles lose inter-phrase spaces.
>  5. On systems without "Noto Sans CJK" fonts, CJK chapters in translations
>     results in full of "TOFU" boxes, with a long build time and a large
>     log file containing lots of missing-font warnings.
>  6. In translations.pdf built by "make pdfdocs", ascii-art diagrams in CJK
>     are not aligned properly.

I've applied the set, thanks.

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.

Thanks,

jon

Re: [PATCH 0/5] docs: pdfdocs: Improve LaTeX preamble (TOC, CJK fonts)

[Akira Yokosawa]

On Tue, 15 Feb 2022 16:46:32 -0700,
Jonathan Corbet wrote:

> I've applied the set, thanks.
> 
> I do notice that Documentation/conf.py is getting large and
> unapproachable.

Yes, I was having the same impression.

>                  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.

I have an idea to accomplish this.

Will prepare a follow-up patch once you push the docs-next branch with this
set applied.

        Thanks, Akira

> 
> Thanks,
> 
> jon

Re: [PATCH 0/5] docs: pdfdocs: Improve LaTeX preamble (TOC, CJK fonts)

[Akira Yokosawa]

On Wed, 16 Feb 2022 22:00:04 +0900,
Akira Yokosawa wrote:
> On Tue, 15 Feb 2022 16:46:32 -0700,
> Jonathan Corbet wrote:
> 
>> I've applied the set, thanks.
>>
>> I do notice that Documentation/conf.py is getting large and
>> unapproachable.
> 
> Yes, I was having the same impression.
> 
>>                  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.
> 
> I have an idea to accomplish this.
> 
> Will prepare a follow-up patch once you push the docs-next branch with this
> set applied.

Jon,

The head of docs-next I see is commit 4fbe7b19a948 ("docs: Fix wording in
optional zram feature docs").
I think you have applied my patch set on top of it.
I'd like you to push up-to-date docs-next so that I can start preparing
a follow-up patch.

        Thanks, Akira

Re: [PATCH 0/5] docs: pdfdocs: Improve LaTeX preamble (TOC, CJK fonts)

[Jonathan Corbet]

Akira Yokosawa <akiyks@gmail.com> writes:

> The head of docs-next I see is commit 4fbe7b19a948 ("docs: Fix wording in
> optional zram feature docs").
> I think you have applied my patch set on top of it.
> I'd like you to push up-to-date docs-next so that I can start preparing
> a follow-up patch.

Apologies, I thought I'd done that - done now.

Thanks,

jon