[groff] 39/51: groff_mdoc(7): Update example.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit e338223d742e85fd1d1554fc3016c35f19ada292
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Sep 8 00:02:45 2022 -0500

    groff_mdoc(7): Update example.
    
    The existing one was hard for me to comprehend; the method attempted for
    computing the width of the widest column failed due to problems explored
    at length recently on the groff mailing list.  Use tbl(1).  Simulate
    output more realistically.
    
    https://lists.gnu.org/archive/html/groff/2022-07/msg00213.html
    https://lists.gnu.org/archive/html/groff/2022-08/msg00079.html
    
    For a possibly exhaustive exploration of the underlying issues, see the
    following.
    
    
https://lore.kernel.org/linux-man/62c1b6748d2faa6263264b9fcaa064495357441b.1658195739.git.nabijaczleweli@nabijaczleweli.xyz/T/#m83835d556f7dd115590ff756305734ce5fb27a18
    
    This commit will provoke warnings when the groff_mdoc(7) page is
    rendered to the terminal.
    
    troff:./build/tmac/groff_mdoc.7:930: warning: cannot select font 'CR'
    
    This is because our mdoc implementation needs to remap these fonts as
    our man implementation does.
    
    This update does exhibit Savannah #62471.  That's a shame.  It's still
    perfectly readable, though.
---
 tmac/groff_mdoc.7.man | 45 +++++++++++++++++++--------------------------
 1 file changed, 19 insertions(+), 26 deletions(-)

diff --git a/tmac/groff_mdoc.7.man b/tmac/groff_mdoc.7.man
index ac8ae17f8..dfe5670a0 100644
--- a/tmac/groff_mdoc.7.man
+++ b/tmac/groff_mdoc.7.man
@@ -912,34 +912,27 @@ the third parameter is used verbatim as the volume name.
 .
 .
 .Pp
-In the following examples,
-the left
-(which is identical to the right)
-and the middle part of the manual page header strings are shown.
+The effects of varying
+.Ql .Dt
+arguments on the page header content
+are shown below.
 .
-Note how
-.Ql \e&
-prevents the digit\~7 from being a valid numeric expression.
+Observe how
+.Ql \[rs]&
+prevents the digit\~2 from being treated as a manual section number.
 .
-.Bd -ragged
-.Bl -tag -width ".Li .Dt\ FOO\ 2\ i386" -compact -offset indent
-.It Li ".Dt FOO 7"
-.Ql FOO(7)
-.Ql \*[doc-volume-ds-7]
-.It Li ".Dt FOO 7 bar"
-.Ql FOO(7)
-.Ql \*[doc-volume-ds-7]
-.It Li ".Dt FOO \e&7 bar"
-.Ql FOO(7)
-.Ql bar
-.It Li ".Dt FOO 2 i386"
-.Ql FOO(2)
-.Ql \*[doc-volume-ds-2]
-.It Li ".Dt FOO \[dq]\[dq] bar"
-.Ql FOO
-.Ql bar
-.El
-.Ed
+.
+.Pp
+.\" XXX: Figure out how to indent this.
+.TS
+tab(@);
+Lf(CR) | L C R.
+\&.Dt foo 2@foo(2)@System Calls Manual@foo(2)
+\&.Dt foo 2 m68k@foo(2)@m68k System Calls Manual@foo(2)
+\&.Dt foo 2 baz@foo(2)@System Calls Manual@foo(2)
+\&.Dt foo \[rs]&2 baz@foo(2)@baz@foo(2)
+\&.Dt foo \[dq]\[dq] baz@foo@baz@foo
+.TE
 .
 .
 .Pp