'-' vs '\-' in TH (man(7))

'-' vs '\-' in TH (man(7))

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 587 bytes --]

Hi Branden,

I just noticed that the Linux man-pages use '-' in TH.  That's
surprising to me, as Michael was careful to use '\-' correctly.

In the documentation, I couldn't find anything that says TH
should be different than anywhere else, and so I'd expect he
would have used it there.

$ grep -rn '^\.TH [^ ]*-' man* | wc -l
30
$ grep -rn '^\.TH [^ ]*\\-' man* | wc -l
0

Was it just an oversight, or are there any obscure reasons to do
that?

Cheers,
Alex


-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

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

Re: '-' vs '\-' in TH (man(7))

[Brian Inglis]

On Sun, 20 Aug 2023 21:10:52 +0200, Alejandro Colomar wrote:
> Hi Branden,
> I just noticed that the Linux man-pages use '-' in TH.  That's
> surprising to me, as Michael was careful to use '\-' correctly.
> In the documentation, I couldn't find anything that says TH
> should be different than anywhere else, and so I'd expect he
> would have used it there.
> $ grep -rn '^\.TH [^ ]*-' man* | wc -l
> 30q
> $ grep -rn '^\.TH [^ ]*\\-' man* | wc -l
> 0
> Was it just an oversight, or are there any obscure reasons to do
> that?

Those are just normal *hyphens* *within* the page title command/function/... 
name; perhaps you are thinking of '\-' used as a *dash*(/minus) after the page 
title command/function/... name following .SH NAME in all 1111 files?

See groff_char(7):

"For best results in roff systems, use the “−” character in input outside an 
escape sequence only to mean a hyphen, as in the phrase “long-term”. For a minus 
sign in running text or a Unix command-line option dash, use \− (or \[−] in 
groff if you find it helps the clarity of the source document)."...

-- 
Take care. Thanks, Brian Inglis              Calgary, Alberta, Canada

La perfection est atteinte                   Perfection is achieved
non pas lorsqu'il n'y a plus rien à ajouter  not when there is no more to add
mais lorsqu'il n'y a plus rien à retirer     but when there is no more to cut
                                 -- Antoine de Saint-Exupéry

Re: '-' vs '\-' in TH (man(7))

[Alejandro Colomar]

On 2023-08-20 23:51, Brian Inglis wrote:
> On Sun, 20 Aug 2023 21:10:52 +0200, Alejandro Colomar wrote:
>> Hi Branden,
>> I just noticed that the Linux man-pages use '-' in TH.  That's
>> surprising to me, as Michael was careful to use '\-' correctly.
>> In the documentation, I couldn't find anything that says TH
>> should be different than anywhere else, and so I'd expect he
>> would have used it there.
>> $ grep -rn '^\.TH [^ ]*-' man* | wc -l
>> 30q
>> $ grep -rn '^\.TH [^ ]*\\-' man* | wc -l
>> 0
>> Was it just an oversight, or are there any obscure reasons to do
>> that?
> 
> Those are just normal *hyphens* *within* the page title command/function/... 
> name; perhaps you are thinking of '\-' used as a *dash*(/minus) after the page 
> title command/function/... name following .SH NAME in all 1111 files?
> 
> See groff_char(7):
> 
> "For best results in roff systems, use the “−” character in input outside an 
> escape sequence only to mean a hyphen, as in the phrase “long-term”. For a minus 
> sign in running text or a Unix command-line option dash, use \− (or \[−] in 
> groff if you find it helps the clarity of the source document)."...
> 

Are they all?  I see they are all in man7 (there's one in man5, which is
my bad, actually), so it's more likely that the names don't represent
some identifier that has a minus sign in it, however, I still have doubts.


$ grep -rn '^\.TH [^ ]*-' man*
man5/proc_sysrq-trigger.5:7:.TH proc_sysrq-trigger 5 (date) "Linux man-pages (unreleased)"
man7/man-pages.7:11:.TH man-pages 7 (date) "Linux man-pages (unreleased)"
man7/iso_8859-10.7:6:.TH ISO_8859-10 7 (date) "Linux man-pages (unreleased)"
man7/iso_8859-8.7:8:.TH ISO_8859-8 7 (date) "Linux man-pages (unreleased)"
man7/iso_8859-9.7:6:.TH ISO_8859-9 7 (date) "Linux man-pages (unreleased)"
man7/rtld-audit.7:8:.TH RTLD-AUDIT 7 (date) "Linux man-pages (unreleased)"
man7/bpf-helpers.7:30:.TH "BPF-HELPERS" 7 "2023-04-11" "Linux v6.2"
man7/iso_8859-14.7:6:.TH ISO_8859-14 7 (date) "Linux man-pages (unreleased)"
man7/user-keyring.7:6:.TH user-keyring 7 (date) "Linux man-pages (unreleased)"
man7/koi8-u.7:8:.TH KOI8-U 7 (date) "Linux man-pages (unreleased)"
man7/iso_8859-11.7:8:.TH ISO_8859-11 7 (date) "Linux man-pages (unreleased)"
man7/iso_8859-1.7:8:.TH ISO_8859-1 7 (date) "Linux man-pages (unreleased)"
man7/iso_8859-6.7:6:.TH ISO_8859-6 7 (date) "Linux man-pages (unreleased)"
man7/persistent-keyring.7:6:.TH persistent-keyring 7 (date) "Linux man-pages (unreleased)"
man7/signal-safety.7:6:.TH signal-safety 7 (date) "Linux man-pages (unreleased)"
man7/thread-keyring.7:6:.TH thread-keyring 7 (date) "Linux man-pages (unreleased)"
man7/iso_8859-4.7:6:.TH ISO_8859-4 7 (date) "Linux man-pages (unreleased)"
man7/process-keyring.7:6:.TH process-keyring 7 (date) "Linux man-pages (unreleased)"
man7/iso_8859-2.7:9:.TH ISO_8859-2 7 (date) "Linux man-pages (unreleased)"
man7/utf-8.7:10:.TH UTF-8 7 (date) "Linux man-pages (unreleased)"
man7/armscii-8.7:6:.TH ARMSCII-8 7 (date) "Linux man-pages (unreleased)"
man7/iso_8859-13.7:6:.TH ISO_8859-13 7 (date) "Linux man-pages (unreleased)"
man7/iso_8859-5.7:6:.TH ISO_8859-5 7 (date) "Linux man-pages (unreleased)"
man7/koi8-r.7:6:.TH KOI8-R 7 (date) "Linux man-pages (unreleased)"
man7/session-keyring.7:6:.TH session-keyring 7 (date) "Linux man-pages (unreleased)"
man7/user-session-keyring.7:6:.TH user-session-keyring 7 (date) "Linux man-pages (unreleased)"
man7/iso_8859-7.7:6:.TH ISO_8859-7 7 (date) "Linux man-pages (unreleased)"
man7/iso_8859-16.7:6:.TH ISO_8859-16 7 (date) "Linux man-pages (unreleased)"
man7/iso_8859-15.7:7:.TH ISO_8859-15 7 (date) "Linux man-pages (unreleased)"
man7/iso_8859-3.7:6:.TH ISO_8859-3 7 (date) "Linux man-pages (unreleased)"


Should the '-' in e.g. UTF-8 be hyphen, or should it be a minus?  Are all of
these hyphens?  And if so, why would a hyphen belong there?

Also, there's inconsistency within the same page.  For example, in
session-keyring(7), we can see this:


$ grep 'session.\?-keyring' man7/session-keyring.7 
.TH session-keyring 7 (date) "Linux man-pages (unreleased)"
session-keyring \- session shared process keyring
.BR user\-session\-keyring (7)
.BR user\-session\-keyring (7)
.BR user\-session\-keyring (7),


Why does user-session-keyring(7) go with minus, but session-keyring(7) goes
with hyphen?

There's also some inconsistency in the use of hyphens (and minus in the
filenames) and underscores; it seems that they are randomly chosen:


$ grep -rn '^\.TH [^ ]*_' man7
man7/iso_8859-10.7:6:.TH ISO_8859-10 7 (date) "Linux man-pages (unreleased)"
man7/iso_8859-8.7:8:.TH ISO_8859-8 7 (date) "Linux man-pages (unreleased)"
man7/iso_8859-9.7:6:.TH ISO_8859-9 7 (date) "Linux man-pages (unreleased)"
man7/cgroup_namespaces.7:6:.TH cgroup_namespaces 7 (date) "Linux man-pages (unreleased)"
man7/shm_overview.7:6:.TH shm_overview 7 (date) "Linux man-pages (unreleased)"
man7/iso_8859-14.7:6:.TH ISO_8859-14 7 (date) "Linux man-pages (unreleased)"
man7/network_namespaces.7:6:.TH network_namespaces 7 (date) "Linux man-pages (unreleased)"
man7/path_resolution.7:5:.TH path_resolution 7 (date) "Linux man-pages (unreleased)"
man7/sem_overview.7:5:.TH sem_overview 7 (date) "Linux man-pages (unreleased)"
man7/iso_8859-11.7:8:.TH ISO_8859-11 7 (date) "Linux man-pages (unreleased)"
man7/iso_8859-1.7:8:.TH ISO_8859-1 7 (date) "Linux man-pages (unreleased)"
man7/iso_8859-6.7:6:.TH ISO_8859-6 7 (date) "Linux man-pages (unreleased)"
man7/ipc_namespaces.7:6:.TH ipc_namespaces 7 (date) "Linux man-pages (unreleased)"
man7/user_namespaces.7:7:.TH user_namespaces 7 (date) "Linux man-pages (unreleased)"
man7/string_copying.7:5:.TH string_copying 7 (date) "Linux man-pages (unreleased)"
man7/iso_8859-4.7:6:.TH ISO_8859-4 7 (date) "Linux man-pages (unreleased)"
man7/iso_8859-2.7:9:.TH ISO_8859-2 7 (date) "Linux man-pages (unreleased)"
man7/kernel_lockdown.7:7:.TH kernel_lockdown 7 (date) "Linux man-pages (unreleased)"
man7/feature_test_macros.7:5:.TH feature_test_macros 7 (date) "Linux man-pages (unreleased)"
man7/mount_namespaces.7:7:.TH mount_namespaces 7 (date) "Linux man-pages (unreleased)"
man7/math_error.7:6:.TH math_error 7 (date) "Linux man-pages (unreleased)"
man7/iso_8859-13.7:6:.TH ISO_8859-13 7 (date) "Linux man-pages (unreleased)"
man7/uts_namespaces.7:6:.TH uts_namespaces 7 (date) "Linux man-pages (unreleased)"
man7/address_families.7:6:.TH address_families 7 (date) "Linux man-pages (unreleased)"
man7/time_namespaces.7:6:.TH time_namespaces 7 (date) "Linux man-pages (unreleased)"
man7/iso_8859-5.7:6:.TH ISO_8859-5 7 (date) "Linux man-pages (unreleased)"
man7/pid_namespaces.7:7:.TH pid_namespaces 7 (date) "Linux man-pages (unreleased)"
man7/mq_overview.7:6:.TH mq_overview 7 (date) "Linux man-pages (unreleased)"
man7/sock_diag.7:5:.TH sock_diag 7 (date) "Linux man-pages (unreleased)"
man7/iso_8859-7.7:6:.TH ISO_8859-7 7 (date) "Linux man-pages (unreleased)"
man7/system_data_types.7:7:.TH system_data_types 7 (date) "Linux man-pages (unreleased)"
man7/iso_8859-16.7:6:.TH ISO_8859-16 7 (date) "Linux man-pages (unreleased)"
man7/iso_8859-15.7:7:.TH ISO_8859-15 7 (date) "Linux man-pages (unreleased)"
man7/iso_8859-3.7:6:.TH ISO_8859-3 7 (date) "Linux man-pages (unreleased)"


See for example time_namespaces.7 and session-keyring.7.  Any reason to prefer
a hyphen for one thing but an underscore for the other?  Hmmm, I hate this lack
of consistency.

Cheers,
Alex

P.S.:  My usb with keys just died today.  I can't sign emails until I get
a new one working from a copy.  :(

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

Re: '-' vs '\-' in TH (man(7))

[Lennart Jablonka]

Quoth Alejandro Colomar:
>$ grep -rn '^\.TH [^ ]*-' man*
>man5/proc_sysrq-trigger.5:7:.TH proc_sysrq-trigger 5 (date) "Linux man-pages (unreleased)"
>man7/man-pages.7:11:.TH man-pages 7 (date) "Linux man-pages (unreleased)"
>man7/iso_8859-10.7:6:.TH ISO_8859-10 7 (date) "Linux man-pages (unreleased)"
>man7/iso_8859-8.7:8:.TH ISO_8859-8 7 (date) "Linux man-pages (unreleased)"
>man7/iso_8859-9.7:6:.TH ISO_8859-9 7 (date) "Linux man-pages (unreleased)"
>man7/rtld-audit.7:8:.TH RTLD-AUDIT 7 (date) "Linux man-pages (unreleased)"
>man7/bpf-helpers.7:30:.TH "BPF-HELPERS" 7 "2023-04-11" "Linux v6.2"
>man7/iso_8859-14.7:6:.TH ISO_8859-14 7 (date) "Linux man-pages (unreleased)"
>man7/user-keyring.7:6:.TH user-keyring 7 (date) "Linux man-pages (unreleased)"
>man7/koi8-u.7:8:.TH KOI8-U 7 (date) "Linux man-pages (unreleased)"
>man7/iso_8859-11.7:8:.TH ISO_8859-11 7 (date) "Linux man-pages (unreleased)"
>man7/iso_8859-1.7:8:.TH ISO_8859-1 7 (date) "Linux man-pages (unreleased)"
>man7/iso_8859-6.7:6:.TH ISO_8859-6 7 (date) "Linux man-pages (unreleased)"
>man7/persistent-keyring.7:6:.TH persistent-keyring 7 (date) "Linux man-pages (unreleased)"
>man7/signal-safety.7:6:.TH signal-safety 7 (date) "Linux man-pages (unreleased)"
>man7/thread-keyring.7:6:.TH thread-keyring 7 (date) "Linux man-pages (unreleased)"
>man7/iso_8859-4.7:6:.TH ISO_8859-4 7 (date) "Linux man-pages (unreleased)"
>man7/process-keyring.7:6:.TH process-keyring 7 (date) "Linux man-pages (unreleased)"
>man7/iso_8859-2.7:9:.TH ISO_8859-2 7 (date) "Linux man-pages (unreleased)"
>man7/utf-8.7:10:.TH UTF-8 7 (date) "Linux man-pages (unreleased)"
>man7/armscii-8.7:6:.TH ARMSCII-8 7 (date) "Linux man-pages (unreleased)"
>man7/iso_8859-13.7:6:.TH ISO_8859-13 7 (date) "Linux man-pages (unreleased)"
>man7/iso_8859-5.7:6:.TH ISO_8859-5 7 (date) "Linux man-pages (unreleased)"
>man7/koi8-r.7:6:.TH KOI8-R 7 (date) "Linux man-pages (unreleased)"
>man7/session-keyring.7:6:.TH session-keyring 7 (date) "Linux man-pages (unreleased)"
>man7/user-session-keyring.7:6:.TH user-session-keyring 7 (date) "Linux man-pages (unreleased)"
>man7/iso_8859-7.7:6:.TH ISO_8859-7 7 (date) "Linux man-pages (unreleased)"
>man7/iso_8859-16.7:6:.TH ISO_8859-16 7 (date) "Linux man-pages (unreleased)"
>man7/iso_8859-15.7:7:.TH ISO_8859-15 7 (date) "Linux man-pages (unreleased)"
>man7/iso_8859-3.7:6:.TH ISO_8859-3 7 (date) "Linux man-pages (unreleased)"
>
>
>Should the '-' in e.g. UTF-8 be hyphen, or should it be a minus?  Are all of
>these hyphens?  And if so, why would a hyphen belong there?

It should be a hyphen.   All of these are hyphens.   A minus sign 
would belong if it was math stuff.   A “Unix dash” (being the same 
character as a minus sign) would belong if those were not names 
for use in prose but names to be interpreted by the software, that 
requires the use of hyphen-minus.   Your programs won’t accept 
command line options introduced by U+2010 ‐ HYPHEN.   Your program 
called fun-program won’t be executed when typing fun‐program with 
U+2010.   Otherwise (and beside its use in NAME), there is hardly 
any reason to use \-.

Perhaps an argument could be made about the copypastability of man 
page titles.   I don’t want to make it and would disagree with it.   
Unless the thing you describe explicitly contains a hyphen-minus, 
don’t use \-.

Re: '-' vs '\-' in TH (man(7))

[G. Branden Robinson]

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

Hi Alex,

I have divided feelings about this issue.

At 2023-08-20T21:10:52+0200, Alejandro Colomar wrote:
> I just noticed that the Linux man-pages use '-' in TH.  That's
> surprising to me, as Michael was careful to use '\-' correctly.
> 
> In the documentation, I couldn't find anything that says TH
> should be different than anywhere else, and so I'd expect he
> would have used it there.
> 
> $ grep -rn '^\.TH [^ ]*-' man* | wc -l
> 30
> $ grep -rn '^\.TH [^ ]*\\-' man* | wc -l
> 0
> 
> Was it just an oversight, or are there any obscure reasons to do
> that?

At 2023-08-20T15:51:04-0600, Brian Inglis wrote:
> Those are just normal *hyphens* *within* the page title command

...not a command.  When a Unix command name has a hyphen-minus in it's
name, that's certainly what you want to get when you cut and paste from
the page title.

'Course, back in the days of screaming capitalized page
titles, it was easier to not take those literally.  And most of the
examples on _my_ system seem to have both hard-coded screaming caps and
Unicode-General-Punctuation-Block-destined hyphens.

And whatever its representation in the man page sources, that character
is going to be represented on the _file system_ as U+002D hyphen-minus.

> /function/...  name; perhaps you are thinking of '\-' used as a
> *dash*(/minus) after the page title command/function/... name
> following .SH NAME in all 1111 files?

Naw, he wasn't.

> See groff_char(7):
> 
> "For best results in roff systems, use the “−” character in input
> outside an escape sequence only to mean a hyphen, as in the phrase
> “long-term”. For a minus sign in running text or a Unix command-line
> option dash, use \− (or \[−] in groff if you find it helps the clarity
> of the source document)."...

I stand by this advice, but it doesn't reach the question of how "-"
characters in Unix file names should be represented.

At 2023-08-21T00:41:29+0200, Alejandro Colomar wrote:
> Are they all?  I see they are all in man7 (there's one in man5, which
> is my bad, actually), so it's more likely that the names don't
> represent some identifier that has a minus sign in it, however, I
> still have doubts.
[many examples snipped]
> See for example time_namespaces.7 and session-keyring.7.  Any reason
> to prefer a hyphen for one thing but an underscore for the other?

An underscore would seem to wriggle free of _this_ problem.

At 2023-08-21T00:59:56+0000, Lennart Jablonka wrote:
> > Should the '-' in e.g. UTF-8 be hyphen, or should it be a minus?
> > Are all of these hyphens?  And if so, why would a hyphen belong
> > there?
> 
> It should be a hyphen.   All of these are hyphens.   A minus sign
> would belong if it was math stuff.

Your perspective is consistent with troff's design until man pages enter
the fray.

> A “Unix dash” (being the same character as a minus sign),

In small character encodings, yes.  In Unicode?  No.

> would belong if those were not names for use in prose but names to be
> interpreted by the software, that requires the use of hyphen-minus.
> Your programs won’t accept command line options introduced by U+2010 ‐
> HYPHEN.   Your program called fun-program won’t be executed when
> typing fun‐program with U+2010.   Otherwise (and beside its use in
> NAME),

My understanding is that other dashes are accepted there by
makewhatis(8) and mandb(8) programs.  lexgrog(1), which is used by
man-db mandb(8), in particular parses them fine.

> there is hardly any reason to use \-.

In man pages, especially of Unix commands, the exception seems to nearly
swallow the rule.

> Perhaps an argument could be made about the copypastability of man
> page titles.   I don’t want to make it and would disagree with it.
> Unless the thing you describe explicitly contains a hyphen-minus,
> don’t use \-.

Here's an exercise for the reader.

$ (cd /usr/share/man/man1 && ls -c *-*)

Regards,
Branden

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