This makes it easier to write the SYNOPSIS, which will reduce the learning curve for contributors. Another benefit is that the prototypes are wrapped correctly for the terminal width that the reader is using, so it's not hardcoded at 80. It also removes the need for carefully aligning the prototypes by the author of a page. It causes a small unwanted problem: a white space is added after the opening parenthesis. That's a minor trade-off for the benefits it brings. Once groff 1.24.0 is released, we'll be able to use an extension that it provides, which allows us to remove that space, by using the second argument to SY. Suggested-by: "Branden G. Robinson" <branden@xxxxxxxxxx> Cc: Ingo Schwarze <schwarze@xxxxxxxxxxx> Signed-off-by: Alejandro Colomar <alx@xxxxxxxxxx> --- Hi all! I'm preparing an important change for the SYNOPSIS sections of the manual pages for syscalls and libc functions. This was originally suggested by Branden, which has authored a man(7) extension in groff that will make SY/YS suitable for this. This patch will be applied after Debian Trixie is released, and after groff-1.24.0 is released (ideally groff-1.24.0 would be in Trixie, but I don't know how likely that is). I'm only foreshadowing for now. This patch will be immediately followed by another one which will be a scripted change: '/^\.SY.*($/s/($/ (/' The idea is that distros using old versions of groff(1) (or other formatters) that don't support the GNU extension would revert the second patch, and get backwards-compatible source, at the expense of having an unwanted whitespace. Distros using a recent-enough formatter will be able to get all the juice with no downside. I'll slowly prepare this patch by transforming a few functions per day, until the time comes. Have a lovely night! Alex man/man2/landlock_create_ruleset.2 | 11 +++++++---- man/man2/posix_fadvise.2 | 10 +++++++--- man/man2/wait4.2 | 19 ++++++++++++++----- man/man2/write.2 | 8 ++++++-- 4 files changed, 34 insertions(+), 14 deletions(-) diff --git a/man/man2/landlock_create_ruleset.2 b/man/man2/landlock_create_ruleset.2 index cfeab62c9..5bc4ee529 100644 --- a/man/man2/landlock_create_ruleset.2 +++ b/man/man2/landlock_create_ruleset.2 @@ -15,11 +15,14 @@ .SH SYNOPSIS .BR "#include <linux/landlock.h>" " /* Definition of " LANDLOCK_* " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.P -.B int syscall(SYS_landlock_create_ruleset, -.BI " const struct landlock_ruleset_attr *" attr , -.BI " size_t " size " , uint32_t " flags ); .fi +.P +.SY int\~syscall( +.B SYS_landlock_create_ruleset, +.BI const\~struct\~landlock_ruleset_attr\~* attr , +.BI size_t\~ size , +.BI uint32_t\~ flags ); +.YS .SH DESCRIPTION A Landlock ruleset identifies a set of rules (i.e., actions on objects). This diff --git a/man/man2/posix_fadvise.2 b/man/man2/posix_fadvise.2 index c7a42baa9..47fc5b789 100644 --- a/man/man2/posix_fadvise.2 +++ b/man/man2/posix_fadvise.2 @@ -15,11 +15,15 @@ .SH LIBRARY .SH SYNOPSIS .nf .B #include <fcntl.h> -.P -.BI "int posix_fadvise(int " fd ", off_t " offset ", off_t " size \ -", int " advice ");" .fi .P +.SY int\~posix_fadvise( +.BI int\~ fd , +.BI off_t\~ offset , +.BI off_t\~ size , +.BI int\~ advice ); +.YS +.P .ad l .RS -4 Feature Test Macro Requirements for glibc (see diff --git a/man/man2/wait4.2 b/man/man2/wait4.2 index f419ce834..a55e21622 100644 --- a/man/man2/wait4.2 +++ b/man/man2/wait4.2 @@ -19,13 +19,22 @@ .SH LIBRARY .SH SYNOPSIS .nf .B #include <sys/wait.h> -.P -.BI "pid_t wait3(int *_Nullable " "wstatus" ", int " options , -.BI " struct rusage *_Nullable " rusage ); -.BI "pid_t wait4(pid_t " pid ", int *_Nullable " wstatus ", int " options , -.BI " struct rusage *_Nullable " rusage ); .fi .P +.SY pid_t\~wait3( +.BI int\~*_Nullable\~ wstatus , +.BI int\~ options , +.br +.BI struct\~rusage\~*_Nullable\~ rusage ); +.YS +.SY pid_t\~wait4( +.BI pid_t\~ pid , +.BI int\~*_Nullable\~ wstatus , +.BI int\~ options , +.br +.BI struct\~rusage\~*_Nullable\~ rusage ); +.YS +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): diff --git a/man/man2/write.2 b/man/man2/write.2 index cd0677cc9..cfbe706f6 100644 --- a/man/man2/write.2 +++ b/man/man2/write.2 @@ -25,9 +25,13 @@ .SH LIBRARY .SH SYNOPSIS .nf .B #include <unistd.h> -.P -.BI "ssize_t write(int " fd ", const void " buf [. count "], size_t " count ); .fi +.P +.SY ssize_t\~write( +.BI int\~ fd , +.BI const\~void\~ buf [. count ], +.BI size_t\~ count ); +.YS .SH DESCRIPTION .BR write () writes up to -- 2.39.5
Attachment:
signature.asc
Description: PGP signature
