[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [groff] [PATCH] man7/mdoc_samples.7: srcfix: Avoid a warning about a
Michael Kerrisk (man-pages)
Re: [groff] [PATCH] man7/mdoc_samples.7: srcfix: Avoid a warning about a wrong section
Wed, 27 Feb 2019 13:37:46 +0100
On Wed, 27 Feb 2019 at 10:48, 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,
> .\" ********************************************************************
> ...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,
> 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.
> 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.
So, summary: should I apply Bjarni's patch? Or does this lead to
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/