Re: Proposed: revised man(7) synopsis macros

[Alejandro Colomar]

On Tue, Apr 23, 2024 at 08:19:55PM -0500, G. Branden Robinson wrote:
> Hi folks,

Hi folk,

> I have been dissatisfied with groff man(7)'s SY and YS macros for a long
> time.  My primary grievance is one that has frustrated its uptake by
> documenters of libraries: the macros are designed for synopsizing Unix
> commands, not C library functions.
> 
> After working on the ncurses man pages for a while it became clear to me
> how to modestly revise the way groff man(7)'s SY and YS macros work to
> serve both set of authors better.
> 
> My proposal, as a diff to groff Git HEAD, is attached.
> 
> Here are the highlights, starting with the most disruptive:
> 
> 1.  The `SY` macro no longer puts vertical space on the output.  That's
>     up to you now.  You can use whatever paragraphing macro you please
>     to separate multiple synopses.
> 
> 2.  The `SY` macro now initially breaks the output line _only_ if it is
>     encountered repeatedly without a preceding `YS` call.  Formerly,
>     it _always_ initially broke the output line because it put vertical
>     space on the output.  This is largely a guardrail in case someone
>     forgets to call `YS`.  (Using `SY` multiple times before `YS` used
>     to be idiomatic for synonymous command invocations like "foobar
>     --help" and "foobar -h"; no longer.  Now you bracket each with `SY`
>     and `YS` and leave out a paragraphing macro if you don't want one.)
> 
> 3.  The computed indentation of synopsis lines after the first now also
>     includes the width of anything on the line _before_ the synopsis.
>     This is so that you can precede the synopsis keyword with other
>     syntax.  The most likely application of this is a return type for a
>     C function prototype.

It would be interesting if consecutive SY/YS blocks would have the same
indentation.  See man-pages(7):

     (2)  But, where multiple functions in the SYNOPSIS require contin‐
          uation  lines, and the function names have different lengths,
          then align all continuation lines to start in the  same  col‐
          umn.   This provides a nicer rendering in PDF output (because
          the SYNOPSIS uses a variable width font where  spaces  render
          narrower than most characters).  As an example:

              int getopt(int argc, char * const argv[],
                         const char *optstring);
              int getopt_long(int argc, char * const argv[],
                         const char *optstring,
                         const struct option *longopts, int *longindex);

Would it be possible to store some register that remembers if there was
a previous prototype with a different indentation?

> 4.  The `SY` macro now accepts an optional second argument.  This
>     second argument is typeset in bold and replaces the fixed-width
>     space that is appended to the synopsis keyword in `SY`'s
>     single-argument form.  As with that fixed-width space, the width of
>     this suffix argument informs the indentation used on subsequent
>     lines of the synopsis if it needs to break.[*]
> 
> 5.  I tested the portability of these changes to DWB 3.3 troff, Heirloom
>     Doctools troff, and Solaris 10 troff, and worked around what appears
>     to be a glitch in their man(7) packages.  That helped, but a small
>     problem remains: the computed width marked with an asterisk[*] in
>     the previous item is 1n too short.
> 
>     Concretely, instead of:
> 
>      int wborder(WINDOW *win, chtype ls, chtype rs, chtype ts,
>                  chtype bs, chtype tl, chtype tr, chtype bl,
>                  chtype br);
> 
>     you get the following on DWB/Heirloom/Solaris 10 nroff.
> 
>      int wborder(WINDOW *win, chtype ls, chtype rs, chtype ts,
>                 chtype bs, chtype tl, chtype tr, chtype bl,
>                 chtype br);
> 
>     I regarded this defect as too inconsequential to worry about, but if
>     someone wants to research the innards of AT&T man(7) to see if a
>     workaround can be found, I'll be receptive to suggestions.
> 
> 6.  I discovered that mandoc mishandles indentation; it does not honor
>     the rules set forth in §6 of CSTR #54 (supporting evidence
>     attached).  The result is merely ugly, however, and no text is lost.
>     Since mandoc is actively maintained I assume that eventually this
>     will get fixed, perhaps after a strident exhortation to migrate
>     one's documents to mdoc(7).  ;-)
> 
> 7.  The first argument to `SY` remains the keyword.  I avoided the
>     complexity of a three-argument form partly because I didn't need it
>     and partly because I wanted to preserve the invariant of the first
>     argument being the name of the documented thing.  A potential
>     advantage to this practice is that we can, in future groff man(7)
>     development, automatically generate hyperlink tags for these items.
>     Need to know where a command or function is synopsized?  With tags
>     you can find out much more quickly than with a textual search.
>     (The invariant is actually a bigger advantage for hypothetical
>     external tools--or grep(1)--because the `SY` macro would "know"
>     which item was the keyword based on the argument count.)
> 
> The payoff is that, if adopted, you can write a function synopsis like
> this.
> 
> .P
> .B int
> .SY wborder (
> .BI WINDOW\~* win ,
> .BI chtype\~ ls ,
> .BI chtype\~ rs ,
> .BI chtype\~ ts ,
> .BI chtype\~ bs ,
> .BI chtype\~ tl ,
> .BI chtype\~ tr ,
> .BI chtype\~ bl ,
> .BI chtype\~ br );
> .YS
> 
> ...and not worry about the line length or line breaking or any of that
> stuff.

LGTM!

> Compare to the status quo for the foregoing function in ncurses.
> 
> .SH SYNOPSIS
> .nf
> ...
> \fBint wborder(WINDOW *\fIwin\fB, chtype \fIls\fB, chtype \fIrs\fB,\fR
>             \fBchtype \fIts\fB, chtype \fIbs\fB, chtype \fItl\fB, chtype 
> \fItr\fB,\fR
>             \fBchtype \fIbl\fB, chtype \fIbr\fB);\fR
> 
> .fi
> 
> The foregoing looks messier to me as input, and moreover it does not
> adapt to the width of the terminal, thanks to those `nf`/`fi` formatter
> requests.  It will waste space on wide terminals and overrun the line on
> narrow ones.
> 
> You may notice that I haven't changed `YS` at all.
> 
> The implementation is in the permissively licensed "an-ext.tmac" file,
> so there is no _legal_ reason for those allergic to copyleft (or even
> Apache-style) licenses to have any compunctions about adopting it.
> 
> The documentation is under the traditional GNU documentation license,
> known to SPDX as the LaTeX 2e license.  (I don't know which is the
> earlier provenance, and I would like to.)
> 
> My questions:
> 
> A.  Does anyone object to me committing this change to groff's master
>     branch?  It will of course require a NEWS item, which I will write.
> 
> B.  Does this look enticing enough to any documenters of C libraries for
>     you to adopt it?

My only meh is the indentation of several functions in the same
synopsis.  Other than that, I had been trying to workaround SY for C
synopses in the past, so yeah, I would.

Have a lovely day!
Alex

> Regards,
> Branden

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

signature.asc
Description: PGP signature