Skip to content

K
Kernel

openeuler / Kernel
接近 2 年 前同步成功

通知 8
Star 0
Fork 0
K
Kernel
切换分支/标签
  1. 27 8月, 2022 1 次提交
  3. 01 6月, 2022 1 次提交
  5. 25 2月, 2022 1 次提交
    • A
      docs: pdfdocs: Pull LaTeX preamble part out of conf.py · 398f7abd
      由 Akira Yokosawa 提交于 
      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 3b4c9632 ("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:

  - f7ebe6b7 ("docs: Activate exCJK only in CJK chapters")
  - 0afd4df0 ("docs: pdfdocs: Prevent column squeezing by tabulary")
  - 659653c9 ("docs: pdfdocs: Refactor config for CJK document")
  - e291ff6f ("docs: pdfdocs: Add CJK-language-specific font settings")
  - 7eb368cc ("docs: pdfdocs: Choose Serif font as CJK mainfont if possible")
  - 35382965 ("docs: pdfdocs: Preserve inter-phrase space in Korean translations")
  - 77abc2c2 ("docs: pdfdocs: One-half spacing for CJK translations")
  - 788d28a2 ("docs: pdfdocs: Permit AutoFakeSlant for CJK fonts")
  - 29ac9822 ("docs: pdfdocs: Teach xeCJK about character classes of quotation marks")
  - 7c5c18bd ("docs: pdfdocs: Fix typo in CJK-language specific font settings")
  - aa872e06 ("docs: pdfdocs: Adjust \headheight for fancyhdr")
  - 8716ef41 ("docs: pdfdocs: Tweak width params of TOC")
  - 66939df5 ("docs: pdfdocs: Switch default CJK font to KR variants")
  - 7b686a2e ("docs: pdfdocs: Enable CJKspace in TOC for Korean titles")
  - 5d9158e3 ("docs/translations: Skip CJK contents if suitable fonts not found")
  - b774cc46 ("docs: pdfdocs: Move CJK monospace font setting to main conf.py")

[1]: https://lore.kernel.org/all/87zgmr66cn.fsf@meer.lwn.net/Suggested-by: NJonathan Corbet <corbet@lwn.net>
Signed-off-by: NAkira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/aaa9dca1-27c0-c414-77f3-c5587db0cc5b@gmail.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>
      398f7abd
  7. 16 2月, 2022 5 次提交
    • A
      docs: pdfdocs: Move CJK monospace font setting to main conf.py · b774cc46
      由 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 a90dad8f ("docs: pdfdocs: Add conf.py
local to translations for ascii-art alignment").
Signed-off-by: NAkira Yokosawa <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/eb87790a-03f4-9f29-c8a3-ef2c3e78ca18@gmail.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>
      b774cc46
    • A
      docs/translations: Skip CJK contents if suitable fonts not found · 5d9158e3
      由 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: NAkira Yokosawa <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/3359ca41-b81d-b2c7-e437-7618efbe241d@gmail.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>
      5d9158e3
    • A
      docs: pdfdocs: Enable CJKspace in TOC for Korean titles · 7b686a2e
      由 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: NAkira Yokosawa <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/19141b3e-01d9-1f6d-5020-42fbda784831@gmail.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>
      7b686a2e
    • A
      docs: pdfdocs: Switch default CJK font to KR variants · 66939df5
      由 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: NAkira Yokosawa <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/0c8ea878-0a6f-ea01-ab45-4e66c5facee9@gmail.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>
      66939df5
    • A
      docs: pdfdocs: Tweak width params of TOC · 8716ef41
      由 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.htmlSigned-off-by: NAkira Yokosawa <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/e52b4718-7909-25be-fbc1-76800aa62ae3@gmail.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>
      8716ef41
  9. 11 12月, 2021 4 次提交
  11. 30 11月, 2021 1 次提交
  13. 13 10月, 2021 1 次提交
  15. 07 9月, 2021 1 次提交
  17. 12 8月, 2021 7 次提交
  19. 18 6月, 2021 1 次提交
  21. 02 6月, 2021 1 次提交
  23. 27 5月, 2021 1 次提交
  25. 09 3月, 2021 1 次提交
  27. 23 2月, 2021 1 次提交
  29. 02 2月, 2021 1 次提交
  31. 12 12月, 2020 1 次提交
  33. 04 12月, 2020 1 次提交
  35. 30 10月, 2020 1 次提交
  37. 29 10月, 2020 1 次提交
  39. 15 10月, 2020 2 次提交
  41. 05 9月, 2020 1 次提交
  43. 08 6月, 2020 1 次提交
  45. 21 4月, 2020 1 次提交
  47. 21 3月, 2020 1 次提交
    • M
      docs: conf.py: avoid thousands of duplicate label warning on Sphinx · 4658b0eb
      由 Mauro Carvalho Chehab 提交于 
      The autosectionlabel extension is nice, as it allows to refer to
a section by its name without requiring any extra tag to create
a reference name.

However, on its default, it has two serious problems:

1) the namespace is global. So, two files with different
   "introduction" section would create a label with the
   same name. This is easily solvable by forcing the extension
   to prepend the file name with:

	autosectionlabel_prefix_document = True

2) It doesn't work hierarchically. So, if there are two level 1
   sessions (let's say, one labeled "open" and another one "ioctl")
   and both have a level 2 "synopsis" label, both section 2 will
   have the same identical name.

   Currently, there's no way to tell Sphinx to create an
   hierarchical reference like:

		open / synopsis
		ioctl / synopsis

  This causes around 800 warnings. So, the fix should be to
  not let autosectionlabel to produce references for anything
  that it is not at a chapter level within any doc, with:

	autosectionlabel_maxdepth = 2

Fixes: 58ad30cf ("docs: fix reference to core-api/namespaces.rst")
Signed-off-by: NMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/74f4d8d91c648d7101c45b4b99cc93532f4dadc6.1584716446.git.mchehab+huawei@kernel.orgSigned-off-by: NJonathan Corbet <corbet@lwn.net>
      4658b0eb
  49. 20 3月, 2020 1 次提交
  51. 03 10月, 2019 1 次提交
    • K
      doc-rst: Programmatically render MAINTAINERS into ReST · aa204855
      由 Kees Cook 提交于 
      In order to have the MAINTAINERS file visible in the rendered ReST
output, this makes some small changes to the existing MAINTAINERS file
to allow for better machine processing, and adds a new Sphinx directive
"maintainers-include" to perform the rendering.

Features include:
- Per-subsystem reference links: subsystem maintainer entries can be
  trivially linked to both internally and external. For example:
  https://www.kernel.org/doc/html/latest/process/maintainers.html#secure-computing

- Internally referenced .rst files are linked so they can be followed
  when browsing the resulting rendering. This allows, for example, the
  future addition of maintainer profiles to be automatically linked.

- Field name expansion: instead of the short fields (e.g. "M", "F",
  "K"), use the indicated inline "full names" for the fields (which are
  marked with "*"s in MAINTAINERS) so that a rendered subsystem entry
  is more human readable. Email lists are additionally comma-separated.
  For example:

    SECURE COMPUTING
	Mail:	  Kees Cook <keescook@chromium.org>
	Reviewer: Andy Lutomirski <luto@amacapital.net>,
		  Will Drewry <wad@chromium.org>
	SCM:	  git git://git.kernel.org/pub/scm/linux/kernel/git/kees/linux.git seccomp
	Status:	  Supported
	Files:	  kernel/seccomp.c include/uapi/linux/seccomp.h
		  include/linux/seccomp.h tools/testing/selftests/seccomp/*
		  tools/testing/selftests/kselftest_harness.h
		  userspace-api/seccomp_filter
	Content regex:	\bsecure_computing \bTIF_SECCOMP\b
Signed-off-by: NKees Cook <keescook@chromium.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      aa204855