Add man_skip_desc_subtitle option

[hkuno]

A configuration value to optionally skip printing the description
of a command as a subtitle when generating a manpage.
This commit addresses #9430

Signed-off-by: Harumi Kuno harumi.kuno@hpe.com

Subject: add option to manpage builder to not generate descriptive subtitle

Feature or Bugfix

• Feature

Purpose

@jsquyres and I would like to generate both groff files and also html files from a single set of rst man page files.
However, the manpage.py writer currently always prints a subtitle (added by the manpage.py builder) with a description of the command (the html writer does not do this).

The problem is that there is currently no way to turn that off and if the man page files already include descriptions of the commands (e.g., because the rst files were ported from nroff files), then that description will appear twice in the generated man page.

For example, if rst/conf.py contains the following:

man_pages=[("ompi/mpi/man/man3/MPI_Abort.3","MPI_Abort", "(from conf.py) Terminates MPI execution environment","",3)]

Then the generated man page will look like this:

MPI_ABORT(3)                            Open MPI                            MPI_ABORT(3)

NAME
       MPI_Abort - (from conf.py) Terminates MPI execution environment

       MPI_Abort - Terminates MPI execution environment.

SYNTAX
   C Syntax
          #include <mpi.h>
          int MPI_Abort(MPI_Comm comm, int errorcode)
...

With this change, someone could invoke sphinx-build with a configuration option, like this:

sphinx-build  -b man  -D man_skip_desc_subtitle=True rst/ man/

And then the generated man page will look like this:

MPI_ABORT(3)                            Open MPI                            MPI_ABORT(3)

NAME
       MPI_Abort - Terminates MPI execution environment.

SYNTAX
   C Syntax
          #include <mpi.h>
          int MPI_Abort(MPI_Comm comm, int errorcode)
...

Relates

• manpage and html builders: same rst file, different output #9430
• manpage builder skip printing blank descriptions #9588

[hkuno]

Closing this PR because it is superceded by #9594