Proposed v2: revised man(7) synopsis macros

[G. Branden Robinson]

Hi folks,

Difference from v1
==================
Support reuse of previously computed indentation, to line up function
arguments and similar across multiple synopses.  Requested by Alex
Colomar.

Proposal
========

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 sets 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.

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.  You can reuse the indentation amount computed in a previous
    synopsis.  To do this, give any argument to the `YS` macro call
    "closing" the synopsis whose indentation you want to reuse.  When
    you're done with such a grouped synopsis, simply leave the argument
    off the final `YS` call.

6.  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(1) mishandles indentation; it does not
    honor the rules set forth in §6 of CSTR #54 (supporting reproducer
    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.)

8.  For version 2 of this proposal, I made the `SY` macro effectively a
    no-op if it is called with no arguments.  No text is discarded.

The payoff of these changes is that, if adopted, you can write a
function synopsis like this.

.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.  (The \~ escape sequences keep the line from breaking between the
data type and the formal argument name.  Documents needing to be
portable to DWB, Heirloom Doctools, or Solaris 10 troff will need to use
the unadjustable space escape sequence `\ ` [backslash, space] instead.)

Compare to the status quo for the foregoing function in ncurses.

.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.  Further, when typeset, the leading spaces are unlikely to
match the width of "int wborder(" when using a proportional typeface.

The implementation is (will be) in the permissively licensed
"an-ext.tmac" file that ships with groff, 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 (will be) in the groff_man(7) and
groff_man_style(7) man pages and under the traditional GNU documentation
license, known to SPDX as the LaTeX 2e license.  (I don't know which of
those is of earlier provenance, and I would like to.)

Attachments:

* "git diff" of my working copy, also including updates to existing
  groff man pages and to a regression test script, to reflect the new
  `SY` and `YS` behavior.
* Sample document exercising mandoc(1)'s incorrect handling of
  `in` and `ti` requests.
* An example document, renderable with groff Git HEAD, 1.23.0, 1.22.4,
  and 1.22.3 (at least), illustrating use of these macros.  View it with
  "nroff -man".

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?

Regards,
Branden

revised-SY-YS-v2.diff
Description: Text Data

delayed-ll-in-ti.roff
Description: Text Data

synopsis-examples-portable.man
Description: Unix manual page

signature.asc
Description: PGP signature