linux.git/Documentation/conf.py, branch v5.16

docs: conf.py: fix support for Readthedocs v 1.0.0

2021-11-29T21:27:52+00:00

As described at:
	https://stackoverflow.com/questions/23211695/modifying-content-width-of-the-sphinx-theme-read-the-docs

since Sphinx 1.8, the standard way to setup a custom theme is
to use html_css_files. While using html_context is OK with RTD
0.5.2, it doesn't work with 1.0.0, causing the theme to not load,
producing a very weird html.

Tested with:
	- Sphinx 1.7.9 + sphinx-rtd-theme 0.5.2
	- Sphinx 2.4.4 + sphinx-rtd-theme 0.5.2
	- Sphinx 2.4.4 + sphinx-rtd-theme 1.0.0
	- Sphinx 4.3.0 + sphinx-rtd-theme 1.0.0

Reported-by: Hans Verkuil 
Tested-by: Hans Verkuil 
Reviewed-by: Laurent Pinchart 
Signed-off-by: Mauro Carvalho Chehab 
Tested-by: Akira Yokosawa 
Link: https://lore.kernel.org/r/80009f0d17ea0840d81e7e16fff6e7677919fdfc.1638004294.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet

docs: pdfdocs: Adjust \headheight for fancyhdr

2021-10-12T20:09:03+00:00

Fancyhdr prior to v4.0 outputs a message per document as follows:

    Package Fancyhdr Warning: \headheight is too small (12.0pt):
    Make it at least 13.59999pt.
    We now make it that large for the rest of the document.
    This may cause the page layout to be inconsistent, however.

Fancyhdr v4.0 complains (once a page!) as follows:

    Package fancyhdr Warning: \headheight is too small (12.0pt):
    (fancyhdr)    Make it at least 13.59999pt, for example:
    (fancyhdr)    \setlength{\headheight}{13.59999pt}.
    (fancyhdr)    You might also make \topmargin smaller to compensate:

    (fancyhdr)    \addtolength{\topmargin}{-1.59999pt}.

Related item in fancyhdr v4.0 announcement on 2021-01-04 [1]:

    Backward incompatible changes:
      - Eliminate adjustments of \headheight or \footskip, when the
        header or footer is too high.

[1]: https://www.ctan.org/ctan-ann/id/mailman.2685.1609863692.2532.ctan-ann@ctan.org

Silence the warnings by adding a couple of \addtolength commands in
the preamble.

Signed-off-by: Akira Yokosawa 
Link: https://lore.kernel.org/r/c5a5577e-5de8-9cd4-9253-956ccc748417@gmail.com
Signed-off-by: Jonathan Corbet

docs: pdfdocs: Fix typo in CJK-language specific font settings

2021-09-06T22:53:39+00:00

There were typos in the fallback definitions of dummy LaTeX macros
for systems without CJK fonts.
They cause build errors in "make pdfdocs" on such systems.
Fix them.

Fixes: e291ff6f5a03 ("docs: pdfdocs: Add CJK-language-specific font settings")
Signed-off-by: Akira Yokosawa 
Link: https://lore.kernel.org/r/ad7615a5-f8fa-2bc3-de6b-7ed49d458964@gmail.com
Signed-off-by: Jonathan Corbet

docs: pdfdocs: Teach xeCJK about character classes of quotation marks

2021-08-12T15:13:33+00:00

Quotation marks in "KR" and "JP" variants of Noto CJK fonts are half
width.
xeCJK assumes they are full width by default and does excessive kerning
around them in Korean and Japanese translations.

Give xeCJK proper hints by the \xeCJKDeclareCharClass command.

Signed-off-by: Akira Yokosawa 
Link: https://lore.kernel.org/r/0da9e3c5-2716-f576-1df5-2f28ea69f0e8@gmail.com
Signed-off-by: Jonathan Corbet

docs: pdfdocs: Permit AutoFakeSlant for CJK fonts

2021-08-12T15:13:33+00:00

Noto CJK fonts don't provide italic shapes.
The AutoFakeSlant option of fontspec and xeCJK packages can be used as
a workaround.

Signed-off-by: Akira Yokosawa 
Link: https://lore.kernel.org/r/502335cc-9a95-3c2a-7744-6cc56ecaf628@gmail.com
Signed-off-by: Jonathan Corbet

docs: pdfdocs: One-half spacing for CJK translations

2021-08-12T15:13:32+00:00

CJK documents are much easier to read with a wider baseline stretch.
Applying onehalfspacing option of "setspace" package looks reasonable.

Note: \usepackage{setspace} needs to be before that of hyperref in the
preamble.
The 'extrapackages' key (available since Sphinx 2.3) is for this purpose.
For systems with Sphinx < 2.3, dummy commands of \onehalfspacing and
\singlespacing are provided instead.
One-half spacing is not effective in LaTeX sources generated by such
revisions of Sphinx.

Signed-off-by: Akira Yokosawa 
Link: https://lore.kernel.org/r/547a1f1c-0bb5-20a7-ea0e-951bfc3c3925@gmail.com
Signed-off-by: Jonathan Corbet

docs: pdfdocs: Preserve inter-phrase space in Korean translations

2021-08-12T15:13:32+00:00

In Korean typesetting, inter-phrase spaces in Hangul text have
a similar role as the the inter-word spaces in Latin text.
They can be preserved by the \xeCJKsetup{CJKspace=true} option.

Signed-off-by: Akira Yokosawa 
Link: https://lore.kernel.org/r/68de2e52-e6d1-3f01-c097-15ba7b28a319@gmail.com
Signed-off-by: Jonathan Corbet

docs: pdfdocs: Choose Serif font as CJK mainfont if possible

2021-08-12T15:13:32+00:00

"Noto Serif CJK SC" and its variants suit better with the roman font
of Latin letters.

On some distros such as Fedora, it is possible to partially install
"Noto Sans CJK" fonts.
So, if the Serif fonts are not found on the system, fall back to the
Sans fonts.

Signed-off-by: Akira Yokosawa 
Link: https://lore.kernel.org/r/5e454140-5d0c-35d4-8c31-3ffb2420793a@gmail.com
Signed-off-by: Jonathan Corbet

docs: pdfdocs: Add CJK-language-specific font settings

2021-08-12T15:13:32+00:00

zh_TW, ko_KR, and ja_JP translations have their preferred glyph sets
different from that of zh_CN.

To switch CJK font in the middle of the translations, introduce custom
LaTeX macros listed below:

    \kerneldocBeginSC
    \kerneldocEndSC
    \kerneldocBeginTC
    \kerneldocEndTC
    \kerneldocBeginKR
    \kerneldocEndKR
    \kerneldocBeginJP
    \kerneldocEndJP

, and embed a pair of macros in each language's index.rst.

NOTE 1: Update of zh_TW/index.rst is deferred to a follow-up change.

NOTE 2: Custom macros added here do not imply \kerneldocCJK(on|off).
This is intentional.  For example, \kerneldocCJKoff needs to be
at the top of Italian translations' index.rst for the footer of
final zh_TW page to be properly typeset.

Signed-off-by: Akira Yokosawa 
Link: https://lore.kernel.org/r/31906baf-7490-68cd-7153-4e4d320fb9b0@gmail.com
Signed-off-by: Jonathan Corbet

docs: pdfdocs: Refactor config for CJK document

2021-08-12T15:13:32+00:00

To make generated LaTeX code portable across systems with different sets
of available fonts, convert font-availability check in python code to
LaTeX code by using a conditional command provided by the "fontspec"
package.

This will help those who run Sphinx on one machine/container and run
latexmk on other machines/containers.

Remove import of check_output as it is unused any more.

Signed-off-by: Akira Yokosawa 
Link: https://lore.kernel.org/r/4baf88af-316d-8aee-240f-6ccbc20907d7@gmail.com
Signed-off-by: Jonathan Corbet