[bug #57618] man/groff_char.7.man: page needs an overhaul

[Ingo Schwarze]

Update of bug #57618 (project groff):

                Severity:              3 - Normal => 2 - Minor              

    _______________________________________________________

Follow-up Comment #3:

Eliminating the "sic"s was just fine, i think.  When a manual page quotes a
syntax element, users should assume that there is no typo.  If a name is
really too badly misleading, causing a risk of users misusing the feature,
than a mere "sic" is not enough, but a warning needs to be given in a
complete, easily understandable sentence - see the last two paragraphs of the
DESCRIPTION of https://man.openbsd.org/man3/SSL_CTX_use_certificate.3
(regarding SSL_CTX_check_private_key(3)) for a drastic example.  In the case
at hand, there is no risk because users are unlikely to type in the PostScript
glyph name.  And even if they do so and get the spelling wrong because they
don't want any seabirds in their document, there won't be any dire
consequences.  Manual pages should remain concise, focussing on their own
topic, and refrain from picking apart unrelated weaknesses in other software.

I consider the PostScript column useful for two reasons: it provides a nice
reminder that while almost every character can be expressed in terms of
Unicode, not every system of glyphs is a subset of Unicode nor necessarily
organized in a strictly numeric manner.  Also, PostScript plays a special role
in the history of roff, and some aspects of the roff character system - like
the distinction of \- and \(mi - can be better understood when considering
PostScript output than when considering Unicode.

As a minor detail, i agree that a description as "left-pointing guillemet"
would be better than "left guillemet".

Branden, your todo list looks good to me, so please do use this ticket for
that purpose.

Regarding table width, you can shorten "Output" to "Out" and the column width
to 3n, and you can reduce inter-column spacing from 3 to 1.  That probably
isn't sufficient for all lines, but for most.  Maybe some Notes can be made
more concise, but in cases of possible doubt, i'd prioritize precision over
nice layout.

Also note how mandoc(1) deals with lines of excessive length (showing an
extract from the groff to mandoc diff here, compressing whitespace such that
it becomes intelligible in this web interface):

- i \[.i] dotlessi u0131 i without a dot (Turkish)
+ i \[.i] dotlessi u0131 i without a dot
+                        (Turkish)

I.e. mandoc puts multiple text lines *into* single table cells when needed,
making sure that it stays inside the page width specified by the user (or the
default of 78).

I think the 80 column limit is still very relevant.  It is still very
widespread in coding styles, so many programmers use 80-column virtual
terminals (and that's an important audience for groff).  Also, the markup of
practically all manual pages i'm aware of is optimized such that it looks good
in 80-column terminals.   Finally, some argue that shorter lines are easier to
follow when reading; consider printed newspapers, for example, so optimizing
for something like 200-character lines may not be a bright idea regardless of
the century.


    _______________________________________________________

Reply to this item at:

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

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