Hi Alex,
Sorry for my delay in responding.
At 2024-06-19T22:06:56+0200, Alejandro Colomar wrote:
> Let's say I write the manual page for git-diff(1).
> The file name is <man1/git-diff.1>.
>
> In TH, should I use \- or just -?
>
> .TH git\-diff 1 2024-06-19 git
> .TH git-diff 1 2024-06-19 git
This is a style choice. The formatter itself doesn't care. I don't
have a strong prescription in this area, just some observations.
1. The difference matters only on output devices that distinguish
hyphens from minus signs.
2. A problem arises from the difference usually only when someone
attempts to copy-and-paste text from a man page to a shell prompt or
text editor, and gets the "wrong" kind of "dash".
3. In general, Unix systems are case-sensitive.
4. I doubt that there is a tradition of copy-and-pasting the man page
name from the rendered document header because there is _another_
tradition, still widely seen, of rendering the document title in
full caps. This tradition came from the Bell Labs CSRC in the
1970s, and obviously those folks knew point #3. (Also they
interacted with the system using teletypewriters, so they had no
"copy-and-paste" experiences.)
5. groff 1.23 makes the foregoing capitalization behavior user-
configurable via a register.[1] So you, the page author, don't know
whether the reader will see your document title in full caps or not.
If they do, copy-and-paste will be defeated anyway ("man GIT-DIFF").
Consequently, my personal judgment would be to not bother with `\-` in
the first argument to the `TH` macro. But I can't say that things are
likely to go wrong if you _do_ bother. Odds are it simply won't suffice
to make the document title copy-and-paste-able for some of your
audience, and a big part of that audience will never notice either way.
> How about SH Name?
I reason differently about this case.
> .SH Name
> git\-diff \- Show changes between commits, commit and working tree, etc
>
> .SH Name
> git-diff \- Show changes between commits, commit and working tree, etc
In the "Name" section of a man page, we start with a comma-separated
list of topics, each of which is supposed to identify a component of the
system. In sections 1, 6, and 8 (commands), we seldom see the "list"
aspect of this specification exercised (or rather, the list is a
singleton). But in sections 2 and 3, lists of function names (and
sometimes C objects [variables]) are common. Since these all name
things you might type that exist somewhere on the system, as programs
resolved by $PATH search or as symbols in object files, or as macros the
compiler will recognize, the argument for marking them up as "literals",
with boldface and `\-` to get hyphen-minus characters, is stronger.[2]
> I'm worried especially about the Name section, in case that \-
> interferes with man-db.
There is no need to worry when you can easily put the question to an
empirical test. Run lexgrog(1) on your document to see what it says.
$ lexgrog ./man/roff.7.man
./man/roff.7.man: "roff - concepts and history of roff typesetting"
$ lexgrog - <<EOF
.TH git-diff 1 2024-06-24 "groff test suite"
.SH Name
git\-diff \- show changes between commits, commit and working tree, etc.
EOF
-: "git-diff - show changes between commits, commit and working tree, etc."
man-db seems happy to me.
Regards,
Branden
[0] Secret footnote: The practices I suggested above also translate well
to mdoc(7) practice, where the `Dt` macro defines the "document
title", and `Nm` calls designate "names" of topics the page
discusses. I don't advocate mdoc(7) over man(7), but I also do not
wish to create unnecessary impedance mismatches between them.
[1] ...which is defeated if the document shouts its title in full caps
in its *roff source. But here is the configuration control.
groff_man(7):
-rCT=1 Set the man page identifier (the first argument to .TH) in
full capitals in headers and footers. This transformation
is off by default because it discards case distinction
information.
People who aren't accustomed to viewing man page documents with
"groff" or "nroff", but do use man-db, would likely put the
foregoing command-line option into $MANROFFOPT. An approach that
works for any (groff 1.23) system regardless of man librarian is to
edit the "man.local" file to set the register (`.nr CT 1`). See
section "Files" of groff_man(7). (mandoc(1) doesn't respect this
and likely never will; its maintainer scorns configurability.)
[2] Since `-` isn't a valid character in C identifiers, that aspect of
the discussion doesn't hold for that language. But I am trying to
reason ecumenically, and command names in kebab-case are well known.
Attachment:
signature.asc
Description: PGP signature
