Hi Jon,
This patch kernel-doc improvements. On v2, I'm keeping just
the patches related to man pages generation.
The first patches on this series are focused mostly on .TH
(troff header) line, but, as a side effect, it also change
the name of man pages generated from DOC kernel-doc annotations.
At the previous state, those were overriden due to lots of
duplicated names.
The rationale for most of such changes 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, modern man pages use this format:
.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.
The last 4 patches on this series are new: they fix lots of issues
related to groff format: there, new lines continue the test from
previous pagragraph. This cause issues mainly on:
- tables;
- code blocks;
- lists
With the changes, the output now looks a lot better.
Please notice that the code there is not meant to fully implement
rst -> troff/groff conversion. Instead, it is meant to make the
output reasonable.
A more complete approach would be to use docutils or Sphinx
libraries, but that would likely require to also write a troff
output plugin, as the "man" builder is very limited. Also,
this could be problematic, as kernel-doc classes can be called
from Sphinx. I don't think we need that much complexity, as what
we mainly need is to avoid bad line grouping when generating
man pages.
This series should not affect HTML documentation. It only affect
man page generation and ManFormat output class.
Mauro Carvalho Chehab (13):
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: fix naming for DOC markups
docs: kdoc_output: describe the class init parameters
docs: kdoc_output: pick a better default for modulename
docs: kdoc_output: Change the logic to handle man highlight
docs: kdoc_output: add a logic to handle tables inside kernel-doc
markups
docs: kdoc_output: add support to handle code blocks
docs: kdoc_output: better handle lists
tools/docs/kernel-doc | 1 -
tools/docs/sphinx-build-wrapper | 10 +-
tools/lib/python/kdoc/kdoc_output.py | 297 +++++++++++++++++++++++++--
3 files changed, 283 insertions(+), 25 deletions(-)
--
2.52.0