[GTALUG] war story: fixing a doc bug can be hard

[D. Hugh Redelmeier]

I'm reading dnf(8) on Fedora 29 and get irked by the layout of the
options.
--disableexcludes=[all|main|<repoid>],
--disableexcludepkgs=[all|main|<repoid>]

Here's what "man dnf" shows on a terminal that is 80
columns wide.  Ugly.

       --disableexcludes=[all|main|<repoid>],               --disableexcludep‐
       kgs=[all|main|<repoid>]

For those of you with MUAs that mangle this kind of stuff: the two
options don't fit on one line so something broke the line in a
terrible place and then filled the whitespace to justify the result.

It would be a lot better to just break the line at the whitespace and
to not justify the result.  The "not justify" part should just fall
out of there being no whitespace to stretch.

In an attempt to fix this, I tried to figure out how this problem
arose.  Surely this would be easy -- I was a troff adept forty years
ago.  And surely troff couldn't have change much because
(1) the orginal author, Joe Osssanna, died in 1977
(2) (I think) it is chained down by POSIX standard
(3) the language rules made it hard to extend

It turns out that the document representation and transformation isn't
what I thought it was.  It used to be that one wrote man pages in
troff, using the "an" macros, optionally with tbl preprocessing for
tables.

The dnf documentation is in a Python representation called
reStructured Text (.rst), not troff.

The .rst gets formatted by a thing called sphinx, a complex Python
system.  Among other things, it produces a formatted manpage that gets
shipped inside the dnf RPM.  So that seems easy, if odd.

But no.  That formatting cannot take account of terminal width or
characteristics.  So the man command, when confronted with one of
these files, process it in an intricate way, approximately:

	gunzip -c /usr/share/man/man8/dnf.8.gz |
	/usr/bin/preconv -e UTF-8 |
	/usr/bin/tbl |
	/usr/bin/nroff -mandoc -Tutf8 |
	/usr/bin/less -r

The most peculiar part of that pipeline preconv.  It converts the
formatted document back into troff input!

In the case of dnf(8), the resulting troff file has a few problems
with the paragraph for these option but they don't explain this
particular misformatting.

The main problem seems to be in the "andoc" macros or in groff (the
GNU implementation of *roff).  And yes, groff has differences from the
troff I knew 40 years ago.

Getting this far in the problem has taken a few steps.

- download the source for dnf and build the .rpm

- attempt to figure out what builds what.  The build log isn't as
  clear as I'd hope.  I mistakenly thought it was rst2man but it is
  sphinx (they do share code).

- air my issues on an appropriate mailing list.  Contrary to the
  documentation, you actually have to join the list to post.
  So far this is the only traffic on the list this month.
  <https://sourceforge.net/p/docutils/mailman/docutils-users/?viewmonth=201904>

Current state:

- I think that some things are wrong with the resulting ephemeral nroff 
  document but I don't know what's at fault and it isn't too important to 
  me.  I've reported it to the responsible authorities but I'm not sure 
  that they accept that there are problems.

- nroff -mandoc is doing something inappropriate with .TP macros but I
  don't know where the blame lies.  It surely requires engaging with
  another community.  I may run out of steam before getting farther.