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

[Alejandro Colomar <alx@kernel.org>]

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