groff man(7) extensions (was: [PATCH 1/3] strcpy.3: Rewrite page to document all string-copying functions)

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

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

Hi Alex,

At 2022-12-12T18:33:52+0100, Alejandro Colomar wrote:
> On 12/12/22 15:24, Alejandro Colomar wrote:
> > +.\" ----- RETURN VALUE :: Deprecated ----------------------------------/
> > +.SS Deprecated
> > +The following functions return
> > +the length of the total string that they tried to create
> > +(as if truncation didn't occur).
> > +.IP \(bu 3
> > +.BR strlcpy (3bsd),
> > +.BR strlcat (3bsd)
> > +.PP
> > +The following function returns
> > +the length of the destination string, or
> > +.B \-E2BIG
> > +on truncation.
> > +.IP \(bu 3
> > +.BR strscpy (9)
> > +.PP
> > +The following functions return the
> > +.I dst
> > +pointer,
> > +which is useless.
> > +.PD 0
> > +.IP \(bu 3
> > +.BR strcpy (3),
> > +.BR strcat (3)
> > +.IP \(bu
> > +.BR strncpy (3)
> > +.IP \(bu
> > +.BR strncat (3)
> > +.PD
> 
> I realized that the above doesn't produce exactly what I wanted.  I
> wanted this:
> 
>        The following functions return the dst pointer, which is useless.
> 
>        •  strcpy(3), strcat(3)
>        •  strncpy(3)
>        •  strncat(3)
> 
> But I got this:
> 
>        The following functions return the dst pointer, which is useless.
>        •  strcpy(3), strcat(3)
>        •  strncpy(3)
>        •  strncat(3)
> 
> I see various possible solutions, but which would you recommend?
> 
> I've thought of:
> 
> [
> [...]
> .PP
> .PD 0
> .IP \(bu 3
> [...]
> ]
> 
> or
> 
> [
> [...]
> .IP \(bu 3
> .PD 0
> [...]
> ]
> 
> I was thinking about your future (I hope) .LS and .LE, and how they
> would also fit in here.

Either is fine; if it were me, after threatening another radical
innovation, I would probably go with the latter, using ".PD 0" _after_
the first `IP` macro.  The hazard there is that if you re-order the
list, you might move the ".PD 0" with it accidentally.  Your earlier
approach avoids that at the cost of a _seemingly_ useless `PP` call.

Paragraphing macros in man(7) are not enclosures; they are spot
marks.[1]  This is an impedance mismatch with the brains of people who
grew up on HTML/XML.

Also, you don't need to keep restating the indentation amount ("3").

  Horizontal and vertical spacing
    The indentation argument accepted by .RS, .IP, .TP, and the
    deprecated .HP is a number plus an optional scaling unit.  If no
    scaling unit is given, the man package assumes "n".  An indentation
    specified in a call to .IP, .TP, or the deprecated .HP persists
    until (1) another of these macros is called with an explicit
    indentation argument, or (2) .SH, .SS, or .P or its synonyms is
    called; these clear the indentation entirely. [...]

(ms(7) works this way, too, though its macro repertoire differs a
bit.[2])

I haven't given much more thought to `LS` and `LE`.  I haven't soured on
them; I simply have more urgent fish to fry.  The possibility of having
`LS` accept an argument to set the paragraph indentation so that `IP` or
`TP` items can be rearranged freely within has occurred to me.  So has
making the inter-paragraph distance itself an argument (possibly just a
Boolean).  So has support for auto-enumerated lists.  But then I wonder
if man(7) authors really need a macro that is as tricked-out as
mdoc(7)'s list macros, which take up about 5 of its 31 U.S. letter-sized
pages of documentation.  That's heavy.

Here's a list of man(7) extensions to which I have given consideration.

	KS/KE	Keeps.  Easy.[3]  Harmlessly ignorable by other
		implementations.
	LS/LE	List enclosure.  Throws a semantic hint (e.g., for HTML
		output) and eliminates final use case of `PD` macro.[4]
	DC/TG	Semantics at last.  Sure to rouse anger in people who
		decided long ago that man(7) can't do this.[5]  Having
		looked more closely at mdoc(7) since writing that, I
		think `DC` should accept a _pair_ of arguments as its
		second and third parameters for bracketing purposes.
		But again, most man page authors would never need to
		mess with `DC` at all.

`DS`/`DE` have been squatted on by groff man(7) for 13 years and have
precedent going back at least to DEC Ultrix, but apart from using them
as a sort of ersatz tbl(1) for people who don't want to use to use
tbl(1),[6] I haven't been able to come up with any use cases for it.

Regards,
Branden

[1] For the curious, all the paragraphing macros in groff man(7) call
    the same common macro.  (They all perform additional operations.)

.\" Break a paragraph.  Restore defaults, except for indentation.
.de an-break-paragraph
.  ft R
.  ps \\n[PS]u
.  vs \\n[VS]u
.  sp \\n[PD]u
.  ns

   This internal macro name is subject to change.

[2] The new ms(7) manual for groff 1.23 appears to have stabilized.[7]
    Here's a URL to a work area I use to proof-read groff documentation.
    I invite you (and others) to check out ms.2022-12-07.pdf, or
    whatever version is there at the time.

    https://www.dropbox.com/sh/17ftu3z31couf07/AAC_9kq0ZA-Ra2ZhmZFWlLuva?dl=0

[3] I initially shied away from dealing with nested diversions, but I
    think I know how to cope with them now.  It seems that in a lot of
    cases, "bubbling up" as illustrated in groff Git's tbl(1) page is
    all that is required.

[4] https://lists.gnu.org/archive/html/groff/2022-05/msg00026.html
[5] https://lore.kernel.org/linux-man/20220724172947.qlunrfnje56yaasv@illithid/
[6] https://lore.kernel.org/linux-man/20220722222045.y7i3yc7d6agygien@illithid/

[7] By saying this, I increase my ability to find a flaw in it, or for
    a reader to report one.  We use all the QA tools at our disposal.

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