linux-kernel.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
To: "Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>
Cc: "Mickaël Salaün" <mic@digikod.net>,
	"Jann Horn" <jannh@google.com>,
	"Jonathan Corbet" <corbet@lwn.net>,
	"Kees Cook" <keescook@chromium.org>,
	"Randy Dunlap" <rdunlap@infradead.org>,
	"Vincent Dagonneau" <vincent.dagonneau@ssi.gouv.fr>,
	landlock@lists.linux.dev, linux-kernel@vger.kernel.org,
	linux-man@vger.kernel.org, linux-security-module@vger.kernel.org,
	"Mickaël Salaün" <mic@linux.microsoft.com>,
	"Michael Kerrisk" <mtk.manpages@gmail.com>
Subject: Re: [PATCH v2 1/4] landlock.7: Add a new page to introduce Landlock
Date: Sat, 31 Jul 2021 23:48:23 +1000	[thread overview]
Message-ID: <20210731134821.qh5ol3wenvb73cjw@localhost.localdomain> (raw)
In-Reply-To: <e88fe0d9-1330-3de4-53e1-4b72360ce7d3@gmail.com>

[-- Attachment #1: Type: text/plain, Size: 3649 bytes --]

Hi, Alex,

[man, that CC list makes me cringe--this is all style issues and groff
release history, skip freely]

At 2021-07-31T12:51:30+0200, Alejandro Colomar (man-pages) wrote:
> Hi Branden, Mickaël,
> > 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.
[...]
> Hmmmm, I can't find that text on my Debian Sid (with a bit of experimental)
> groff_man(7).  Not even in the SEE ALSO.

That's because Debian is still shipping groff 1.22.4, even in unstable.
That's not shocking; I think Colin Watson was hesitant to ship a release
candidate and that was all the groff team had ready at the time.  (I'm
the most active developer but not the project lead or release manager;
I've shied away from those responsibilities.)

> Re-reading this, we've been doing it wrong (as you pointed out in
> another thread) with macro names with variable part.

I do think it is wise to have a markup distinction between constant and
variable parts of C (or C preprocessor) symbol names.  Admittedly, font
style distinctions can get lost in terminal copy-and-paste, but we can't
solve everything in plain text alone.

> I wasn't very convinced by the current usage of the man pages, but it
> was already current, so I just followed it :/
> 
> I'll try to follow this from now.

The man-pages project has some style rules for visible output that are
not in alignment with what groff does, but the only one that comes to
mind is the style used for man page names (man-pages: bold; groff:
italics).  I have a plan for resolving that on the rendering end[1].

> Ahh, I missed this text, as it was neither under .I nor .IR, and only
> had a fast read of the page.  The 3rd paragraph hints that you should
> only use .IR when really needed, and use .I otherwise.  But someone
> new to man-pages, who probably did never read this page (or read some
> specific paragraphs of it when needed), and found the extensive (and
> somewhat incorrect) usage of .IR in place of .I in the current man
> pages, might be confused by all of that inconsistency and hard-to-find
> (except by those who already know where it is (reference to Pirates of
> the Caribbean intended :) )) information.

Yes, it would really help if we (groff) could do a release.  :-/

> > I'd appreciate feedback from anyone on how I can improve the above.
> 
> I think it's great.  But unless one reads the page with some time (and
> not only the bullets), one might think that the man page is
> incomplete.  Maybe groff_man_style(7) is better suited for newbies,
> but I can't tell...  I couldn't find it.

It's in groff Git and in the man-pages curated collection,
<https://man7.org/linux/man-pages/man7/groff_man_style.7.html>.

Michael apparently re-pulls from groff Git HEAD every time he does a
man-pages release, which makes the groff man pages massively more up to
date (by 2.5 years and counting) than what most distributions have.

> I'm not sure, but maybe (I always get confused by these things)?:
> 
> [
> each _of the_ OverlayFS layers and merge hierarchies _is_ standalone and
> _contains_
> _its_ own set of files and directories,
> which is different from bind mounts.
> ]
> 
> And still I'm not sure about the last "mounts".

Yes, I think that's an improvement, and "bind mounts" could be made
singular: "a bind mount".

Regards,
Branden

[1] https://lists.gnu.org/archive/html/groff/2020-08/msg00068.html

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

  reply	other threads:[~2021-07-31 13:48 UTC|newest]

Thread overview: 17+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-07-12 15:57 [PATCH v2 0/4] Add Landlock man pages Mickaël Salaün
2021-07-12 15:57 ` [PATCH v2 1/4] landlock.7: Add a new page to introduce Landlock Mickaël Salaün
2021-07-29 14:56   ` Alejandro Colomar (man-pages)
2021-07-29 22:01     ` G. Branden Robinson
2021-07-29 22:34       ` Alejandro Colomar (man-pages)
2021-07-30 12:15     ` Mickaël Salaün
2021-07-30 12:41       ` Alejandro Colomar (man-pages)
2021-07-30 12:59         ` Alejandro Colomar (man-pages)
2021-07-30 14:32           ` Mickaël Salaün
2021-07-31  0:15           ` G. Branden Robinson
2021-07-31 11:02             ` Alejandro Colomar (man-pages)
2021-07-30 23:39       ` G. Branden Robinson
2021-07-31 10:51         ` Alejandro Colomar (man-pages)
2021-07-31 13:48           ` G. Branden Robinson [this message]
2021-07-12 15:57 ` [PATCH v2 2/4] landlock_create_ruleset.2: Document new syscall Mickaël Salaün
2021-07-12 15:57 ` [PATCH v2 3/4] landlock_add_rule.2: " Mickaël Salaün
2021-07-12 15:57 ` [PATCH v2 4/4] landlock_restrict_self.2: " Mickaël Salaün

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20210731134821.qh5ol3wenvb73cjw@localhost.localdomain \
    --to=g.branden.robinson@gmail.com \
    --cc=alx.manpages@gmail.com \
    --cc=corbet@lwn.net \
    --cc=jannh@google.com \
    --cc=keescook@chromium.org \
    --cc=landlock@lists.linux.dev \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux-man@vger.kernel.org \
    --cc=linux-security-module@vger.kernel.org \
    --cc=mic@digikod.net \
    --cc=mic@linux.microsoft.com \
    --cc=mtk.manpages@gmail.com \
    --cc=rdunlap@infradead.org \
    --cc=vincent.dagonneau@ssi.gouv.fr \
    --subject='Re: [PATCH v2 1/4] landlock.7: Add a new page to introduce Landlock' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).