From: Dave Martin <Dave.Martin@arm.com>
To: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
Cc: linux-arch@vger.kernel.org, linux-man@vger.kernel.org,
Catalin Marinas <catalin.marinas@arm.com>,
Mark Rutland <mark.rutland@arm.com>,
Vincenzo Frascino <vincenzo.frascino@arm.com>,
Will Deacon <will@kernel.org>,
linux-arm-kernel@lists.infradead.org
Subject: Re: [PATCH v3 0/2] prctl.2 man page updates for Linux 5.6
Date: Mon, 20 Jul 2020 17:52:07 +0100 [thread overview]
Message-ID: <20200720165205.GI30452@arm.com> (raw)
In-Reply-To: <c17e330c-69f7-da7a-feae-cb8b8f5d7ea0@gmail.com>
On Mon, Jun 29, 2020 at 01:52:24PM +0200, Michael Kerrisk (man-pages) wrote:
> Hi Dave,
>
> On 6/24/20 7:36 PM, Dave Martin wrote:
> > A bunch of updates to the prctl(2) man page to fill in missing
> > prctls (mostly) up to Linux 5.6 (along with a few other tweaks and
> > fixes).
> >
> > Patches from the v2 series [1] that have been applied or rejected
> > already have been dropped.
> >
> > All that remain here now are the SVE and tagged address ABI controls
> > for arm64.
> >
> >
> >
> > [1] https://lore.kernel.org/linux-man/1590614258-24728-1-git-send-email-Dave.Martin@arm.com/
> >
> >
> > Dave Martin (2):
> > prctl.2: Add SVE prctls (arm64)
> > prctl.2: Add tagged address ABI control prctls (arm64)
> >
> > man2/prctl.2 | 331 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
> > 1 file changed, 331 insertions(+)
> Thanks. I've pushed these changes to master now.
Thanks -- btw I finally got around to reviewing master, and noted a few
editorial changes that man-pages(7) does not make any statement about:
"arg1, arg2, and arg3"
Do you strictly prefer the command before "and" here?
Conventionally, the final comma would typically be omitted in
prose, except where the list members are complex enough that the
command is required to assist parsing. However, lists of formal
arguments are not quite vanilla prose.
"Providing that" -> "Provided that"
Any particular rationale here?
"error EFOO" -> "the error EFOO"
Is this a rule, in general?
.IP \(bu 2
I assumed that specifying an explicit indentation amount would
be fragile. Going with the default behaviour also tends to
result in a more consistent appearance. Do you have any
recommandations in this area?
Do you have rules about the order to use bullet symbols? I tend
to avoid \(bu if possible, since while it's "correct", nroff can
render it nastily as an unadorned letter "o" (e.g., with -Tascii
or LC_CTYPE=C). This is particlarly annoying if the indent is
<= 2, since then the "o" tends to be visually swallowed by the
following text (i.e., to a casual glance it looks like a word,
particlarly if the following text is not capitalised). Perhaps
this is a bad glyph substitution decision in nroff rather than
something that should be fixed in the man-pages source, but the
man-pages source may be easier to fix...
There is already inconsistency here: there are may top-level
lists using ".IP *" in prctl.2, and plenty of places where the
default indentation is used.
Should any of these be written up in man-pages(7), or is there a checker
than can detect them?
I wan't to minimise the amount of tweaking you have to do when merging
patches.
Cheers
---Dave
next prev parent reply other threads:[~2020-07-20 16:52 UTC|newest]
Thread overview: 16+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-06-24 17:36 [PATCH v3 0/2] prctl.2 man page updates for Linux 5.6 Dave Martin
2020-06-24 17:36 ` Dave Martin
[not found] ` <1593020162-9365-1-git-send-email-Dave.Martin-5wv7dgnIgG8@public.gmane.org>
2020-06-24 17:36 ` [PATCH v3 1/2] prctl.2: Add SVE prctls (arm64) Dave Martin
2020-06-24 17:36 ` Dave Martin
2020-06-26 11:23 ` Michael Kerrisk (man-pages)
2020-06-24 17:36 ` [PATCH v3 2/2] prctl.2: Add tagged address ABI control " Dave Martin
2020-06-24 17:36 ` Dave Martin
[not found] ` <1593020162-9365-3-git-send-email-Dave.Martin-5wv7dgnIgG8@public.gmane.org>
2020-06-26 11:23 ` Michael Kerrisk (man-pages)
2020-06-26 11:23 ` Michael Kerrisk (man-pages)
2020-06-29 11:52 ` [PATCH v3 0/2] prctl.2 man page updates for Linux 5.6 Michael Kerrisk (man-pages)
2020-06-29 11:52 ` Michael Kerrisk (man-pages)
2020-07-20 16:52 ` Dave Martin [this message]
[not found] ` <20200720165205.GI30452-5wv7dgnIgG8@public.gmane.org>
2020-07-20 21:31 ` Michael Kerrisk (man-pages)
2020-07-20 21:31 ` Michael Kerrisk (man-pages)
2020-07-29 14:56 ` Dave Martin
2020-08-04 12:52 ` Michael Kerrisk (man-pages)
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=20200720165205.GI30452@arm.com \
--to=dave.martin@arm.com \
--cc=catalin.marinas@arm.com \
--cc=linux-arch@vger.kernel.org \
--cc=linux-arm-kernel@lists.infradead.org \
--cc=linux-man@vger.kernel.org \
--cc=mark.rutland@arm.com \
--cc=mtk.manpages@gmail.com \
--cc=vincenzo.frascino@arm.com \
--cc=will@kernel.org \
/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
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).