[PATCH] man2/: SYNOPSIS: Use SY/YS

[PATCH] man2/: SYNOPSIS: Use SY/YS

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 4876 bytes --]

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@debian.org>
Cc: Ingo Schwarze <schwarze@openbsd.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---

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 #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] man2/: SYNOPSIS: Use SY/YS

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 2516 bytes --]

Hi Alex,

At 2024-11-24T22:10:19+0100, Alejandro Colomar wrote:
> 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.

You can go ahead and use the second argument to `SY` now--older groffs
(and other formatters) won't complain about it.[1]

$ printf '.TH foo 1 2024-12-01 "groff test suite"\n.SH Name\nfoo \\- frobnicate a bar\n.SH Synopsis\n.SY foo\n.B \-\-help\n.YS 0\n' | ~/groff-1.22.4/bin/nroff -ww -man -rCHECKSTYLE=4
foo(1)                      General Commands Manual                     foo(1)



Name
       foo - frobnicate a bar

Synopsis
       foo --help



groff test suite                  2024‐12‐01                            foo(1)
$ printf '.TH foo 1 2024-12-01 "groff test suite"\n.SH Name\nfoo \\- frobnicate a bar\n.SH Synopsis\n.SY foo\n.B \-\-help\n.YS 0\n' | ~/groff-stable/bin/nroff -ww -man -rCHECKSTYLE=4
foo(1)                      General Commands Manual                     foo(1)

Name
       foo - frobnicate a bar

Synopsis
       foo --help

groff test suite                  2024‐12‐01                            foo(1)

Regards,
Branden

[1] mandoc(1) prints the argument, but the release of groff 1.24 won't
    solve that problem.  mandoc's developers will have to decide if they
    want to support this GNU extension, and if so, they will also need
    to do a release.

$ printf '.TH foo 1 2024-12-01 "groff test suite"\n.SH Name\nfoo \\- frobnicate a bar\n.SH Synopsis\n.SY foo\n.B \-\-help\n.YS 0\n' | mandoc | ul
foo(1)                      General Commands Manual                     foo(1)

Name
       foo - frobnicate a bar

Synopsis
       foo --help
       0

groff test suite                  2024-12-01                            foo(1)

    What mandoc(1) is doing here is off-spec for a *roff...but it's not
    roff.  So who can say whether its output is erroneous?  ¯\_(ツ)_/¯

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

Re: [PATCH] man2/: SYNOPSIS: Use SY/YS

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1611 bytes --]

Hi Branden,

On Sun, Dec 01, 2024 at 02:51:27PM -0600, G. Branden Robinson wrote:
> You can go ahead and use the second argument to `SY` now--older groffs
> (and other formatters) won't complain about it.[1]

Hmmm.  Actually, groff <= 1.23.0 is bad: it doesn't print $2.  See
below.

Cheers,
Alex


alx@devuan:~/tmp/groff$ cat foo.man 
.TH a s d f
.SH Name
f \- oo
.SH Foo
.SY f (
.B void);
.YS
alx@devuan:~/tmp/groff$ groff --version | head -n1
GNU groff version 1.22.4
alx@devuan:~/tmp/groff$ groff -man -Tutf8 ./foo.man
a(s)                                                                      a(s)



Name
       f - oo

Foo
       f void);



f                                      d                                  a(s)
alx@devuan:~/tmp/groff$ dpkg -l mandoc | grep mandoc
ii  mandoc         1.14.6-1+b1  amd64        BSD manpage compiler toolset
alx@devuan:~/tmp/groff$ mandoc -man -Tutf8 ./foo.man
a(s)                                                                      a(s)

Name
       f - oo

Foo
       f (
         void);

f                                      d                                  a(s)
alx@devuan:~/tmp/groff$ ssh www
alx@www:~$ cd /tmp/
alx@www:/tmp$ /usr/bin/groff --version | head -n1
GNU groff version 1.23.0
alx@www:/tmp$ /usr/bin/groff -man -Tutf8 ./foo.man 
a(s)                                                                      a(s)

Name
       f - oo

Foo
       f void);

f                                      d                                  a(s)




-- 
<https://www.alejandro-colomar.es/>

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

Re: [PATCH] man2/: SYNOPSIS: Use SY/YS

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 684 bytes --]

Hi Alex,

At 2024-12-01T22:45:20+0100, Alejandro Colomar wrote:
> On Sun, Dec 01, 2024 at 02:51:27PM -0600, G. Branden Robinson wrote:
> > You can go ahead and use the second argument to `SY` now--older
> > groffs (and other formatters) won't complain about it.[1]

Sorry, I had a brainfart there--I should have said `YS` instead of `SY`;
that is what my example illustrated.

> Hmmm.  Actually, groff <= 1.23.0 is bad: it doesn't print $2.  See
> below.

Right.  And I wouldn't expect it to; a general rule in *roff is that
macros do nothing with arguments that they don't expect.  (mandoc(1)
prints them all.)

So yes, probably need to wait for 1.24 for this one.

Regards,
Branden

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