[Bug 273245] textproc/groff: groff_mdoc(7): output from 'man 7 groff_mdoc' is badly broken

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=273245

--- Comment #5 from G. Branden Robinson <g.branden.robinson@gmail.com> ---
(In reply to Wolfram Schneider from comment #4)

Hi Wolfram,

> Are you aware that this tiny change (-man -> -mandoc) will break some of our
> core FreeBSD tools, and a lot of third-party tools which we use in the base
> system? Not to mention some FreeBSD ports which may fail as well.

I anticipated some impact, but was mostly concerned with users of "man"
programs.  Between _mandoc_(1), which does its own man page rendering, and
man-db _man_(1), which has invoked _groff_ with the `-mandoc` flag for 22
years, the impact on end users seemed relatively low.  At the time I mooted (a
form of) this idea to the _groff_ mailing list almost 3 years ago (item D,
https://lists.gnu.org/archive/html/groff/2020-10/msg00012.html ) it drew no
objections in a discussion that included _groff_'s current and former
maintainers, together then representing 21 years of pedigree with the project,
and the _mandoc_ current and present maintainer, Ingo Schwarze.

I'm aware of another (non-proprietary Unix) _man_ implementation, for which I
have no better name than "Brouwer/Lucifredi man".  It has been moribund for
several years, and has been replaced by man-db man where it was once popular,
on RPM-based Linux distributions.  I don't know that it was ever ported to
*BSD, but it may have been.  I also don't know if it used "-mandoc" or "-man". 
But it's arguably an irrelevant implementation; it had been stale long enough
by 2010 that Fedora 14 discarded it for man-db man despite Lucifredi man's home
field advantage, if you will. 

I did not immediately act on the idea back in October 2020.  I raised it again
in June 2021 (item 3,
https://lists.gnu.org/archive/html/groff/2021-06/msg00070.html ), explicitly
flagging it as "disruptive".  It drew no objection, but support from Ingo
Schwarze as well as from Doug McIlroy, with whom some are familiar as Thompson
& Ritchie's manager at Bell Labs, and author of the original man(7) macro
package that shipped in Seventh Edition Unix (1979).

> This will affect all FreeBSD releases/branches (12/13/14/15) that we support.
> A possible workaround is to downgrade the groff port to 1.22.4 locally.

I concede that that is an option.  You may want to peruse a list of bugs
resolved in the groff 1.23.0 release as part of your consideration process. 
Here is one sorted by severity.  I apologize in advance for the gargantuan URL;
it is an inelegant aspect of the GNU Savane ticket tracker.

https://savannah.gnu.org/bugs/?group=groff&func=browse&set=custom&msort=0&bug_id[]=&summary[]=&submitted_by[]=0&resolution_id[]=1&assigned_to[]=0&bug_group_id[]=0&status_id[]=3&severity[]=0&category_id[]=0&plan_release_id[]=103&advsrch=0&msort=0&chunksz=50&spamscore=5&report_id=225&sumORdet=&morder=bug_id%3C&order=severity#results

> Checking our repos I see that we need to change ~100 files:
>
> for i in freebsd-{src,ports,doc};do (cd $i && printf "$i "; git grep 'roff.* -man[^d]' |wc -l );done
> freebsd-src 35
> freebsd-ports 51
> freebsd-doc 9

It would likely be educational for me to retrieve these (3?) repositories and
examine these results in detail.  My expectation is that build
scripts/Makefiles are calling "groff -man" to generate "cat pages".  If that is
the case, then the use of "groff -man" as opposed to "groff -mandoc" is, I
would guess, a bit of sloppiness unfortunately coddled by groff for many years.
 Using "-mandoc" to format man pages when one is uncertain of or indifferent to
the macro package used for their composition has a long, honorable tradition
dating back to 4.3BSD-Reno (1990). 
https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.3BSD-Reno/share/tmac/tmac.andoc

> Thinking about the issue - maybe we should just patch the FreeBSD port of
> groff and revert this change. It hurts a lot of our users.

If so, there are several commits you will want to revert.  At the time this
change was made, they were recorded in a Savannah ticket. 
https://savannah.gnu.org/bugs/?60789

If part of your _groff_ port build involves running its automated test suite
with "make check", then I predict that you will also need to update some test
scripts for the man package that have been written and committed since then.

Please consider me a resource for any questions you have.

Regards,
Branden

-- 
You are receiving this mail because:
You are on the CC list for the bug.