Re: [PATCH] man*/: ffix

From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
To: linux-man@vger.kernel.org
Cc: Guillem Jover <guillem@hadrons.org>, Alejandro Colomar <alx@kernel.org>
Subject: Re: [PATCH] man*/: ffix
Date: Sun, 16 Apr 2023 18:51:26 -0500	[thread overview]
Message-ID: <20230416235126.vdbiab5p5jwty4ol@illithid> (raw)
In-Reply-To: <20230416231916.281037-1-guillem@hadrons.org>

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

At 2023-04-17T01:19:16+0200, Guillem Jover wrote:
> Escape dashes on dates, UUIDs, URLs, file and package names.
[...]

I'm a +1 on all of this except the dates (explanation below).

> diff --git a/man4/rtc.4 b/man4/rtc.4
> index 55dc1ff6b..b16be16c1 100644
> --- a/man4/rtc.4
> +++ b/man4/rtc.4
> @@ -43,7 +43,7 @@ and
>  .BR time (2),
>  as well as setting timestamps on files, and so on.
>  The system clock reports seconds and microseconds since a start point,
> -defined to be the POSIX Epoch: 1970-01-01 00:00:00 +0000 (UTC).
> +defined to be the POSIX Epoch: 1970\-01\-01 00:00:00 +0000 (UTC).
>  (One common implementation counts timer interrupts, once
>  per "jiffy", at a frequency of 100, 250, or 1000 Hz.)
>  That is, it is supposed to report wall clock time, which RTCs also do.

> diff --git a/man5/proc.5 b/man5/proc.5
> index dc5397a22..9c0b3e2ab 100644
> --- a/man5/proc.5
> +++ b/man5/proc.5
> @@ -4383,7 +4383,7 @@ Unnumbered interrupts are not shown, only summed into the total.
>  The number of context switches that the system underwent.
>  .TP
>  \fIbtime 769041601\fP
> -boot time, in seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
> +boot time, in seconds since the Epoch, 1970\-01\-01 00:00:00 +0000 (UTC).
>  .TP
>  \fIprocesses 86031\fP
>  Number of forks since boot.

These are parts of prose sentences and are themselves prose.  In the
groff man pages we neither model, nor recommend, the use of hyphen-minus
signs (escaped hyphens) in date strings, as one might commonly encounter
in `TH` calls to assign a revision date to a man page, for example.

Similarly, we would not escape the hyphen in the sentence: "While I was
in Quebec, I met Yves St-Denis.".[1]

Escaping hyphens is important for material that might copied and pasted.
I don't think these date expressions for the Epoch qualify.  If one
wants to format the date of the Epoch, "date --date=@0" is less to type.
(In a man page, we would escape _those_ hyphens and might bracket the
command with `EX` and `EE` macro calls.)

Regards,
Branden

[1] https://en.wikipedia.org/wiki/Yves_St-Denis

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