Re: [PATCH v2 0/2] userfaultfd.2: Update to latest

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 4736 bytes --]

Hi Peter!

On 6/7/22 16:29, Peter Xu wrote:
>> "registered" is not acting as an adjective, but as a verb.
> 
> I wanted to use it as an adjective, but after you questioned this one I'm
> not sure any more on my English school knowledges. :)
> 
>> Maybe Peter was confused by that; I didn't consider that option.  I'm
>> actually surprised that you were, Branden, but I guess it was just a
>> neuron going crazy, as mine with \c the other day :p
>>
>>
>>>
>>>> It's always challenging for me to grasp how you prefer the newlines
>>>> are made, but anyway below changes looks good to me.
>>
>> Sorry, Peter.  I'll take that into account, and try to help as much as I
>> can.
> 
> You're greatly helpful start from the beginning, and I just hope you can
> still bare with me. :-)

Sure! :)


> 
>> Apart from what Branden has already added to this thread, the
>> following man-pages commit has some more details, quoted from B. W.
>> Kernighan, and may help you understand what I want:
>>
>> <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/man7/man-pages.7?h=alx/main&id=6ff6f43d68164f99a8c3fb66f4525d145571310c>
>>
>> I have a long-standing discussion with Branden regarding how much should I
>> push for semantic newlines.  The origin of using semantic newlines is only
>> to simplify diffs (and it does that very well), but for some reason, my
>> brain reads the text better too when organized that way, as opposed to
>> normal prose-like text flow.  There I seem to disagree with Branden, who
>> prefers to read my emails as if they were a book.  Maybe I need semantic
>> newlines to understand the text better, because there are a lot of technical
>> terms that I don't know, and having less load on my brain (because I don't
>> need to calculate phrase boundaries) makes it easier; it's especially useful
>> when text is under development, where it may have mistakes that make it even
>> more difficult to read.
>>
>> But, just do what you can.  I'll try to do the rest, and ask you if I don't
>> understand something.
> 
> Yes IMHO that'll be the best way to go with the rest of the community too,
> because afaict not all community developers will be able to quickly get
> used to the rules on man page repository - you're working with a bunch of
> people using in most cases C compilers which has a much looser syntax!
> 
> It'll be great if you could help tune the bits after the content being
> contributed by others as long as the modified version has the correct
> meanings.  Not sure whether it'll have scaling problem but hopefully the
> man pages won't be updated drastically so it won't overload you so easily.
 >
 > Thanks again for all the helps,
 >

Yes, if I just fix all of them, programmers never learn how to write 
proper manual pages, and I'll have to fix them forever (and sometimes, 
when I recevie huge patches, such as new pages, it doesn't scale very 
well).  But I can't put too much pressure either.  It's difficult, but I 
try to adapt to each of you.


In this case, I applied both of your patches, and on top of them, I 
applied the following one.

Cheers!

Alex

---

     userfaultfd.2: Minor tweaks to Peter's patches

     Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
     Cc: Peter Xu <peterx@redhat.com>

diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2
index 9b5ec0358..0c0a4f687 100644
--- a/man2/userfaultfd.2
+++ b/man2/userfaultfd.2
@@ -62,11 +62,11 @@ flag in
  .BR open (2).
  .TP
  .B UFFD_USER_MODE_ONLY
-This is an userfaultfd specific flag that was introduced since Linux 5.11.
-When set, the userfaultfd object will only be able to handle page faults
-originated from the userspace on the registered regions.
-When a kernel originated fault was triggered on the registered range with
-this userfaultfd, a
+This is an userfaultfd-specific flag that was introduced in Linux 5.11.
+When set, the userfaultfd object will only be able to handle
+page faults originated from the user space on the registered regions.
+When a kernel-originated fault was triggered
+on the registered range with this userfaultfd, a
  .B SIGBUS
  signal will be delivered.
  .PP
@@ -277,8 +277,9 @@ ioctl against the feature bit
  .B UFFD_FEATURE_PAGEFAULT_FLAG_WP
  before using this feature.
  .PP
-Since Linux 5.19, the write-protection mode was also supported on shmem 
and hugetlbfs
-memory types.
+Since Linux 5.19,
+the write-protection mode was also supported on
+shmem and hugetlbfs memory types.
  It can be detected with the feature bit
  .BR UFFD_FEATURE_WP_HUGETLBFS_SHMEM .
  .PP


-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

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