Message-ID: <20210730233931.lbtq67esmeuo4o6d@localhost.localdomain>
Date:   Sat, 31 Jul 2021 09:39:32 +1000
From:   "G. Branden Robinson" <g.branden.robinson@...il.com>
To:     Mickaël Salaün <mic@...ikod.net>
Cc:     "Alejandro Colomar (man-pages)" <alx.manpages@...il.com>,
        Jann Horn <jannh@...gle.com>, Jonathan Corbet <corbet@....net>,
        Kees Cook <keescook@...omium.org>,
        Randy Dunlap <rdunlap@...radead.org>,
        Vincent Dagonneau <vincent.dagonneau@....gouv.fr>,
        landlock@...ts.linux.dev, linux-kernel@...r.kernel.org,
        linux-man@...r.kernel.org, linux-security-module@...r.kernel.org,
        Mickaël Salaün <mic@...ux.microsoft.com>,
        Michael Kerrisk <mtk.manpages@...il.com>
Subject: Re: [PATCH v2 1/4] landlock.7: Add a new page to introduce Landlock

Hi, Mickaël!

I'm going to rearrange your message to reply to it to put the shortest
point first, as I am nervous of people tiring of my info dumps,
especially with such an efflorescent CC list.

At 2021-07-30T14:15:48+0200, Mickaël Salaün wrote:
> >> +The rule will only allow reading the file hierarchy
> >> +.IR /usr .
> 
> Why ".IR" is correct here?

Because you don't want a space or a line break in the output between
"/usr" and the period.

Line breaks in *roff input usually mean "insert a word break here".[1]

[the long version]
> When do we really need .IR? Isn't `.I "foo bar"` the same as `.IR foo
> bar`? What do you use roman for?
> 
> Where can we find these preferences? The best I found was
> https://www.man7.org/linux/man-pages/man7/groff_man.7.html but it
> doesn't explain what to use. The current man pages seems to use both
> interchangeably.

This is a good news/bad news situation for me.  As the maintainer of
that man page, I'm delighted to hear that you found it the best resource
of its type.  But that you came away still not knowing when or why to
use .IR tells me I still have work to do.

One of the things I did after the groff 1.22.4 release (December 2018)
was to split groff_man(7) into two pages.  The one you've linked is the
terser reference for seasoned (perhaps salty) man page writers.  Near
the top of it you'll find this.

       This document presents the macros thematically; for those needing
       only a quick reference, the following table lists them
       alphabetically, with cross-references to appropriate subsections
       below.

       Man page authors and maintainers who are not already experienced
       groff users should consult groff_man_style(7), an expanded
       version of this document, for additional explanations and advice.
       It covers only those concepts required for man page document
       maintenance, and not the full breadth of the groff typesetting
       system.

There, at <https://www.man7.org/linux/man-pages/man7/groff_man.7.html>,
I'd direct you to the following.

   Font style macros
       The man macro package is limited in its font styling options,
       offering only bold (.B), italic (.I), and roman.  Italic text is
       usually set underscored instead on terminal devices.  The .SM and
       .SB macros set text in roman or bold, respectively, at a smaller
       point size; these differ visually from regular-sized roman or
       bold text only on typesetter devices.  It is often necessary to
       set text in different styles without intervening space.  The
       macros .BI, .BR, .IB, .IR, .RB, and .RI, where “B”, “I”, and “R”
       indicate bold, italic, and roman, respectively, set their odd-
       and even-numbered arguments in alternating styles, with no space
       separating them.
[...]
       .I [text]
              Set text in italics.  If the macro is given no arguments,
              the text of the next input line is set in italics.

              Use italics for file and path names, for environment
              variables, for enumeration or preprocessor constants in C,
              for variable (user-determined) portions of syntax
              synopses, for the first occurrence (only) of a technical
              concept being introduced, for names of works of software
              (including commands and functions, but excluding names of
              operating systems or their kernels), and anywhere a
              parameter requiring replacement by the user is
              encountered.  An exception involves variable text in a
              context that is already marked up in italics, such as file
              or path names with variable components; in such cases,
              follow the convention of mathematical typography: set the
              file or path name in italics as usual but use roman for
              the variable part (see .IR and .RI below), and italics
              again in running roman text when referring to the variable
              material.
[...]
       Note what is not prescribed for setting in bold or italics above:
       elements of “synopsis language” such as ellipses and brackets
       around options; proper names and adjectives; titles of anything
       other than works of literature or software; identifiers for
       standards documents or technical reports such as CSTR #54,
       RFC 1918, Unicode 13.0, or POSIX.1-2017; acronyms; and
       occurrences after the first of a technical term or piece of
       jargon.  Again, the names of operating systems and their kernels
       are, by practically universal convention, set in roman.

       Be frugal with italics for emphasis, and particularly with bold.
       Brief runs of literal text, such as references to individual
       characters or short strings, including section and subsection
       headings of man pages, are suitable objects for quotation; see
       the \(lq, \(rq, \(oq, and \(cq escapes in subsection
       “Portability” below.

       Unlike the above font style macros, the font style alternation
       macros below accept only arguments on the same line as the macro
       call.  Italic corrections are applied as appropriate.  If space
       is required within one of the arguments, first consider whether
       the same result could be achieved with as much clarity by using
       the single-style macros on separate input lines.  When it cannot,
       double-quote an argument containing embedded space characters.
       Setting all three different styles within a word presents
       challenges; it is possible with the \c and/or \f escapes, but see
       subsection “Portability” below for caveats.
[...]
       .IR italic-text roman-text ...
              Set each argument in italics and roman, alternately.

                     This is the first command of the
                     .IR prologue .

I'd appreciate feedback from anyone on how I can improve the above.

> >> +upper layer.
> >> +From a Landlock policy point of view,
> >> +each OverlayFS layers and merge hierarchies are standalone and contains
> >> +their own set of files and directories,
> >> +which is different from bind mounts.
> > 
> > 
> > Incorrect mix of singular and plural, I think.
> 
> Is it OK with s/contains/contain/?

That's correct, but you also need s/their/its/.

A handy technique for resolving inflection/agreement problems in English
is to drop phrases from the sentence in a way that preserves its
structure; this usually makes clear what should be done.

In this case, "... Each ... contains its own set."

Native speakers screw this up even in simpler cases; e.g.,

  *"The spaces in between leave room for you and I to grow."

We get thrown by the conjunction "and", which makes the language organ
in our brain think of plural number.  But no native speaker ever commits
the error

  *"Will you buy a hamburger for I?"

unless for deliberate effect.  (Though there is probably some hamlet in
the West Midlands of England or something where this is standard. :-| )

Regards,
Branden

[1] "Usually."  In roff terms, this generalization applies to text lines
    (not control lines; that is, lines starting with a control
    character) that do not end with the output line continuation escape
    sequence, '\c'.

Download attachment "signature.asc" of type "application/pgp-signature" (834 bytes)

Powered by blists - more mailing lists