Re: mdoc(7) closing macros in See also

2020-08-17 Thread Jason McIntyre
On Mon, Aug 17, 2020 at 12:33:43PM -0400, Scott Bennett wrote:
> Hi,
> 
> While learning the mdoc(7) markup language, I sometimes have trouble figuring
> out which macros are used to close certain multi-line macros. It is certainly
> not impossible to find the necessary closing macro to any arbitrary opening
> macro, but for the macros that I use less often it can be a bit of a
> scavenger hunt.
> 
> This could be much easier if the required closing macro were listed in the
> "See also" section of the opening macro. In fact, there is already a precedent
> in the Bf and Bl macros, which do list their closers (Ef and El, respectively)
> in their "See also" sections.
> 
> I think the following patch could be useful to those starting to learn the
> mdoc(7) language, or for anyone who prefers to jump right into the MACRO
> REFERENCE section.
> 
> Thanks,
> Scott Bennett
> 

hi.

the stuff you want is documented nicely in the "Physical enclosures"
part of MACRO OVERVIEW, page top.

your diff is odd in that it adds, for example, a note to Aq to see Ac,
but not Ao. anyway, i don;t think such an addition is warranted. for the
most part they're pretty logical: Aq can be expanded as Ao/Ac (so the
same initial letter, plus 'o' (open) or 'c' (closed).

jmc

> diff f7f933db8e4e532d6a39c747672ac5861ccd4883 
> ced68e3867e5e6c3d2dc26f337effe036c033d47
> blob - 7cbe1db136ad1619f26a599517c7c9b1d7e36ce8
> blob + 45935846ab15de1500fd65ccb773c8371d614bbf
> --- share/man/man7/mdoc.7
> +++ share/man/man7/mdoc.7
> @@ -677,10 +677,13 @@ Begin a block enclosed by angle brackets.
>  Does not have any head arguments.
>  This macro is almost never useful.
>  See
>  .Ic \
>  for more details.
> +.Pp
> +See also
> +.Ic \ .
>  .It Ic \
>  Inserts an apostrophe without any surrounding whitespace.
>  This is generally used as a grammatical device when referring to the verb
>  form of a function.
>  .Pp
> @@ -870,13 +873,14 @@ Examples:
> Hello   world.
>  \&.Ed
>  .Ed
>  .Pp
>  See also
> -.Ic \
> +.Ic \ ,
> +.Ic \ ,
>  and
> -.Ic \ .
> +.Ic \ .
>  .It Ic \ Fl emphasis | literal | symbolic | Cm \ | \ | \
>  Change the font mode for a scoped block of text.
>  The
>  .Fl emphasis
>  and
> @@ -921,10 +925,13 @@ macro line:
>  \&.Ek
>  .Ed
>  .Pp
>  Be careful in using over-long lines within a keep block!
>  Doing so will clobber the right margin.
> +.Pp
> +See also
> +.Ic \ .
>  .It Xo
>  .Ic \
>  .Fl Ns Ar type
>  .Op Fl width Ar val
>  .Op Fl offset Ar val
> @@ -1062,10 +1069,12 @@ Examples:
>  \&.Bo 1 ,
>  \&.Dv BUFSIZ \
>  .Ed
>  .Pp
>  See also
> +.Ic \
> +and
>  .Ic \ .
>  .It Ic \ Ar line
>  Encloses its arguments in square brackets.
>  .Pp
>  Examples:
> @@ -1095,10 +1104,12 @@ Examples:
>  \&.Bro 1 , ... ,
>  \&.Va n \
>  .Ed
>  .Pp
>  See also
> +.Ic \
> +and
>  .Ic \ .
>  .It Ic \ Ar line
>  Encloses its arguments in curly braces.
>  .Pp
>  Examples:
> @@ -1275,10 +1286,12 @@ April is the cruellest month
>  \&.Dc
>  \e(em T.S. Eliot
>  .Ed
>  .Pp
>  See also
> +.Ic \
> +and
>  .Ic \ .
>  .It Ic \ Ar line
>  Encloses its arguments in
>  .Dq typographic
>  double-quotes.
> @@ -1470,10 +1483,13 @@ An arbitrary enclosure.
>  The
>  .Ar opening_delimiter
>  argument is used as the enclosure head, for example, specifying \e(lq
>  will emulate
>  .Ic \ .
> +.Pp
> +See also
> +.Ic \ .
>  .It Ic \ Ar identifier ...
>  Error constants for definitions of the
>  .Va errno
>  libc global variable.
>  This is most often used in section 2 and 3 manual pages.
> @@ -2016,10 +2032,13 @@ Examples:
>  .Bd -literal -offset indent -compact
>  \&.Oo
>  \&.Op Fl flag Ns Ar value
>  \&.Oc
>  .Ed
> +.Pp
> +See also
> +.Ic \ .
>  .It Ic \ Ar line
>  Optional part of a command line.
>  Prints the argument(s) in brackets.
>  This is most often used in the
>  .Em SYNOPSIS
> @@ -2127,10 +2146,13 @@ See also
>  and
>  .Ic \ .
>  .It Ic \ Ar block
>  Multi-line version of
>  .Ic \ .
> +.Pp
> +See also
> +.Ic \ .
>  .It Ic \
>  Break a paragraph.
>  This will assert vertical space between prior and subsequent macros
>  and/or text.
>  .Pp
> @@ -2164,10 +2186,13 @@ and
>  .Ic \
>  .Fl literal .
>  .It Ic \ Ar block
>  Multi-line version of
>  .Ic \ .
> +.Pp
> +See also
> +.Ic \ .
>  .It Ic \ Ar line
>  Encloses its arguments in
>  .Qq typewriter
>  double-quotes.
>  Consider using
> @@ -2221,10 +2246,13 @@ Examples:
>  If an
>  .Ic \
>  block is used within a SEE ALSO section, a vertical space is asserted
>  before the rendered output, else the block continues on the current
>  line.
> +.Pp
> +See also
> +.Ic \ .
>  .It Ic \ Fl std Op Ar function ...
>  Insert a standard sentence regarding a function call's return value of 0
>  on success and \-1 on error, with the
>  .Va errno
>  libc global variable set on error.
> @@ -2277,10 +2305,13 @@ When called without an argument, the
>  macro toggles the spacing mode.
>  Using this is not recommended because it makes the code harder to read.
>  .It Ic \ Ar block
>  Multi-line version of
>  .Ic \ .
> +.Pp
> +See 

mdoc(7) closing macros in See also

2020-08-17 Thread Scott Bennett
Hi,

While learning the mdoc(7) markup language, I sometimes have trouble figuring
out which macros are used to close certain multi-line macros. It is certainly
not impossible to find the necessary closing macro to any arbitrary opening
macro, but for the macros that I use less often it can be a bit of a
scavenger hunt.

This could be much easier if the required closing macro were listed in the
"See also" section of the opening macro. In fact, there is already a precedent
in the Bf and Bl macros, which do list their closers (Ef and El, respectively)
in their "See also" sections.

I think the following patch could be useful to those starting to learn the
mdoc(7) language, or for anyone who prefers to jump right into the MACRO
REFERENCE section.

Thanks,
Scott Bennett

diff f7f933db8e4e532d6a39c747672ac5861ccd4883 
ced68e3867e5e6c3d2dc26f337effe036c033d47
blob - 7cbe1db136ad1619f26a599517c7c9b1d7e36ce8
blob + 45935846ab15de1500fd65ccb773c8371d614bbf
--- share/man/man7/mdoc.7
+++ share/man/man7/mdoc.7
@@ -677,10 +677,13 @@ Begin a block enclosed by angle brackets.
 Does not have any head arguments.
 This macro is almost never useful.
 See
 .Ic \
 for more details.
+.Pp
+See also
+.Ic \ .
 .It Ic \
 Inserts an apostrophe without any surrounding whitespace.
 This is generally used as a grammatical device when referring to the verb
 form of a function.
 .Pp
@@ -870,13 +873,14 @@ Examples:
Hello   world.
 \&.Ed
 .Ed
 .Pp
 See also
-.Ic \
+.Ic \ ,
+.Ic \ ,
 and
-.Ic \ .
+.Ic \ .
 .It Ic \ Fl emphasis | literal | symbolic | Cm \ | \ | \
 Change the font mode for a scoped block of text.
 The
 .Fl emphasis
 and
@@ -921,10 +925,13 @@ macro line:
 \&.Ek
 .Ed
 .Pp
 Be careful in using over-long lines within a keep block!
 Doing so will clobber the right margin.
+.Pp
+See also
+.Ic \ .
 .It Xo
 .Ic \
 .Fl Ns Ar type
 .Op Fl width Ar val
 .Op Fl offset Ar val
@@ -1062,10 +1069,12 @@ Examples:
 \&.Bo 1 ,
 \&.Dv BUFSIZ \
 .Ed
 .Pp
 See also
+.Ic \
+and
 .Ic \ .
 .It Ic \ Ar line
 Encloses its arguments in square brackets.
 .Pp
 Examples:
@@ -1095,10 +1104,12 @@ Examples:
 \&.Bro 1 , ... ,
 \&.Va n \
 .Ed
 .Pp
 See also
+.Ic \
+and
 .Ic \ .
 .It Ic \ Ar line
 Encloses its arguments in curly braces.
 .Pp
 Examples:
@@ -1275,10 +1286,12 @@ April is the cruellest month
 \&.Dc
 \e(em T.S. Eliot
 .Ed
 .Pp
 See also
+.Ic \
+and
 .Ic \ .
 .It Ic \ Ar line
 Encloses its arguments in
 .Dq typographic
 double-quotes.
@@ -1470,10 +1483,13 @@ An arbitrary enclosure.
 The
 .Ar opening_delimiter
 argument is used as the enclosure head, for example, specifying \e(lq
 will emulate
 .Ic \ .
+.Pp
+See also
+.Ic \ .
 .It Ic \ Ar identifier ...
 Error constants for definitions of the
 .Va errno
 libc global variable.
 This is most often used in section 2 and 3 manual pages.
@@ -2016,10 +2032,13 @@ Examples:
 .Bd -literal -offset indent -compact
 \&.Oo
 \&.Op Fl flag Ns Ar value
 \&.Oc
 .Ed
+.Pp
+See also
+.Ic \ .
 .It Ic \ Ar line
 Optional part of a command line.
 Prints the argument(s) in brackets.
 This is most often used in the
 .Em SYNOPSIS
@@ -2127,10 +2146,13 @@ See also
 and
 .Ic \ .
 .It Ic \ Ar block
 Multi-line version of
 .Ic \ .
+.Pp
+See also
+.Ic \ .
 .It Ic \
 Break a paragraph.
 This will assert vertical space between prior and subsequent macros
 and/or text.
 .Pp
@@ -2164,10 +2186,13 @@ and
 .Ic \
 .Fl literal .
 .It Ic \ Ar block
 Multi-line version of
 .Ic \ .
+.Pp
+See also
+.Ic \ .
 .It Ic \ Ar line
 Encloses its arguments in
 .Qq typewriter
 double-quotes.
 Consider using
@@ -2221,10 +2246,13 @@ Examples:
 If an
 .Ic \
 block is used within a SEE ALSO section, a vertical space is asserted
 before the rendered output, else the block continues on the current
 line.
+.Pp
+See also
+.Ic \ .
 .It Ic \ Fl std Op Ar function ...
 Insert a standard sentence regarding a function call's return value of 0
 on success and \-1 on error, with the
 .Va errno
 libc global variable set on error.
@@ -2277,10 +2305,13 @@ When called without an argument, the
 macro toggles the spacing mode.
 Using this is not recommended because it makes the code harder to read.
 .It Ic \ Ar block
 Multi-line version of
 .Ic \ .
+.Pp
+See also
+.Ic \ .
 .It Ic \ Ar line
 Encloses its arguments in
 .Sq typewriter
 single-quotes.
 .Pp
@@ -2675,10 +2706,13 @@ Extend the header of an
 macro or the body of a partial-implicit block macro
 beyond the end of the input line.
 This macro originally existed to work around the 9-argument limit
 of historic
 .Xr roff 7 .
+.Pp
+See also
+.Ic \ .
 .It Ic \ Ar name section
 Link to another manual
 .Pq Qq cross-reference .
 .Pp
 Cross reference the