[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [PATCH] man7/: ffix

From: G. Branden Robinson
Subject: Re: [PATCH] man7/: ffix
Date: Sun, 12 Mar 2023 11:44:34 -0500

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;

(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...


[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.


Attachment: signature.asc
Description: PGP signature

reply via email to

[Prev in Thread] Current Thread [Next in Thread]