Re: [PATCH v2 1/2] fanotify.7, fanotify_init.2: Document FAN_REPORT_TARGET_FID

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

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

Hi Amir!

On 6/26/22 17:31, Amir Goldstein wrote:
> 
> Alex,
> 
> I hope the reviewers won't mind, but because we are adding more
> reasons of ENOTDIR
> later on, I think this section would look better with every ENOTDIR
> reason in a paragraph
> of its own, like this:

That makes sense.  Other pages also do that already, so it's fine for me.

I must say that it was a bit weird to me a long time ago, when I started 
reading manual pages, and I've also received a report recently from 
someone who thought the same, but now it reads normal to me, so I'll 
assume it's just part of the learning curve of learning to read man 
pages.  Probably having a lot of text together in a single entry would 
be even worse from the readability point of view, so go ahead.

For the review, as long as you don't change existing code, you can do it 
all in one commit.  If you're refactoring text at the same time as 
adding new text, I'd prefer if you break the commit into 2, the first 
one being the refactor, to make it easy to review (same as kernel rules, 
I guess).

> 
> .TP
> .B ENOTDIR
> .I flags
> contains
> .BR FAN_MARK_ONLYDIR ,
> and
> .I dirfd
> and
> .I pathname
> do not specify a directory.
> .TP
> .B ENOTDIR
> The fanotify group was initialized with flag
> .BR FAN_REPORT_TARGET_FID ,
> .I mask
> contains directory entry modification events
> (e.g.,
> .BR FAN_CREATE ,
> .BR FAN_DELETE ) ,
> and
> .I dirfd
> and
> .I pathname
> do not specify a directory.
> .TP
> 
> The end result [1] after the following FAN_RENAME patch looks like this:
> 
>         ENOTDIR
>                flags contains FAN_MARK_ONLYDIR, and dirfd and pathname
> do not specify a directory.
> 
>         ENOTDIR
>                mask contains FAN_RENAME, and dirfd and pathname do not
> specify a directory.
> 
>         ENOTDIR
>                The fanotify group was initialized with flag
> FAN_REPORT_TARGET_FID, mask contains
>                directory entry modification events (e.g., FAN_CREATE,
> FAN_DELETE), and dirfd and
>                pathname do not  specify  a directory.
> 
> BTW, I could not figure out what causes the line break after ENOTDIR.
> Other errors look similarly formatted and don't have this line break.

That's normal.  There must be at least a space between the tag and the 
paragraph in a tagged paragraph (.TP), so if there's not room for the 
space, it breaks, but it's normal.

groff_man(7):
        .TP [indentation]
               Set a paragraph with a leading tag,  and  the  re‐
               mainder of the paragraph indented.  The input line
               following this macro, known as the tag, is printed
               at  the  current  left margin.  Subsequent text is
               indented by indentation, if specified,  and  by  a
               default amount otherwise; see subsection “Horizon‐
               tal and vertical spacing” below.

               If  the tag is not as wide as the indentation, the
               paragraph starts on the same line as the  tag,  at
               the  applicable  indentation, and continues on the
               following lines.  Otherwise, the descriptive  part
               of  the paragraph begins on the line following the
               tag.

Thanks,

Alex

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

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