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

[G. Branden Robinson]

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

At 2024-08-18T13:53:13-0400, Helge Kreutzmann wrote:
> Please note: I know you are not following traditional man rules any
> more,

I dispute that.  I think groff's man pages are as faithful to the format
and conventions established in the Seventh Edition Unix Programmer's
Manual as any other well-curated corpus of man pages.

I am happy to discuss particulars with you.

> so maybe some of the following issues are changes done on purpose,
> Those where I do not see updates I will mark appropriately, so that
> they are not reported in the future again.

Understood.

> Man page: groff.1
> Issue:    I<roff> → B<roff>(7)

Deliberate.  As far as the font style is concerned, I have explored this
matter at length.

https://lists.gnu.org/archive/html/groff/2023-08/msg00005.html

> "groff - front end to the GNU I<roff> document formatting system"
> 
> "I<groff> is the primary front end to the GNU I<roff> document
> formatting " "system."

If the report is that "roff" and "groff" should be set in bold instead
of italics, or in roman, I do not agree and that is not convention
except in man pages authored with a poor grasp of tradition (or
deliberate deviation).

groff_man_style(7):
              Use italics for file and path names, for environment
              variables, for C data types, for enumeration or
              preprocessor constants in C, for variant (user‐
              replaceable) portions of syntax synopses, for the first
              occurrence (only) of a technical concept being introduced,
              for names of journals and of literary works longer than an
              article, and anywhere a parameter requiring replacement by
              the user is encountered.  An exception involves variant
              text in a context already typeset in italics, such as file
              or path names with replaceable components; in such cases,
              follow the convention of mathematical typography: set the
              file or path name in italics as usual but use roman for
              the variant part (see .IR and .RI below), and italics
              again in running roman text when referring to the variant
              material.

> Man page: groff.1
> Issue:    The variable strings here are different than in the description
> below, e.g. ctext, fallback-encoding, i.e.
>  cs or ctest?
>  fallback-encoding or enc?
>  font-family or fam?
>  font-directory or dir?
>  inclusion-directory or dir?
>  input-encoding or enc?
>  spooler-argument or arg?
>  macro-package or name?
>  macro-directory or dir?
>  page-number or num?
>  page-list or list?
>  postprocessor-argument or arg?
>  output-device or dev?
>  warning-category or name?

Yes.  These are all deliberate.  The idea is to have the synopsis
synopsize, and to keep it in parallel with the command's usage message,
which does describe each option in detail.

You should perceive parity between

Synopsis
       groff [-abcCeEgGijklNpRsStUVXzZ] [-d ctext] [-d string=text]
             [-D fallback‐encoding] [-f font‐family] [-F font‐directory]
             [-I inclusion‐directory] [-K input‐encoding] [-L spooler‐
             argument] [-m macro‐package] [-M macro‐directory] [-n page‐
             number] [-o page‐list] [-P postprocessor‐argument]
             [-r cnumeric‐expression] [-r register=numeric‐expression]
             [-T output‐device] [-w warning‐category] [-W warning‐
             category] [file ...]

       groff -h
       groff --help

       groff -v [option ...] [file ...]
       groff --version [option ...] [file ...]

and

$ groff --help
usage: groff [-abcCeEgGijklNpRsStUVXzZ] [-d ctext] [-d string=text] [-D
fallback-encoding] [-f font-family] [-F font-directory] [-I
inclusion-directory] [-K input-encoding] [-L spooler-argument] [-m
macro-package] [-M macro-directory] [-n page-number] [-o page-list] [-P
postprocessor-argument] [-r cnumeric-expression] [-r
register=numeric-expression] [-T output-device] [-w warning-category] [-W
warning-category] [file ...]
usage: groff {-v | --version}
usage: groff {-h | --help}

...for example.

groff (GNU roff) is a typesetting system that reads plain text input
files that include formatting commands to produce output in
PostScript, PDF, HTML, or DVI formats or for display to a terminal.
See the groff(1) manual page.

By contrast, when we present command-line options in the "Options"
section of a man page, there is no pressing need to have such lengthy,
descriptive parameter names, because these names are explicated in the
immediate context.  This convention should be familiar from mathematical
writing.

     -D enc   Use enc as preconv(1)’s fallback input encoding; implies
              -k.
...
     -I dir   Works as troff’s option (see below), but also implies -g
              and -s.  groff passes -I options and their arguments to
              soelim(1), troff(1), and output drivers; with the option
              letter changed to -M, the same arguments are passed to
              grn(1).
...
     -K enc   Set input encoding used by preconv(1) to enc; implies -k.
...
     -L arg   Pass arg to the print spooler.  If multiple args are
              required, pass each with a separate -L option.  groff does
              not prefix an option dash to arg before passing it to the
              spooler.
...
     -P arg   Pass arg to the postprocessor.  If multiple args are
              required, pass each with a separate -P option.  groff does
              not prefix an option dash to arg before passing it to the
              postprocessor.
...
     -T dev   Prepare output for device dev.  groff passes the -T option
              and its argument to troff, then (unless the -Z option is
              used) runs an output driver to convert troff’s output to a
              form appropriate for dev; see subsection “Output devices”
              below.

As you can see, it also makes for tidier typesetting.

I use long parameter names again where this page (unique in the groff
corpus) explicitly demurs from explaining them.

   Transparent options
     The following options are passed as‐is to the formatter program
     troff(1) and described in more detail in its man page.
...
     -d ctext
     -d string=text
              Define string.
...
     -r cnumeric‐expression
     -r register=numeric‐expression
              Define register.

> "The combination constitutes a document in one of a family of languages we "
> "also call I<roff>; see E<.MR roff 7> for background."

If "E" means "error", then it looks like your tools may want to adapt to
a new feature of groff 1.23's man(7) macros.

groff_man(7):
     .MR topic [manual‐section [trailing‐text]]
            (since groff 1.23) Set a man page cross reference as
            “topic(manual‐section)”.  If manual‐section is absent, the
            package omits the surrounding parentheses.  If trailing‐text
            (typically punctuation) is specified, it follows the closing
            parenthesis without intervening space.  Hyphenation is
            disabled while the cross reference is set.  topic is set in
            the font specified by the MF string.  If manual‐section is
            present, the cross reference hyperlinks to a URI of the form
            “man:topic(manual‐section)”.
...
     James Clark implemented the foregoing features in early versions of
     groff.  Later, groff 1.20 (2009) originated .SY/.YS, .TQ, .MT/.ME,
     and .UR/.UE.  Plan 9 from User Space’s troff introduced .MR in
     2020.

> Man page: groff.1
> Issue:    I<\\%grn> → MR  \\%grn 1 \\%grn 1
> 
> "It is passed to E<.MR \\%soelim 1> and the output driver, and I<\\%grn> is
"
> "passed an B<-M> option with I<dir> as its argument."

Fixed in groff Git since September 2023.

groff(1):
     -I dir   Works as troff’s option (see below), but also implies -g
              and -s.  groff passes -I options and their arguments to
              soelim(1), troff(1), and output drivers; with the option
              letter changed to -M, the same arguments are passed to
              grn(1).

> Man page: groff.1
> Issue 1:  I<\\%pic> → .MR \\%pic 1
> Issue 2:  I<\\%troff> → .MR \\%troff 1
> 
> "Operate in unsafe mode: pass the B<-U> option to I<\\%pic> and
I<\\%troff>."

Thanks for the report.

> Man page: groff.1
> Issue:    cnumeric-expression → numeric-expression
> 
> "B<-r\\ >I<cnumeric-expression>"

This is not a typo, but an explication of the syntax, which admits no
separating space.  groff(1) defers explanation of this option, like `-d`
to troff(1).

groff(1):
   Transparent options
     The following options are passed as‐is to the formatter program
     troff(1) and described in more detail in its man page.

troff(1):
     -r cnumeric‐expression
     -r register=numeric‐expression
              Define roff register c or register as numeric‐expression.
              c must be a one‐character identifier; register can be of
              arbitrary length.  Such assignments happen before any
              macro file is loaded, including the startup file.  Due to
              getopt_long(3) limitations, c cannot be, and register
              cannot contain, an equals sign, even though that is a
              valid character in a roff identifier.

> Man page: groff.1
> Issue 1:  I<roff> → .MR roff 7
> Issue 2:  I<troff> → .MR \\%troff 1

I do not slavishly mark _every_ occurrence of a potential man page cross
reference as such.  This can get noisy and repetitious.

Observe the specification of the `MR` macro.

groff_man(7):
     .MR topic [manual‐section [trailing‐text]]
            (since groff 1.23) Set a man page cross reference as
            “topic(manual‐section)”.  If manual‐section is absent, the
            package omits the surrounding parentheses.  If trailing‐text
            (typically punctuation) is specified, it follows the closing
            parenthesis without intervening space.  Hyphenation is
            disabled while the cross reference is set.  topic is set in
            the font specified by the MF string.  If manual‐section is
            present, the cross reference hyperlinks to a URI of the form
            “man:topic(manual‐section)”.

I _do_ think that a cross reference should be written out in full
(which, in groff 1.23, will also hyperlink them on supporting devices)
on a first occurrence in a page.

> --
> Man page: groff.1
> Issue:    I<sed> → .MR sed 1
> 
> "We used a I<sed> command only to eliminate the 65 blank lines that would "
> "otherwise flood the terminal screen."
> --

Thanks for the report.

> Man page: groff.1
> Issue 1:  I<nroff> → .MR nroff 1
> Issue 2:  I<troff> → .Mr troff 1
> 
> "These have one- or two-letter names arising from intense practices of
naming
> "
> "economy in early Unix culture, a laconic approach that led to many of the "
> "packages being identified in general usage with the I<nroff> and I<troff> "
> "option letter used to invoke them, sometimes to punning effect, as with "
> "\\[lq]man\\[rq] (short for \\[lq]manual\\[rq]), and even with the option "
> "dash, as in the case of the I<s> package, much better known as I<ms> or
even
> "
> "I<-ms>."
> 
> "It provides the features of the AT&T I<troff> and I<nroff> programs as well
> "
> "as many extensions."
> --

As above, this is an avoidance of slavish repetition.

> Man page: groff.1
> Issue:    Use colon at end of line?
> "An output device may be any of the following."
> 
> "Once a E<.MR man 1> librarian program has located a man page, it may
execute
> "
> "a I<groff> command much like the following."

Negative.  Use of a colon is poor grammar when the ensuing list fails to
exhibit sentence-ending punctuation, as is often the case in man pages
composed by inexpert (or indifferent) technical writers.

I editorialized about this problem four years ago.

commit 3afcaf0ed409093626c3a9fe346bd33afec60f29
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sun Sep 6 04:54:06 2020 +1000

    doc/groff.texi, groff_diff(7): Tweak example.

    It's like bathing a cat to get programmers to punctuate inset examples
    that are grammatically part of a sentence, as if they were part of a
    sentence.  People love to just trail off with "the following:", blitz
    the user with 1-100 lines of block-quoted literal, and then pretend they
    ended a sentence.  (This is suggestive of the console jockey ethos; once
    one has thrown code at you, they're done with you.)

    Mathematical literature is more careful.

    However, the man macros make doing the right thing difficult; in nroff
    mode there just aren't many font styles to go around, and while one
    could ".if t" around that problem, a miniature BSD daemon materializes
    on my shoulder and pokes me with a pitchfork if I even consider it.  And
    doing so doesn't help the likely majority of people who _only_ read man
    pages in a terminal window.

    In the end the best solution is to just recast.  Our man pages are
    already overrun with lazy "sentences" ending in "the following:" and
    similar constructions anyway, so it's no burden to scrub out one more.

    tl;dr: A colon does not relieve you of your duty to finish a sentence.

> --
> Man page: groff.1
> Issue:    ISO 646 1991:IRV  → ISO/IEC 646:1991  (what des IRV stand for?)

IRV stands for "International Reference Version".

https://agimcami.wordpress.com/wp-content/uploads/2019/07/ascii-characters-set-aivosto-com.pdf

> "for terminals using the ISO 646 1991:IRV character set and encoding, also "
> "known as US-ASCII."
> --
> Man page: groff.1
> Issue:    ISO → ISO/IEC
> "for terminals using the ISO Latin-1 (ISO 8859-1)  character set and
> encoding."
> 
> "for terminals using the ISO 10646 (\\[lq]Unicode\\[rq]) character set in "
> "UTF-8 encoding."
> 
> "Conversely, the output device B<cp1047> is not available on systems based
on
> "
> "the ISO\\ 646 or ISO\\ 8859 character encoding standards."
> --

As I understand it, ISO and IEC are not merged organizations.  It is
appropriate to denote a standard document as "ISO/IEC" when it is
actually issued under the joint aegis of the two bodies.

When making such a rewrite recommendation, you should cite an
authoritative reference indicating that the IEC has cosponsored the
document in question.

A blind sed(1) rewrite of "ISO" will not do.  One would not say "ISO/IEC
9000 quality management".

> Man page: groff.1
> Issue:    I<\\%gxditview> → .MR \\%gxditview 1
> 
> "for previewing with I<\\%gxditview> using 75 dpi resolution and a 10-point
"
> "base type size."
> 
> "for previewing with I<\\%gxditview> using 75 dpi resolution and a 12-point
"
> "base type size."
> 
> "for previewing with I<\\%gxditview> using 100 dpi resolution and a 10-point
> "
> "base type size."
> 
> "for previewing with I<\\%gxditview> using 100 dpi resolution and a 12-point
> "
> "base type size."
> 
> "The B<-X> option overrides this selection, causing I<\\%gxditview> to serve
> "
> "as the output driver."

Aleady cross referenced earlier in the page.

     -X       Use gxditview(1) instead of the usual postprocessor to
              (pre)view a document on an X11 display.  Combining this
              option with “-T ps” uses the font metrics of the
              PostScript device, whereas the “-T X75”, “-T X75-12”
“-T
              X100”, and “-T X100-12” options use the metrics of X11
              fonts.

> --
> Man page: groff.1
> Issue:    I<\\%afmtodit> → .MR \\%afmtodit 1
> 
> "translates a PostScript Type\\ 1 font in PFB (Printer Font Binary)  format
"
> "to PFA (Printer Font ASCII), which can then be interpreted by
> I<\\%afmtodit>."

Already cross referenced in the immediately preceding paragraph.

     afmtodit(1)
            creates font description files for PostScript Type 1 fonts.

> --
> Man page: groff.1
> Issue 1:  I<troff> → .MR troff 1
> Issue 2:  I<nroff> → .MR nroff 1
> Issue 3:  I<\\%soelim> → .MR soelim 1
> Issue 4:  I<\\%indxbib> → .MR indxbib 1
> Issue 5:  I<\\%lookbib> → .MR lookbib 1
> 
> "Besides I<troff>, the prefix applies to the formatter I<nroff>; the "
> "preprocessors I<eqn>, I<grn>, I<pic>, I<\\%refer>, I<tbl>, and
I<\\%soelim>;
> "
> "and the utilities I<\\%indxbib> and I<\\%lookbib>."

Similarly, the paragraph tags in subsection "Utilities" already cross
reference the latter three of these, and the former two earlier still.

> --
> Man page: groff.1
> Issue:    I<preconv>(1) → .MR preconv 1
> 
> "The value of this variable is passed to the I<preconv>(1)  preprocessor's
> B<-"
> "e> option to select the character encoding of input files."
> 
> "If set but empty, I<groff> calls I<preconv> without an B<-e> option."
> --

Cross-referenced earlier.

     -k       Run preconv(1) preprocessor.  Refer to its man page for
              its behavior if neither of groff’s -K or -D options is
              also specified.

> Man page: soelim.1
> Issue:    I<\\%soelim> → B<soelim>

Conventions are split here.  mandoc(1), and Thomas Dickey's man pages,
tend to boldface a page's own topic name(s) at every occurrence.  I
think this is too busy.

groff_man_style(7):
     Be frugal with italics for emphasis, and particularly with bold.
     Article titles and brief runs of literal text, such as references
     to individual characters or short strings, including section and
     subsection headings of man pages, are suitable objects for
     quotation; see the \(lq, \(rq, \(oq, and \(cq escape sequences in
     subsection “Portability” below.

I am not alone; also see
<https://uit.stanford.edu/accessibility/concepts/typography>.

> --
> Man page: soelim.1
> Issue:    I<roff> → .MR roff 7
> 
> "I<soelim> was designed to handle situations where the target of a I<roff> "
> "source request requires a preprocessor such as E<.MR \\%eqn 1 ,> E<.MR \\"
> "%pic 1 ,> E<.MR \\%refer 1 ,> or E<.MR \\%tbl 1 .>"

Already cross referenced in the first sentence of the document.

Description
     GNU soelim is a preprocessor for the groff(7) document formatting
     system.  soelim works as a filter to eliminate source requests in
     roff(7) input; that is, it replaces lines of the form “.so
     included‐file” within each text input‐file with the contents of
     included‐file, recursively.

> Man page: soelim.1
> Issue:    I<\\%troff> → .MR troff 1
> 
> "That is, files sourced with \\[lq]B<so>\\[rq] are normally read I<only> by
"
> "the formatter, I<\\%troff>."

Thanks for the report.

> Man page: soelim.1
> Issue 1:  I<\\%soelim> → B<\\%soelim>
> Issue 2:  I<\\%troff> → .MR \\%troff 1
> 
> "I<\\%soelim> is I<not> required for I<\\%troff> to source files."

As this is the very next sentence, another cross reference here would be
superfluous.

Automated style checking is a valuable thing to have, but technical
writing, if it is be of sufficient quality to engage a human reader
productively, is not a robotic practice.  I counsel against a lazy
prescription that every single mention of a word that might be a man
page cross reference should be marked up as such.



    _______________________________________________________

Reply to this item at:

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

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

signature.asc
Description: PGP signature