Re: [groff] no header in Japanese manpages

[G. Branden Robinson]

[response inline]

At 2019-04-20T19:22:34+0200, Steffen Nurpmeso wrote:
> Hello.
> 
> KUBO Koichi wrote in <address@hidden>:
>  |I am using groff-1.22.4 on FreeBSD.
>  |After updating groff, I realized that there is no header in Japanese
>  |manpages using mdoc.tmac.  So I added the following line to
>  |mdoc.local:
>  |
>  |.if ((\n[.x]\n[.y] >= 122) & (\n[.Y] >= 4)) \{\
>  |.  if "\*[locale]"japanese" \{\
>  |
>  |.    als doc-section-name        section-name
[...]
> This should not be needed, the doc- is a shared prefix that will
> be stripped during installations, as it is not needed.

Strictly speaking, all that is needed are symbol names of the smallest
possible length that will remain unique; fortunately, the stripper
script was not _that_ aggressive.  ;-)

> Whether it is good to strip it, i do not know.  I do not like it.

No one did, and it adversely affected the mom macro package, which is
why we fixed it:

2017-11-12  G. Branden Robinson <address@hidden>

        * tmac/strip.sed: Stop rewriting symbol names.  A substitution
        originally intended to strip the "doc-" prefix off of mdoc macro
        and string names unintentionally caught some mom stuff.
        Harmlessly in this instance, but with potentially surprising
        future effects.  Remove (only) this substitution per discussion in
        https://lists.gnu.org/archive/html/groff/2017-11/msg00055.html
        et sequentia.

(The above is from the groff changelog file.)

> Namespaces would be much cooler, like being able to say "use namespace
> doc",

Definitely.

> but i cannot help it, at least not for the forseeable future.  I am
> confident Ingo tested 1.22.4.

I am confident he did too, but not everyone has Japanese mdoc pages
handy, I reckon.

> Out of interest, who needs this doc- prefix, actually?

No one _needs_ it, but it's the polite thing to do to keep from
cluttering the namespace.

At 2019-04-23T14:36:34+0200, Steffen Nurpmeso wrote:
> Well i think it has been changed from 1.22.3 to .4.  Now the doc-
> prefix is not stripped no more, and any downstream consumers need
> to adjust.
> 
>  |Sorry for taking up your time.
> 
> I see it was not mentioned in the 1.22.4 release announcement.
> This surely was an oversight only, with no ill intent.

This came up a couple of months ago.  I fell on my sword over it, but
Ingo's view was that mdoc's symbol names are not part of its advertised
interface.

See
https://lists.gnu.org/archive/html/groff/2019-02/msg00131.html
and subsequent messages.

Anyway, the bottom line is that the stripper no longer rewrites _any_
symbol names, and I or someone else will probably kill the stripper off
entirely one of the days, as no advocates remain for its retention.

If I do it, I may move the script into an "advanced usage" section of
groff(7) or similar, to help out any users who actually do need to
optimize the performance of their documents' rendering.  Or maybe web
searches will be good enough for this doubtlessly small audience.

Regards,
Branden

signature.asc
Description: PGP signature