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 \&Aq
for more details.
+.Pp
+See also
+.Ic \&Ac .
.It Ic \&Ap
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 \&D1
+.Ic \&D1 ,
+.Ic \&Dl ,
and
-.Ic \&Dl .
+.Ic \&Ed .
.It Ic \&Bf Fl emphasis | literal | symbolic | Cm \&Em | \&Li | \&Sy
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 \&Ek .
.It Xo
.Ic \&Bl
.Fl Ns Ar type
.Op Fl width Ar val
.Op Fl offset Ar val
@@ -1062,10 +1069,12 @@ Examples:
\&.Bo 1 ,
\&.Dv BUFSIZ \&Bc
.Ed
.Pp
See also
+.Ic \&Bc
+and
.Ic \&Bq .
.It Ic \&Bq Ar line
Encloses its arguments in square brackets.
.Pp
Examples:
@@ -1095,10 +1104,12 @@ Examples:
\&.Bro 1 , ... ,
\&.Va n \&Brc
.Ed
.Pp
See also
+.Ic \&Brc
+and
.Ic \&Brq .
.It Ic \&Brq 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 \&Dc
+and
.Ic \&Dq .
.It Ic \&Dq 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 \&Do .
+.Pp
+See also
+.Ic \&Ec .
.It Ic \&Er 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 \&Oc .
.It Ic \&Op 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 \&Sm .
.It Ic \&Po Ar block
Multi-line version of
.Ic \&Pq .
+.Pp
+See also
+.Ic \&Pc .
.It Ic \&Pp
Break a paragraph.
This will assert vertical space between prior and subsequent macros
and/or text.
.Pp
@@ -2164,10 +2186,13 @@ and
.Ic \&Bd
.Fl literal .
.It Ic \&Qo Ar block
Multi-line version of
.Ic \&Qq .
+.Pp
+See also
+.Ic \&Qc .
.It Ic \&Qq Ar line
Encloses its arguments in
.Qq typewriter
double-quotes.
Consider using
@@ -2221,10 +2246,13 @@ Examples:
If an
.Ic \&Rs
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 \&Re .
.It Ic \&Rv 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 \&So Ar block
Multi-line version of
.Ic \&Sq .
+.Pp
+See also
+.Ic \&Sc .
.It Ic \&Sq 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 \&Xc .
.It Ic \&Xr Ar name section
Link to another manual
.Pq Qq cross-reference .
.Pp
Cross reference the
