[bug #63632] man pages: improve some wording and typesetting

[G. Branden Robinson]

Update of bug #63632 (project groff):

                 Summary: manpages: improve some wording and typesetting =>
man pages: improve some wording and typesetting

    _______________________________________________________

Follow-up Comment #7:

[comment #6 comment #6:]
> [comment #0 original submission:]
> > Input file is ./src/preproc/refer/refer.1.man
> > 
> > Add a hair space (\^) around "|" to increase readability
> 
> The \^ escape sequence is not among the approved escapes listed 
> in the Portability section of groff_man(7).  The thin space \| 
> is, though, and should offer the legibility benefit you're after 
> here.

The _groff_ man pages don't scrupulously adhere to our own portability advice
in the referenced section.

The most obvious example is that we use `\[xx]`-style special character escape
sequences in our _man_(7) documents instead of `\(xx`.  However, I am at
greater pains to make _groff_man_(7) (and `_style`) better exemplars of
portable page composition, on the theory that man page authors are more likely
to consult its source even if they neglect to inspect that of other _groff_
man pages.

There are other places in the _groff_ man page corpus where things of
imperfect portability were done.

* Interpolating the name of the output device in _groff_char_(7) (I think this
was me).
* Use of _eqn_ in _groff_(7), _groff_diff_(7), and _eqn_(1) itself; the last
was my innovation.  (Formally, this isn't unportable; practically speaking, it
can make for unintelligible output to terminals.  However, I have an evil idea
that would address the former two cases.  [The latter is already safely
guarded via a portable technique that "Portability" nevertheless does not
countenance.)
* Use of _pic_ in _soelim_(1).  Also guarded per the previous item.

There is no hard rule against use of formatter features not listed in
_groff_man_style_(7)'s "Portability" section.  I haven't seen anyone argue for
one, and I would oppose it because it's just too limiting.

At the same time I haven't changed my mind about wanting to remove the
page-private macros from _groff_hdtbl_(7), _groff_mom_(7), _groff_(7), and
_groff_out_(5).

A better, and limited, use of page-private macros can be found in _grodvi_(1),
_grolj4_(1), _gropdf_(1), and _grops_(1).  These also degrade gracefully in
the event the formatting program can't handle macro definitions.

> > Input file is ./src/preproc/tbl/tbl.1.man
> > 
> > Add a hair space (\^) around "|" to increase readability
> > 
> > 1839:n|n\[rs]f[B]\[rs][tmu]\[rs]f[]n|difference
> > 1856:n|n\f[B]\[tmu]\f[]n|difference
> 
> Adding such spaces here would be flat-out wrong.  These vertical 
> bars are part of the tbl syntax.  In the latter case they are 
> formatted by tbl and do not even appear in the output.  In the 
> former, they're tbl input that is typeset in a monospace font, 
> where horizontal adjustments are inappropriate because they spoil 
> the vertical alignment of the character cells.

I concur.  This head of the hydra (or hecatoncheiris?) in comment #0 should be
sliced off and cauterized.


    _______________________________________________________

Reply to this item at:

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

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