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