Hi Jon,
This series contains some patches that were submitted originally
on this /41 patch series:
https://patchew.org/linux/cover.1769867953.git.mchehab+huawei@kernel.org/fc6723d13b96db014eaf0f14354d8821ea2085b8.1769867954.git.mchehab+huawei@kernel.org/
It consists on two parts:
- the first two patches are meant to better allow using kernel-doc
inside QEMU and to improve KernelFiles ABI, which will be used
there. I'm placing it here just to avoid on extra PR with just
two patches on it.
- the second part do some improvements on how man pages are produced.
The second part is related to man pages. It is focused mostly on
TH, but, as a side effect, it also change the name of man pages
generated from DOC kernel-doc annotations.
The rationale is that modern troff/man page specs say that .TH has
up to 5 arguments,, as defined at [1]:
.TH topic section [footer-middle] [footer-inside] [header-middle]
[1] https://man7.org/linux/man-pages/man7/groff_man_style.7.html
Right now, Kernel uses 6 arguments, probably due to some legacy
man page definitions.
After double checking, this is typically used like this:
.TH "{name}" {section} "{date}" "{modulename}" "{manual}"
Right now, man pages generation are messing up on how it encodes
each position at .TH, depending on the type of object it emits.
After this series, the definition is more consistent and file
output is better named.
It also fixes two issues at sphinx-build-wrapper related to how
it generate files names from the .TH header.
This series hould not affect HTML documentation. It only changes
man pages.
As the names are now better defined, it also prevents some
file name duplication.
Mauro Carvalho Chehab (11):
docs: kdoc_files: allows the caller to use a different xforms class
docs: kdoc_files: document KernelFiles() ABI
docs: sphinx-build-wrapper: better handle troff .TH markups
docs: sphinx-build-wrapper: don't allow "/" on file names
docs: kdoc_output: use a method to emit the .TH header
docs: kdoc_output: remove extra attribute on man .TH headers
docs: kdoc_output: use a single manual for everything
docs: kdoc_output: don't use a different modulename for functions
docs: kdoc_output: use a more standard order for .TH on man pages
docs: kdoc_output: describe the class init parameters
docs: kdoc_output: pick a better default for modulename
tools/docs/kernel-doc | 1 -
tools/docs/sphinx-build-wrapper | 9 ++--
tools/lib/python/kdoc/kdoc_files.py | 53 ++++++++++++++++++--
tools/lib/python/kdoc/kdoc_output.py | 73 +++++++++++++++++++++++-----
4 files changed, 115 insertions(+), 21 deletions(-)
--
2.52.0