Re: [PATCH] man*/: ffix

["G. Branden Robinson" <g.branden.robinson@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 3632 bytes --]

Hi Alex,

At 2023-04-17T20:14:42+0200, Alejandro Colomar wrote:
> What do standards say about formatting dates?

Nothing that I know of.

> Do they specify the character?

Not that I know of.

> I read some RFCs, but didn't see it specified, other than calling it
> literally '"-"'.  No name of the character, or ASCII code.

Most RFCs don't concern themselves with typography.  :)

> However, date(1) only accepts hyphen-minus, so it would be nice to use
> a compatible format, even if standards didn't mandate it.

Sure, and for an example you actually intend someone to copy and paste,
you should _typeset it as an example_.

In my opinion, the cases at issue weren't examples of things to be
copied and pasted, but _read_.  That is why I attempted to point out a
much easier way of getting date(1) to format the Epoch.

As another example, in the history section of a man page, I might say
something like the following.

  This system call appeared in First Edition Unix, 1971-11-03.

It would be silly, in my opinion, to escape these hyphens.  They're not
intended as command parameters, but for the enlightenment of the reader.

I concede that there are people who don't _ever_ want to see proper
hyphens in UTF-8 man pages.  For them, _every_ hyphen should be a
hyphen-minus.  I don't agree, but groff man(7) can accommodate their
desires.  That is why groff has the following in its "PROBLEMS" file.

---snip---
[groff 1.19.2]

* When viewing man pages, some characters on my UTF-8 terminal emulator
  look funny or copy-and-paste wrong.  Why?

Some Unicode Basic Latin ("ASCII") input characters are mapped to
non-Basic Latin code points in output for consistency with other output
devices, like PDF.  See groff_man_style(7) and groff_char(7) for correct
input conventions and background.  If you use the correct groff special
character escape sequences to input them, you will get correct output no
matter what device the input is formatted for.

However, many man pages are written in ignorance of the correct special
characters to obtain the desired glyphs.  You can conceal these errors
by adding the following to your site-local man(7) configuration.  The
file is called "man.local"; its installation directory depends on how
groff was configured when it was built.

--- start ---
.if '\*[.T]'utf8' \{\
.  char ' \[aq]
.  char - \-
.  char ^ \[ha]
.  char ` \[ga]
.  char ~ \[ti]
.\}
--- end ---

You may also wish to do the same for "mdoc.local".

In man pages (only), groff maps the minus sign special character '\-' to
the Basic Latin hyphen-minus (U+002D) because man pages require this
glyph and there is no historically established *roff input character,
ordinary or special, for obtaining it when a hyphen and minus sign are
both separately available.  To obtain a true minus sign, use the special
character escape sequences '\(mi' or '\[mi]'.
---end snip---

By analogy, we don't compose man pages to write "don\[aq]t", even if for
some reason a person might want to type "don't" as input to a Unix
command.  (I hope they've prepared for its potential interaction with
the shell's quoting mechanisms.)  People have gradually realized over
the years that typing "don\[aq]t" is derpy and awkward.  Typesetting
enthusiasts also note that it gives you a wrongly-shaped apostrophe in
DVI, PostScript, and PDF output.

> I'll hold the patch, to allow for some discussion, but I want to apply
> it.

I unflinchingly agree with the remainder of the patch.  I simply want to
caution against a robotic process of demoting perfectly legitimate
hyphens to the crudely compromised hyphen-minus character.

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]