Hi Alex,
Short answer: take the patch. :)
At 2023-03-12T12:02:04+0100, Alejandro Colomar wrote:
> Should I apply this patch? I'm not sure if the variable part should
> be bold because it's part of a heading or roman because it's variable
> part within italics. How would you format it?
> diff --git a/man7/time_namespaces.7 b/man7/time_namespaces.7
> index 708099934..8c31b5f95 100644
> --- a/man7/time_namespaces.7
> +++ b/man7/time_namespaces.7
[...]
> -.SS /proc/\fIpid\fP/timens_offsets
> +.SS \fI/proc/\fPpid\fI/timens_offsets\fP
[...]
> diff --git a/man7/user_namespaces.7 b/man7/user_namespaces.7
> index 6647b02bf..737dd54ad 100644
> --- a/man7/user_namespaces.7
> +++ b/man7/user_namespaces.7
[...]
> -.SS The /proc/\fIpid\fP/setgroups file
> +.SS The \fI/proc/\fPpid\fI/setgroups\fP file
Long answer:
This is one of those cases where man(7) isn't expressive enough to suit
me, for precisely the reason you identify. Because we largely don't
have semantic tags, we can't mark "pid" semantically and let the context
determine the styling.
I prefer the former to the latter, and would apply the patch. In groff
1.23.0 (which still doesn't have its final tag :( ), the man(7) macro
package remaps the `I` (italic) style to `BI` (bold+italic) if it is
available and the font being used for (subsection) headings is
configured to be bold. (The heading font has been configurable via the
`HF` string since groff 1.19, February 2004.)
So what will happen here, in groff 1.23 and the future, is that the file
name will be rendered mostly in bold italics, but the variable portion
will appear in upright bold.
However, if it were my man page, I might recast the headings entirely to
describe the files--or rather their purpose--in English, avoiding both
the use of escape sequences and concern with typeface changes.
.SS "Setting offsets in time name spaces" \" yes, name spaces (sic)
.SS "Enabling processes to change effective group membership" \" ?
But I will understand if you want to stick with the proposed patch, for
two reasons.
(1) Adopting my proposal means getting into another word-division fight
with C programmers (perhaps influenced by C++ keywords) who port
their identifier typography directly into English without
alteration, as also discussed on linux-man in the past day or so;
and
(2) I've inverted the discursive orientation of the material.
Generally, I think (sub)section headings in a man page should be
_broadly categorical_ or should address themselves to operations a
user wants to perform, or tasks they want to achieve. Another
popular approach, seen here, is to use the man page as a sort of
index for file system objects, so people reading the man page in
full or trying to answer the question "what does this file do?" will
be more readily enlightened.
Both of these are legitimate purposes, and the latter is easier to
write, which I think partly explains its popularity among those who
are tasked by others with writing documentation and would prefer to
get back to hacking. If your new kernel subsystem creates
/proc/$$/foo/{bar,baz,qux} for every process, you can proclaim your
section 7 man page "done" once you've written a paragraph for each
of these items. Your manager will eagerly sign off so as to get you
back to more "productive" work, like performance tuning so that they
can in turn try to impress their own bosses with a chart on a
PowerPoint slide. (Bonus points if they characterize the shape of
_any_ curve as "exponential".)
And it is better than nothing. But as a rule I think it is better
to present a catalog in a tagged list, and spend time thinking about
what it is that conceptually unifies that list. Doing so tends to
lead to an introductory paragraph preceding the list that makes it
clear to everyone why the list is present and when people should
care about it. Observe how many man pages pass immediately from a
(sub)section heading to one of these lists.[1] This is often a
tell-tale sign that the unifying thinking, the writer's craft of
getting above the worm's-eye view of technical detail, has been
omitted. I won't claim that groff's own man pages are perfect in
this respect. They never will be, but maybe I can improve them
further given another five years...
Regards,
Branden
[1] (groff war story)
As I recall, a few years ago Ingo Schwarze once lobbied me to take
out the "Options" sections of groff's section 1 man pages using a
similar argument, claiming that options should be motivated and
discussed within the "Description" section in a more organic manner.
(And I did in fact change our nroff(1) page to do this, to test out
his advice and because GNU nroff is a wrapper--nearly all its
options are synonymous with groff(1) or troff(1) options). He's not
wrong, but because GNU programs tend to have many options (also a
defect, in his view and others', like Rob Pike[2]) and because man
pages are so frequently consulted to determine what a command option
is for, I decided I could not dispense with them.
Another reform to groff's man pages that I undertook was to begin
shifting more discursive material earlier in the page. A popular
approach to man page organization for section 1 and 8 pages is to
have a single paragraph of overview followed immediately by the
"Options" section, which promptly starts referring to technical
details, sometimes obscure ones, that the reader must already
comprehend or which are not properly presented until later in the
document. As you may suspect, I dislike that. Ingo felt that if I
was going to have an Options section at all, I should keep it up
high so it would at least start on the first pager screen--I think
this was meant for the convenience of the expert reader. But I
think this approach sacrifices too much accessibility to the
learner. One should be able to read a man page linearly and feel
one's understanding of the topic building. Some people would retort
that man pages are meant as a reference, not a tutorial. My counter
is that while they generally aren't tutorials, terming one's page a
"reference" does not excuse one from covering the domain-specific
knowledge that another needs to acquire to competently use the
software at issue. I think the boot(8) and crash(8) pages from the
V7 Unix manual (1979) are examples, from an esteemed source, of how
discursive--nigh-on tutorial--a man page of good reputation can get.
My opinion is that the reader who is already familiar with the
page's material can type "/Options" in their pager to navigate there
if they are in a hurry. Alternatively, thanks to Deri James, they
can view man pages as PDFs, open up the navigation pane of their PDF
viewer, and click on "Options". A good conversion to HTML enables
this, too.
[2] http://harmful.cat-v.org/cat-v/
Attachment:
signature.asc
Description: PGP signature
