Re: [groff] [PATCH] man7/mdoc_samples.7: srcfix: Avoid a warning about a wrong section

[G. Branden Robinson]

At 2019-02-27T10:09:44+0100, Michael Kerrisk (man-pages) wrote:
> Bjarni,
> 
> On 2/16/19 7:03 PM, Bjarni Ingi Gislason wrote:
> > Usage: .Rv -std in sections 2 and 3 only (#1672)
> > 
> >   The output from "nroff" and "groff" is unchanged
> 
> Can you please elaborate on what the problem problem is (.,
> how do you see the warning)?

I can't answer the parenthetical definitively--I think Bjarni has
customized local versions of man-db and groff that enable or supplement
warnings, making a kind of lint tool for man pages.

But I think I can speak to the underlying change.  The names of some
symbols in the mdoc macro package got their "doc-" prefixes restored to
them in groff 1.22.4.  They had been getting rewritten by "the stripper"
in the groff source tree, a sed script which applies a bunch of
transforms to a few of the macro packages to make them run more
efficiently.  Groff's parser does not tokenize its input, let alone
compile it down to an intermediate representation, so for instance if
you have a 72-character comment line inside a macro definition or loop,
thus:

.\" ********************************************************************

...groff will re-parse the 73 characters (counting the newline) every
time the macro is called or the loop iterates.

Unfortunately it is only the stripped version of the macro packages that
get installed, which makes them pretty hostile to user comprehension,
like JavaScript minification.

Opinions on the utility of the stripper script among the groff
development team are mixed.  One thing no one cared to defend was using
the stripper to change the names of string or number registers, as those
are part of the interface of a macro package, not cosmetic or stylistic
stuff.  The whole issue arose because the stripper script inadvertently
renamed a symbol in "mom", an entirely different macro package, contrary
to the knowledge and intentions of its developer.

Here is the commit in question.

https://lists.gnu.org/archive/html/groff-commit/2017-11/msg00098.html

Come to think of it, because this _was_ an interface change for mdoc,
this change should have been documented in the NEWS file for groff
1.22.4.  That it was not was my oversight, and I apologize.

> > Signed-off-by: Bjarni Ingi Gislason <address@hidden>
> > ---
> >  man7/mdoc.samples.7 | 4 ++--
> >  1 file changed, 2 insertions(+), 2 deletions(-)
> > 
> > diff --git a/man7/mdoc.samples.7 b/man7/mdoc.samples.7
> > index 6d1887481..7109afba4 100644
> > --- a/man7/mdoc.samples.7
> > +++ b/man7/mdoc.samples.7
> > @@ -1668,11 +1668,11 @@ will generate the following text:
> >  .Pp
> >  .\" fake section 3 to avoid error message from Rv
> >  .\".ds cH 3
> > -.ds section 3
> > +.ds doc-section 3
> >  .Rv -std atexit
> >  .\" and back to 7 again
> >  .\".ds cH 7
> > -.ds section 7
> > +.ds doc-section 7
> >  .Pp
> >  The
> >  .Fl std

Regards,
Branden

signature.asc
Description: PGP signature