At 2019-02-27T13:37:46+0100, Michael Kerrisk (man-pages) wrote: > So, summary: should I apply Bjarni's patch? Or does this lead to > back-compatibility problems? For maximum back-compatibility, you'd leave all of the string defines (.ds requests) active and uncommented. Zooming out a little bit, it appears that the proposed patch may be getting layered on top of an _earlier_ patch to shut up warnings from the macro package while rendering mdoc.samples(7). Looking at the patch once again, and noting the context, I see three workarounds in a row, first pushed and then popped. --- a/man7/mdoc.samples.7 +++ b/man7/mdoc.samples.7 @@ -1668,11 +1668,11 @@ will generate the following text: .Pp .\" fake section 3 to avoid error message from Rv .\".ds cH 3 -.ds section 3 +.ds doc-section 3 .Rv -std atexit .\" and back to 7 again .\".ds cH 7 -.ds section 7 +.ds doc-section 7 .Pp The .Fl std The warning in question is this: Usage: .Rv -std in sections 2 and 3 only (#1672) I'm starting to think the correct thing to do here is to see how we can get the page to render correctly without having to define strings at all. Or, as Ingo suggested, drop the page altogether. The purpose of the mdoc macro ".Rv" is to document a function's return value. I've attached groff's implementation of this macro for the curious. The macro complains if it's called from a page that isn't in the two sections set aside for documenting function interfaces (2 and 3). Being a gallery of examples, the page is trying to trick .Rv into not spewing a diagnostic message by using insider knowledge of the test .Rv implements to determine whether it should emit one. This is going to be a fragile thing, hence the 3 different strings that have been used for the purpose: "doc-section" (unstripped groff_mdoc, groff 1.22.4), "section" (stripped groff_mdoc, groff 1.22.3 and earlier), and "cH" (no idea). While I consider myself competent in man(7), I defer to Ingo's expertise on mdoc(7)[1]. But I don't think any of the above--the commented out .ds, the old (-) one, or the new (+)--is a model solution for resolving what .Rv is complaining about. Therefore my suggestion is to either live with the warning, chopping out _all_ these .ds kludges from the page--leaving one comment noting the warning we expect--or to drop the page altogether. Regards, Branden [1] As I have said elsewhere, I admire mdoc's goals and design--it is semantically-oriented, which man(7) very badly is not. Unfortunately I find mdoc unergonomic due in part to its self-restriction to the two-character macro namespace of legacy *roff implementations, which in my opinion makes the language too hard to acquire, especially for the occasional user. And most man page writers are only occasional users. (I have other complaints about mdoc's documentation and pedagogy, but I will leave them for another discussion.)
.\" NS Rv user macro
.\" NS return values
.\" NS
.\" NS width register 'Rv' set in doc-common
.\" NS
.\" NS local variables:
.\" NS doc-str-Rv-std-prefix
.\" NS doc-str-Rv-std-suffix
.\" NS doc-str-Rv-stds-prefix
.\" NS doc-str-Rv-stds-and
.\" NS doc-str-Rv-stds-suffix
.\" NS doc-str-Rv-std0
.
.ds doc-str-Rv-std-prefix "The
.ds doc-str-Rv-std-suffix "function returns the value\~0 if successful;
.as doc-str-Rv-std-suffix " otherwise the value\~\-1 is returned and
.as doc-str-Rv-std-suffix " the global variable \*[doc-Va-font]errno\f[]
.as doc-str-Rv-std-suffix " is set to indicate the error.
.
.ds doc-str-Rv-stds-prefix "The
.ds doc-str-Rv-stds-and "and
.ds doc-str-Rv-stds-suffix "functions return the value\~0 if successful;
.as doc-str-Rv-stds-suffix " otherwise the value\~\-1 is returned and
.as doc-str-Rv-stds-suffix " the global variable \*[doc-Va-font]errno\f[]
.as doc-str-Rv-stds-suffix " is set to indicate the error.
.
.ds doc-str-Rv-std0 "Upon successful completion, the value\~0 is returned;
.as doc-str-Rv-std0 " otherwise the value\~\-1 is returned and
.as doc-str-Rv-std0 " the global variable \*[doc-Va-font]errno\f[]
.as doc-str-Rv-std0 " is set to indicate the error.
.
.de Rv
.
.\" XXX: what does this function without '-std'?
.
. if \n[doc-arg-limit] \{\
. tm Usage: .Rv not callable by other macros (#\n[.c])
. doc-reset-args
. return
. \}
.
. if !\n[.$] \{\
. tm Usage: .Rv [-std] [<function> ...] (#\n[.c])
. return
. \}
.
. if "\$1"-std" \{\
. nr doc-reg-Rv \*[doc-section]
. if ((\n[doc-reg-Rv] < 2) : (\n[doc-reg-Rv] > 3)) \
. tm Usage: .Rv -std in sections 2 and 3 only (#\n[.c])
. br
. shift
. ie (\n[.$] > 1) \{\
. nop \)\*[doc-str-Rv-stds-prefix]
. nr doc-reg-Rv 1
. while (\n[doc-reg-Rv] < \n[.$]) \{\
. ie (\n[.$] > 2) \
. Fn \$\n[doc-reg-Rv] ,
. el \
. Fn \$\n[doc-reg-Rv]
. nr doc-reg-Rv +1
. \}
. nop \)\*[doc-str-Rv-stds-and]
. Fn \$\n[.$]
. nop \)\*[doc-str-Rv-stds-suffix]
. \}
. el \{ .ie (\n[.$] == 1) \{\
. nop \)\*[doc-str-Rv-std-prefix]
. Fn \$1
. nop \)\*[doc-str-Rv-std-suffix]
. \}
. el \{\
. nop \)\*[doc-str-Rv-std0]
. \}\}\}
..
Attachment:
signature.asc
Description: PGP signature
