[groff] 17/40: groff_mdoc(7): Revise "Miscellaneous macros".

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit ef2420804eefb89299cd790f92bf55bbfd99736f
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Dec 10 04:24:31 2022 -0600

    groff_mdoc(7): Revise "Miscellaneous macros".
    
    * Recast.
    * Document default widths, found in tmac/mdoc/doc-common.
    * Use more idiomatic synopsis markup, following an example from Ingo
      Schwarze.  However, in my opinion the dot in "Pf . Ic \&Whatever"
      kisses the `Ic` argument too closely when that argument is in Courier
      bold.  Perhaps soon we'll see if Times bold makes it better.
    * Rechristen "space mode" as "argument-spacing mode".  Let's not confuse
      *roff users accustomed to the meanings of the `ns` and `rs` requests.
    
    It is a mystery to me why a default width is required of `Sm`; it
    toggles state internal to the macro package rather than producing
    formatted output.
---
 tmac/groff_mdoc.7.man | 112 ++++++++++++++++++++++++++++++++++----------------
 1 file changed, 76 insertions(+), 36 deletions(-)

diff --git a/tmac/groff_mdoc.7.man b/tmac/groff_mdoc.7.man
index e9c6cfea6..d7f5dc659 100644
--- a/tmac/groff_mdoc.7.man
+++ b/tmac/groff_mdoc.7.man
@@ -4539,23 +4539,25 @@ Suppress insertion of vertical space before the list 
and between list items.
 .
 .Sh "Miscellaneous macros"
 .
-Here a list of the remaining macros which do not fit well into one of
-the above sections.
+A double handful of macros fit only uncomfortably into one of the above
+sections.
 .
-We couldn't find real examples for the following macros:
-.Ql .Me
-and
-.Ql .Ot .
+Of these,
+we couldn't find attested examples for
+.Ql \&Me
+or
+.Ql \&Ot .
 .
-They are documented here for completeness\(emif you know how to use them
-properly,
+They are documented here for completeness\[em]if you know their proper
+usage,
 please send a mail to
 .Mt groff@gnu.org
-(including an example).
+and include a specimen with its provenance.
+.
 .
 .Bl -tag -width ".Li .Bt"
 .It Li .Bt
-prints
+formats boilerplate text.
 .
 .Bd -ragged -offset indent
 .Bt
@@ -4565,36 +4567,52 @@ prints
 .Pp
 It is neither callable nor parsed and takes no arguments.
 .
+Its default width is 6n.
+.
+.
 .It Li .Fr
+is an obsolete means of specifying a function return value.
 .
 .
 .Pp
-.Dl Usage: .Fr Ao function return value Ac ...
+.D1 Usage: Pf . Ic \&Fr Ar return-value No ...
 .
 .
 .Pp
-Don't use this macro.
-It allows a break right before the return value (usually a single digit)
+.Ql \&Fr
+allows a break right before the return value
+(usually a single digit)
 which is bad typographical behaviour.
-Use
-.Ql \e\[ti]
+.
+Instead,
+set the return value with the rest of the code,
+using
+.Ql \[rs]\[ti]
 to tie the return value to the previous word.
 .
+.
+.Pp
+Its default width is 12n.
+.
+.
 .It Li .Hf
-Use this macro to include a (header) file literally.
-It first prints
-.Ql File:
-followed by the file name, then the contents of
-.Ao file Ac .
+Inlines the contents of a (header) file into the document.
 .
 .
 .Pp
-.Dl Usage: .Hf Ao file Ac
+.D1 Usage: Pf . Ic \&Hf Ar file
 .
 .
 .Pp
+It first prints
+.Ql File:
+followed by the file name,
+then the contents of
+.Ar file .
+.
 It is neither callable nor parsed.
 .
+.
 .It Li .Lk
 Embed hyperlink.
 .
@@ -4603,17 +4621,23 @@ Embed hyperlink.
 .D1 Usage: Pf . Ic \&Lk Ar uri Op Ar link-text
 .
 .
+.Pp
+Its default width is 6n.
+.
+.
 .It Li .Me
-Exact usage unknown.
-The documentation in the
+Usage unknown.
+.
+The
 .Xr mdoc
-source file describes it as a macro for
+sources describe it as a macro for
 .Dq "menu entries" .
 .
 .
 .Pp
 Its default width is 6n.
 .
+.
 .It Li .Mt
 Embed email address.
 .
@@ -4622,32 +4646,46 @@ Embed email address.
 .D1 Usage: Pf . Ic \&Mt Ar email-address
 .
 .
+.Pp
+Its default width is 6n.
+.
+.
 .It Li .Ot
-Exact usage unknown.
-The documentation in the
+Usage unknown.
+The
 .Xr mdoc
-source file describes it as
-.Dq old function type (fortran) .
+sources describe it as
+.Dq "old function type (fortran)" .
+.
 .
 .It Li .Sm
-Activate (toggle) space mode.
+Manipulate or toggle argument-spacing mode.
 .
 .
 .Pp
-.Dl Usage: .Sm Oo on | off Oc ...
+.D1 Usage: Pf . Ic \&Sm Oo Li on | Li off Oc ...
 .
 .
 .Pp
-If space mode is off, no spaces between macro arguments are inserted.
-If called without a parameter (or if the next parameter is neither
+If argument-spacing mode is off,
+no spaces between macro arguments are inserted.
+.
+If called without a parameter
+(or if the next parameter is neither
 .Ql on
 nor
-.Ql off ,
-.Ql .Sm
-toggles space mode.
+.Ql off ) ,
+.Ql \&Sm
+toggles argument-spacing mode.
+.
+.
+.Pp
+Its default width is 8n.
+.\" The package demands it, but how is that meaningful?
+.
 .
 .It Li .Ud
-prints
+formats boilerplate text.
 .
 .Bd -ragged -offset indent
 .Ud
@@ -4656,6 +4694,8 @@ prints
 .
 .Pp
 It is neither callable nor parsed and takes no arguments.
+.
+Its default width is 8n.
 .El
 .
 .