Re: manpage infilicity

| From: D. Hugh Redelmeier <[email protected]>

| On Fedora 29, the dnf(1) has a formatting ugliness:

In private email, it was pointed out that this ugliness probably
didn't come from rst2man or sphinx.

I'm trying to track down just where it comes from.  I found out that
the plumbing of the man command has gotten a lot more complicated than
when I last paid attention (1980s?).

In this case, a preformatted man page, generated by sphinx, is
distributed by Fedora.  When the man command is issued, apparently a
pipeline is created.

	something does gunzip |
	/usr/bin/preconv -e UTF-8 |
	/usr/bin/tbl |
	/usr/bin/nroff -mandoc -Tutf8 |
	/usr/bin/less # as if -r

At the moment, it looks as if nroff is the culprit.

nroff performs nicely if it is invoked with
	 -rLL=86n
and badly with
	 -rLL=85n

The -r flag sets the "number register".  According to groff_man(7), LL
is line length.  "n" is a scaling factor so that these numbers are in
ens, the width of the character n.

But wait!  I do see problems with the input to nroff.

It is generated by sphinx.  My impression is that sphinx is also a
part of the docutils project.

I generated this with
  gunzip -c /usr/share/man/man8/dnf.8.gz | preconv -e UTF-8 | tbl

Here is a section of interest:

   203	.TP
   204	.B \fB\-d <debug level>, \-\-debuglevel=<debug level>\fP
   205	Debugging output level. This is an integer value between 0 (no additional information strings) and 10 (shows all debugging information, even that not understandable to the user), default is 2. Deprecated, use \fB\-v\fP instead.
   206	.TP
   207	.B \fB\-\-debugsolver\fP
   208	Dump data aiding in dependency solver debugging into \fB\&./debugdata\fP\&.
   209	.UNINDENT
   210	.sp
   211	\fB\-\-disableexcludes=[all|main|<repoid>], \-\-disableexcludepkgs=[all|main|<repoid>]\fP
   212	.INDENT 0.0
   213	.INDENT 3.5
   214	Disable the configuration file excludes. Takes one of the following three options:
   215	.INDENT 0.0
   216	.IP \(bu 2
   217	\fBall\fP, disables all configuration file excludes
   218	.IP \(bu 2
   219	\fBmain\fP, disables excludes defined in the \fB[main]\fP section
   220	.IP \(bu 2
   221	\fBrepoid\fP, disables excludes defined for the given repository
   222	.UNINDENT
   223	.UNINDENT
   224	.UNINDENT
   225	.INDENT 0.0
   226	.TP
   227	.B \fB\-\-disable, \-\-set\-disabled\fP

Lines 203-205 show what a normal option description turns into.  Ditto
206-208.  Notice that no explicit indentation is specified.

man(7) descibes .TP as starting a paragraph with a hanging tag.  The
tag is given on the next line.

(Note that the tag is emboldened twice-over (.B and \fB).
This seems like an inconsequential bug.)

Things go weird at line 209, for the --debugexcludes option.
For one thing, .TP isn't used.  For another, there seems to be a lot
of explicit indenting going on.

The indenting is wrong.  It does not match that of other options.

But even with these fixed (by manual editing of the generated nroff
file), my original problem is not solved.  The tag is still split in a
bad place.

Some explicit indentation is probably needed since the paragraph
contains nested paragraphs (the bullet points).  I don't know what the
correct indentation is.