[bug #66103] manpage-10n project: issues in man pages

[G. Branden Robinson]

Follow-up Comment #10, bug #66103 (group groff):

Hi Helge,

At 2024-09-14T12:35:35-0400, Helge Kreutzmann wrote:
> thanks for handling the report. I'll note down where you are not in
> agreement with the report, so it won't be reported again in the
> future.

Okay.  I won't get upset if they are.  I can cross-reference back
to this one if necessary.  :)

> Regarding the questions raised, here is my reply. It's a bit tough in
> this form, so please accept that citing is difficult.

Understood.

> 1. Man rules:
> If in doubt, I look at man-pages(7).

That's a good resource, and has gotten better over the years, but it's a
style guide specifically for the Linux man-pages project.  _groff_ is
not the same project.  While I, like Ingo, believe there should be
considerable parity between projects' man page styling practices, I am
willing to go only so far as a prescriptivist.  I have my own conscience
to struggle with.  ;-)

_groff_'s own style guide for man pages is in, you won't be surprised to
learn, groff_man_style(7).

> I'm not judging it, but given also this thread, I noticed e.g. the
> following changes:

> -Any reference to another man page should be written with the name in bold

This is a matter of preference and moreover of historical mutation, as I
explored at length in one of the URLs in comment #1.  Importantly, an
explicit design objective of the new `MR` macro is to give the user--the
person typing "man whatever"--a means of expressing that preference such
that a man(7) document will honor it.

groff_man(7):

Options
     The following groff options set registers (with -r) and strings
     (with -d) recognized and used by the man macro package.  To ensure
     rendering consistent with output device capabilities and reader
     preferences, man pages should never manipulate them.
...
     -dMF=man‐page‐topic‐font
              Select the font used for man page identifiers in .TH calls
              and topics named in .MR calls; the default is “I” (italic
              style of the default family).  Any valid argument to
              groff’s “.ft” request may be used.  If the MF string ends
              in “I”, the package assumes it to be an oblique typeface,
              and applies italic corrections before and after man page
              topics and identifiers.


mdoc(7) from
[https://git.savannah.gnu.org/cgit/groff.git/tree/macros/tmac.doc?h=1.02
day one (or 1990 at the latest)] supported an extensive mechanism for
user customization of the styling of most formatting macros.  I don't
know to what extent Ingo's mandoc(1) supports that, but _groff_ has done
so for 34+ years.

> -The list below shows conventional or suggested sections.
> Again, no judgement, just an observation.

Acknowledged.

> 2. No E<.MR ..> does not mean error. It is a way for po4a to express to
insert
> the new MR macro. 

Ahh, interesting!  E<> is new to me; I'm familiar with B<> and I<> and I
think there's a C<> or maybe an L<>?  I've looked in vain for a
canonical reference to all such po4a tags.  Can you point me to one?

> 3. List styles/colons: I've seen (also in other context) different
> conventions, but I'm not a native speaker, so I simply wanted to point
> this (potential) issue out. (And see comment #7)

Native speech might not help.  One _groff_ developer from the U.K.
starts such colon-introduced lists like this:-

...like a discombobulated obelus ÷.  I seldom see that orthography
anywhere, but when I do, it seems to be a Commonwealth practice.

I lump it in with fortnights, ha'pennies and unleavened "biscuits".  ;-)

> 4. Regarding ISO/IEC: I know the difference, I'm editor of several
> ISO/IEC standards and I double checked each proposal. This was *not*
> done blindly.  (And yes, this is ISO 9001, I'm aware).

Ah, excellent!

> If you want to check yourself: Insert the standard number in question
> in www.iso.org. If it comes from ISO/IEC JTC1 (the group responsible
> for joint standards), then it is written out. (This is what I did for
> *every* report on this matter).

Thank you for the link, the advice, and for researching the background.
I'll reopen the ticket to reflect the need to address this issue.

> I was basically correcting it as "IEC" is often left out, even though
> it is a joint standard.

Yes.  I've seen it omitted so often that I am left with little intuition
as to whether any given ISO standard commonly cited by Unix developers
is a joint one with IEC or not.

> 5.Regarding cross reference - I acknowledge your decision, I'm
> personally fond of have more then less cross references or bold
> typeface for self reference. I think it helps for consistency and do
> not feel it "nosy". But again, this is just my personal impression.
> (In agreement with Comment 4)

Acknowledged.

> 6. Regarding the decision to have different terms in the synopsis and
> later on in the man page - ok, I'm just worried it might confuse
> readers. But again, I did not do any study on this.

It's a relatively recent initiative of mine in my development as a
technical writer.  I might come to repent of it.  But right now, I think
it better than the alternative, for the reasons I proffered.

Regards,
Branden



    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?66103>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/

signature.asc
Description: PGP signature