[PATCH 00/11] kernel-doc improvements

[Mauro Carvalho Chehab]

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@xxxxxxxxxx/fc6723d13b96db014eaf0f14354d8821ea2085b8.1769867954.git.mchehab+huawei@xxxxxxxxxx/

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