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/
