Re: [groff] Release Candidate 1.22.4.rc3

[Ingo Schwarze]

Hi Brandon,

G. Branden Robinson wrote on Wed, Nov 28, 2018 at 06:44:32PM -0500:
> At 2018-11-28T23:09:34+0100, Bertrand Garrigues wrote:
> > On Sun, Nov 04 2018 at 01:18:32 AM, "G. Branden Robinson" <address@hidden> 
> > wrote:

> B. A few bits of my advice in groff_man.7 about which things get marked
> up in bold vs. italics are controversial within our team, and will be at
> least as much in general.  We're at a bit of an impasse on that, which
> is blocking some inconsistencies in our corpus of 61 page sources from
> being resolved.

We should somehow resolve that, though i'm not sure how if neither
the argument that long-standing BSD practice and Linux man pages
project recommendations agree on this nor that having command names
bold in the SYNOPSIS and italic in the DESCRIPTION imply an
inconsistency within any given page seem strong enough for you.

>> If no I would make a rc4 for final sanity checks (only allowing
>> important bug fixes) before releasing the official 1.22.4.

Please do, i shall definitely test without too much delay.
I consider testing again on different platforms important because
a considerable number of dangerous commits to the build system were
made lately that could impact portability if they happen to contain
any subtle oversights.

> I do wish I had statistics on which groff man pages are the most viewed.

If you have good reasons why you need to know that, consider asking
Michael Stapelberg nicely, mentioning that you are the de-facto groff
documentation maintainer and we value his work on manpages.debian.org,
if that's true from your perspective.  Lastname at debian dot org it is.

> I'm already thinking of release goals for 1.23.  My current fantasies
> are:
> * Moving strip.sed into groff_tmac(5) as an example, and not actually
>   using it in our build anymore.  We can warn of its imminent departure
>   in 1.22.5.

I heartily support getting rid of strip.sed.  I'm not even sure it
should be shown around as an example: trying to parse and manipulate
some language with a parser that doesn't really understand the language
is asking for trouble, usually, so we should hardly give people the idea.
Then again, i won't make a fuss about adding an example somewhere... :)

> * My semantic macro package extending groff_man(7), if I can get it
>   where I'm happy with it and folks on the list don't bleed from the
>   eyes about it.

That would be a HUGE step backwards, making the groff manual pages
even less portable (they are already among the 20-30 least portable
manual page sets in those about ten thousand free software projects
that i looked at, and the amount of portability problems in groff
manual pages is vastly larger than in most other of those 20-30
projects).  You surely want to make that worse, right?

The dusty man-ext macros are already a trainwreck: they have been
around for more than 12 years now and still aren't universally
supported, and the bad practice of copying macro implementations
into each and every bloody manual page only makes matters worse,
causing bloat, lingering outdated or buggily hand-edited versions,
and other potential compat issues.  For example, what is mandoc(1)
supposed to do?  Use the slow, purely presentational, and potentially
buggy and outdated local macro implementations, just in case somebody
edited them in a way that matters for the page at hand, or use the
fast, partially structural, actively maintained built-in C
implementations?  Or do you want mandoc(1) to inspect the local
macro implementations and try to guess whether they are better or
worse than the normal behaviour of the macros?

That said, i'm looking forward to the release and very much
appreciating the work both of you are doing.

Yours,
  Ingo