[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[groff] 42/49: groff_mdoc(7): Revise "Conventions" section.

From: G. Branden Robinson
Subject: [groff] 42/49: groff_mdoc(7): Revise "Conventions" section.
Date: Sun, 6 Nov 2022 00:37:23 -0400 (EDT)

gbranden pushed a commit to branch master
in repository groff.

commit ce32810390500bba3fb52192c02b6578b2d0d907
Author: G. Branden Robinson <>
AuthorDate: Fri Nov 4 21:10:30 2022 -0500

    groff_mdoc(7): Revise "Conventions" section.
    * Drop discussion of angle brackets.  They should only be necessary when
      space doesn't separate parameters.
    * Make examples more realistic for experienced Unix users with a
      hypothetical "ztar" command and an actual "ls" one.
    * Recast discussion of implicit and explicit widths for
    * Perform a Kemper notectomy.
    * Stop using `Ic` where `Li` seems more appropriate.
    * Use `Bl`'s "-compact" flag; stop putting paragraph breaks after inline
    * Tighten wording.
    * Break input lines after commas.
    * Use an empty request between sentences.
    * Annotate a weirdness in `Bl` behavior (possibly poor understanding on
      my part).
 tmac/ | 106 +++++++++++++++++++++++++++++---------------------
 1 file changed, 62 insertions(+), 44 deletions(-)

diff --git a/tmac/ b/tmac/
index 115b3bfc1..e08b4d2d4 100644
--- a/tmac/
+++ b/tmac/
@@ -716,74 +716,92 @@ we use them to illustrate the use of page structure 
domain macros.
 .Sh Conventions
-In the description of all macros below, optional arguments are put into
+In the descriptions of macros below,
+square brackets surround optional arguments.
 An ellipsis
 .Pf ( Sq ... )
-represents zero or more additional arguments.
-Alternative values for a parameter are separated with
-.Ql | .
-If there are alternative values for a mandatory parameter, braces are used
-(together with
-.Ql | )
-to enclose the value set.
-Meta-variables are specified within angles.
+represents repetition of the preceding argument zero or more times.
+Alternative values of a parameter are separated with
+.Ql | .
+If a mandatory parameter can take one of several alternative values,
+use braces to enclose the set,
+with spaces and
+.Ql |
+separating the items.
-.Bl -tag -width 6n -offset indent
-.It Li .Xx Xo
-.Aq foo
-.Brq bar1 | bar2
-.Op \-test1 Op \-test2 | \-test3
-.No ...
+.\" XXX: Angle brackets should only be necessary when space doesn't
+.\" separate parameters.
+.\" .
+.\" Metasyntactic variables are specified within angle brackets.
+.\"Bl -tag -width 6n -offset indent -compact
+.Bl -tag -offset indent -compact
+.It Nm ztar Xo
+.Brq Cm c | Cm x
+.Op Fl w Op Fl y | Fl z
+.Op Fl f Ar archive
+.Ar member No ...
 Except where explicitly stated,
-all macros are parsed and callable.
+.Xr mdoc
+macros are parsed and callable.
-Note that a macro takes effect up to the next nested macro.
+Most macros affect subsequent arguments until another macro or a newline
+is encountered.
 For example,
-.Ql ".Ic foo Aq bar"
+.Sq Li ".Li ls Bq Ar file"
 doesn't produce
-.Sq Ic "foo <bar>"
-but rather
-.Sq Ic foo Aq bar .
+.Sq Li "ls [file]" ,
+.Sq Li ls Bq Ar file .
 a warning message is emitted for most commands if the first argument is
-a macro itself since it cancels the effect of the calling command
-.Sq Ic "foo <bar>"
-is produced by
-.Ql ".Ic \[dq]foo <bar>\[dq]" .
+itself a macro,
+since it cancels the effect of the preceding one.
+On rare occasions,
+you might want to format a word along with surrounding brackets as a
+.\" XXX: Why do we need the extra "\ " for the width parameter?  Without
+.\" it, the line breaks before the arrow on a 78n terminal.  But there
+.\" should be room anyway...bug?
+.Bl -tag -width "Li\ \[dq]ls\ [file]\[dq]\ " -offset indent -compact
+.It Li ".Li \[dq]ls [file]\[dq]"
+.Li "ls [file]"
+.Em "# list any files named e, f, i, or l"
-Most macros have a default width value that can be used to specify a
-label width
-.Pf ( Fl width )
-or offset
-.Pf ( Fl offset )
-for the
-.Ql .Bl
-.Ql .Bd
-It is recommended not to use this rather obscure feature to avoid
-dependencies on local modifications of the
+Many macros possess an implicit width,
+used when they are contained in lists and displays.
+If you avoid relying on these default measurements,
+you escape potential conflicts with site-local modifications of the
 .Xr mdoc
+.Fl width
+.Fl offset
+arguments to the
+.Ql \&Bl
+.Ql \&Bd
+macros are preferable.
 .Sh "Title macros"

reply via email to

[Prev in Thread] Current Thread [Next in Thread]