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

["G. Branden Robinson" <g.branden.robinson@gmail.com>]

[-- 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 --]