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 \&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 >
