docs: kerneldoc-preamble.sty: Remove code for Sphinx <2.4

Now that Sphinx 2.4.4 or better is required, get rid of
\providecommand{}'s for compatibility with Sphinx 1.7.9.

While at it, reword the comment on \sphinxtableofcontentshook
for better description of why it needs to be emptied.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <ed1ec6f2-0050-46f6-807d-8679f26427e9@gmail.com>

docs: kerneldoc-preamble: Test xeCJK.sty before loading

On distros whose texlive packaging is fine-grained, texlive-xecjk
can be installed/removed independently of other texlive packages.
Conditionally loading xeCJK depending only on the existence of the
"Noto Sans CJK SC" font might end up in xelatex error of
"xeCJK.sty not found!".

Improve the situation by testing existence of xeCJK.sty before
loading it.

This is useful on RHEL 9 and its clone distros where texlive-xecjk
doesn't work at the moment due to a missing dependency [1].
"make pdfdocs" for non-CJK contents should work after removing
texlive-xecjk.

Link: [1] https://bugzilla.redhat.com/show_bug.cgi?id=2086254
Fixes: 398f7abdcb7e ("docs: pdfdocs: Pull LaTeX preamble part out of conf.py")
Cc: stable@vger.kernel.org # v5.18+
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org>
Link: https://lore.kernel.org/r/c24c2a87-70b2-5342-bcc9-de467940466e@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: pdfdocs: Add space for chapter counts >= 100 in TOC

It turns out that networking.pdf has exceeded 100 chapters and
titles of chapters >= 100 collide with their counts in its table
of contents (TOC).

Increase relevant params by 0.6em in the preamble to avoid such
ugly collisions.

While at it, fix a typo in comment (subsection).

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/bdb60ba3-7813-47d0-74f9-7c31dd912d95@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Reword note on missing CJK fonts

Use past tense as the fonts can be installed after the fact.
Add suggestion to install "Noto Sans CJK" and "Noto Serif CJK"
font families. ("Noto Serif CJK" is optional.)

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/dfefa601-c58d-c86c-953f-5e4454db9409@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: kerneldoc-preamble.sty: Expand comments in LaTeX code

Expand comments in LaTeX code and mention some of important points
told in changelogs of conf.py changes.
Hopefully they can help future contributors in this area.

No code change involved.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/bce9261b-1950-3146-07b2-07bd2ec79158@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: pdfdocs: Pull LaTeX preamble part out of conf.py

Quote from Jon's remark [1]:

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.

Pull LaTeX preamble settings added since commit 3b4c963243b1 ("docs:
conf.py: adjust the LaTeX document output") out into
sphinx/kerneldoc-preamble.sty.

It will be copied to the build directory by the added
"latex_additional_files" setting in conf.py.

As a bonus, LaTeX/TeX code can be maintained without escaping backslashes.

To compensate the loss of change history in sphinx/kerneldoc-preamble.sty,
here is a list of changes made in conf.py:

- f7ebe6b76940 ("docs: Activate exCJK only in CJK chapters")
- 0afd4df0d16a ("docs: pdfdocs: Prevent column squeezing by tabulary")
- 659653c9e546 ("docs: pdfdocs: Refactor config for CJK document")
- e291ff6f5a03 ("docs: pdfdocs: Add CJK-language-specific font settings")
- 7eb368cc319b ("docs: pdfdocs: Choose Serif font as CJK mainfont if possible")
- 35382965bdd2 ("docs: pdfdocs: Preserve inter-phrase space in Korean translations")
- 77abc2c230b1 ("docs: pdfdocs: One-half spacing for CJK translations")
- 788d28a25799 ("docs: pdfdocs: Permit AutoFakeSlant for CJK fonts")
- 29ac9822358f ("docs: pdfdocs: Teach xeCJK about character classes of quotation marks")
- 7c5c18bdb656 ("docs: pdfdocs: Fix typo in CJK-language specific font settings")
- aa872e0647dc ("docs: pdfdocs: Adjust \headheight for fancyhdr")
- 8716ef413aa5 ("docs: pdfdocs: Tweak width params of TOC")
- 66939df53948 ("docs: pdfdocs: Switch default CJK font to KR variants")
- 7b686a2ea1e4 ("docs: pdfdocs: Enable CJKspace in TOC for Korean titles")
- 5d9158e3c762 ("docs/translations: Skip CJK contents if suitable fonts not found")
- b774cc46313b ("docs: pdfdocs: Move CJK monospace font setting to main conf.py")

[1]: https://lore.kernel.org/all/87zgmr66cn.fsf@meer.lwn.net/

Suggested-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/aaa9dca1-27c0-c414-77f3-c5587db0cc5b@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>