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'.
Attachment:
signature.asc
Description: PGP signature
