Re: [PATCH v4 09/10] man/man2/open_tree{,_attr}.2: document new open_tree_attr() API

[Aleksa Sarai]

On 2025-09-21, Alejandro Colomar <alx@xxxxxxxxxx> wrote:
> On Fri, Sep 19, 2025 at 11:59:50AM +1000, Aleksa Sarai wrote:
> > diff --git a/man/man2/open_tree.2 b/man/man2/open_tree.2
> > index 7f85df08b43c7b48a9d021dbbeb2c60092a2b2d4..60de4313a9d5be4ef3ff1217051f252506a2ade9 100644
> > --- a/man/man2/open_tree.2
> > +++ b/man/man2/open_tree.2
> > @@ -15,7 +15,19 @@ .SH SYNOPSIS
> >  .B #include <sys/mount.h>
> >  .P
> >  .BI "int open_tree(int " dirfd ", const char *" path ", unsigned int " flags );
> > +.P
> > +.BR "#include <sys/syscall.h>" "    /* Definition of " SYS_* " constants */"
> > +.P
> > +.BI "int syscall(SYS_open_tree_attr, int " dirfd ", const char *" path ,
> > +.BI "            unsigned int " flags ", struct mount_attr *_Nullable " attr ", \
> > +size_t " size );
> 
> Do we maybe want to move this to its own separate page?
> 
> The separate page could perfectly contain the same exact text you're
> adding here; you don't need to repeat open_tree() descriptions.
> 
> In general, I feel that while this improves discoverability of related
> functions, it produces more complex pages.

I tried it and I don't think it is a better experience as a reader when
split into two pages because of the huge overlap between the two
syscalls.

-- 
Aleksa Sarai
Senior Software Engineer (Containers)
SUSE Linux GmbH
https://www.cyphar.com/

Attachment: signature.asc
Description: PGP signature