[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 37/49: groff_mdoc(7): Revise "Getting started" section.
G. Branden Robinson
[groff] 37/49: groff_mdoc(7): Revise "Getting started" section.
Sun, 6 Nov 2022 00:37:22 -0400 (EDT)
gbranden pushed a commit to branch master
in repository groff.
Author: G. Branden Robinson <firstname.lastname@example.org>
AuthorDate: Fri Nov 4 05:15:17 2022 -0500
groff_mdoc(7): Revise "Getting started" section.
* Refer to mdoc(7) macros without a leading dot. Not only are they
generally referred to with the `Ql` macro, which quotes them, but much
more than man(7) users, mdoc(7) writers need to grasp the fact that
the leading dot is not part of the macro's name.
* Dial down editorializing about how hard the roff language is to
acquire. mdoc ain't that easy, either, and it doesn't take long for
this man page to show the reader why.
* Define the term "call".
* Add cross references to roff(7) and groff(7) pages for conceptual and
* Identify (default) *roff control and escape characters as such. I
don't think anything is gained by obscuring this crucial information.
* When introducing the escape character, also present the input line
continuation escape sequence (`\newline`).
* Correct introductory presentation of `Fn` macro to more clearly
distinguish C language function parameters from mdoc macro parameters,
and remove falsehood about the C standard requiring identifiers in
function "delcarations". ANSI didn't and the language still doesn't.
The writer was thinking of function _definitions_.
* Identify `\ ` as the "unadjustable space escape sequence".
* Identify `\~` as the "unbreakable space escape sequence". Note its
good, but imperfect, portability. Add example of its use to group
words as macro arguments.
* Point out what's wrong with the counterexample when presenting the
specification of macro arguments.
* Rename subsection "Trailing Blank Space Characters" to "Trailing space
* Drop claim that the formatter "can be confused" by trailing spaces.
It can't. Perhaps the author of this text was confused by troff
syntax. (Alternatively, mdoc's innovative approach to argument
parsing might create problems where other macro packages would not
have them. Is it an accident that no other package works this way?)
* Rename subsection "Escaping Special Characters" to "Formatting the
backslash glyph" since that is all it is about.
* Add subsection "Other possible pitfalls".
* When telling people not to use the `"` character in macro arguments,
offer a forward cross reference to "Enclosure and quoting macros".
* Expand discussion of end-of-sentence detection and how to manage it.
* When cross referencing with `Sx`, identify target heading as "section"
or "subsection" as appropriate. A savvy reader can use this
information to find such headings more reliably with pagers (because
section headings are set flush left while subsections are indented)
and editors (because they use different macros).
* Set (sub)section headings in sentence case, even in cross references
to (sub)sections not yet revised. Forthcoming commits will make this
* Eschew use of `Tn`. We don't need to style "GNU" with it.
* Use `Em` to introduce technical terms. (Bafflingly, mandoc_mdoc(7) is
much less help than I expected. It says that `Em` is for "stress",
not "importance", and `Sy` is for "importance or seriousness", not
"stress". Ergo `Em` is for when you want to...stress things that
aren't important. ¿Qué? But `Em` gives the italics I wanted.)
* Tighten. For instance, who thought it was helpful to say "dot
character (`.\&`)" every time it was referred to? Introduce it once
and then move on. That's just one example of this page's garrulous
* Stop using an inline example after a colon as an excuse to avoid
punctuating a sentence.
* Use `Bl`'s "-compact" flag more and stop putting paragraph breaks
after inline examples. This moves the examples more obviously into
the running text. I don't see the point of the former ersatz displays
when the package (again unlike man(7)) seems to have serviceable
* Adjust "-width" of examples presented with `Bl`.
* Drop qualifier "blank" from "blank space". There are indeed many
kinds of spaces--but all are blank, so the modifier expresses nothing.
* Stop using the adverb "directly" in several different contexts to
suggest something the author meant to express but couldn't find the
* Fix grammar nits (lack of pluralization and so forth).
* Quote phrasal macro arguments to use the package more efficiently.
* Break input lines after commas, semicolons, and colons.
tmac/groff_mdoc.7.man | 374 +++++++++++++++++++++++++++++---------------------
1 file changed, 220 insertions(+), 154 deletions(-)
diff --git a/tmac/groff_mdoc.7.man b/tmac/groff_mdoc.7.man
index 2a6397dfd..0813511f1 100644
@@ -149,19 +149,36 @@ The
package attempts to simplify the process of writing a man page.
-one should not have to learn the tricky details of
-.Xr @g@troff @MAN1EXT@
-.Xr mdoc ;
-there are a few limitations that are unavoidable and best gotten out of
+One need not master the
+language to write them.
-And, too, be forewarned, this package is
+We present some essential facts about the formatter's language below.
+For further background,
+including a discussion of basic typographical concepts like
+.Dq breaking ,
+.Dq filling ,
+.Dq adjustment ,
+.Xr roff @MAN7EXT@ .
+Occasional mention is made of typgraphical units of measurement:
+.Dq n ,
+.Dq v ,
+.Dq i ,
+.Xr groff @MAN7EXT@ .
@@ -181,10 +198,14 @@ on the right.
.Ss "Macro usage"
-.Xr @g@troff ,
-a macro is called by placing a
+by placing the
at the beginning of a line followed by the two-
@@ -207,33 +228,42 @@ A dot followed immediately by a newline is ignored;
this is called the
.Em "empty request" .
-To place a dot
-at the beginning of an input line in some context other than a macro
-precede the dot with the
+To place a dot at the beginning of an input line in some context other
+than a macro call,
+precede it with the
this is a dummy character that is never displayed in the output.
+The backslash is the
+it can appear anywhere and it always followed by at least one more
+If followed by a newline,
+the backslash escapes the input line break,
+permitting input lines to kept to a reasonable length without affecting
+their interpretation by
+.Xr @g@troff .
-macros accept an unlimited number of arguments,
-in contrast to other versions of
-that can't handle more than nine arguments.
+accept an unlimited number of arguments,
+in contrast to other
+.Xr troff Ns No s
+that often can't handle more than nine.
In limited cases,
-arguments may be continued or extended on the next line
-.Sx Extended Arguments
+arguments may be continued or extended on the next input line
+.Sx "Extended arguments"
Almost all macros handle quoted arguments
.Sx "Passing space characters in an argument"
@@ -251,16 +281,15 @@ text or manual domain macro name
(and that is defined to be callable)
will be executed or called when it is processed.
-In this case the argument,
+In such cases,
although the name of a macro,
-is not preceded by a
+is not preceded by a dot.
This makes it possible to nest macros;
the option macro,
-.Ql .Op ,
+.Ql \&Op ,
the flag and argument macros,
@@ -269,7 +298,8 @@ and
.Ql \&Ar ,
to specify an optional flag with an argument.
-.Bl -tag -width ".Op\ Fl\ s\ Ar\ bytes" -offset indent -compact
+.\" Use width of second example below.
+.Bl -tag -width ".Op\ \e&Fl\ s\ \e&Ar bytes" -offset indent -compact
.It Li ".Op Fl s Ar bytes"
.Op Fl s Ar bytes
@@ -291,16 +321,18 @@ and
are not interpreted as macros.
-Macros whose argument lists are parsed for callable arguments are
+In this document,
+macros whose argument lists are parsed for callable arguments are
referred to as
.Em parsed ,
and those that may be called from an argument list are referred to as
-throughout this document.
+.Em callable .
This is a technical
-.Em "faux pas"
-as almost all of the macros in
+.Em "faux pas" ,
+since almost all of the macros in
but as it is cumbersome to constantly refer to macros as being callable
@@ -318,78 +350,79 @@ macro that starts a line
(with a leading dot)
-if this distinction is necessary.
+if a distinction from those appearing as arguments of other macros is
.Ss "Passing space characters in an argument"
Sometimes it is desirable to give as an argument a string containing one
-or more blank space characters,
+or more space characters,
to specify arguments to commands that expect a particular arrangement of
items in the argument list.
+quoting multi-word arguments that are to be treated the same makes
the function command
-expects the first argument to be the name of a function and any
+expects its first argument to be the name of a function and any
remaining arguments to be function parameters.
-stipulates the declaration of function parameters in the parenthesized
-each parameter is guaranteed to be at minimum a two word string.
+Because ANSI\~C mandates the inclusion of types
+identifiers in the parameter lists of function definitions,
+parameter after the first will be at least two words in length,
.Fa int foo .
-There are two possible ways to pass an argument that contains an
+There are a few possible ways to pass an argument that contains an
-One way of passing a string containing blank spaces is to use the hard
-or unpaddable space character
+One is to use the unadjustable space escape sequence
.Ql \e\ ,
-a blank space preceded by the escape character
-.Ql \e .
+a space preceded by the escape character.
-This method may be used with any macro but has the side effect of
-interfering with the adjustment of text over the length of a line.
+This method may be used with any macro,
+but has the side effect of not adjusting as other spaces do when an
+output line is formatted.
-sees the hard space as if it were any other printable character and
-cannot split the string into blank or newline separated pieces as one
-This method is useful for arguments that are not expected to overlap a
-An alternative is to use
-.Ql \e\[ti] ,
-(this is a
+treats the unadjustable space as if it were any other printable
+and will not break a line there as it would a normal space when the
+output line is full.
+This method is useful for macro arguments that are not expected to
+straddle an output line boundary.
+An alternative is to use the unbreakable space escape sequence,
+.Ql \[rs]\[ti] ,
+which cannot break but does adjust.
+extension is widely but not perfectly portable.
-The second method is to enclose the string with double quotes.
+Another method is to enclose the string with double quotes.
.Bl -tag -width ".Fn\ fetch\ \[dq]char\ *str\[dq]" -offset indent \
.It Li ".Fn fetch char\e *str"
.Fn fetch char\ *str
+.It Li ".Fn fetch char\e\[ti]*str"
+.Fn fetch char\~*str
.It Li ".Fn fetch \[dq]char *str\[dq]"
.Fn fetch "char *str"
@@ -398,10 +431,11 @@ The second method is to enclose the string with double
before the space in the first example
-or double quotes in the second example
+or double quotes in the third example
-would see three arguments.
+would see three arguments,
+and the result would contain an undesired comma.
.\" Use same width as before so it's easier to see the discrepancy.
.Bl -tag -width ".Fn\ fetch\ \[dq]char\ *str\[dq]" -offset indent \
@@ -412,7 +446,7 @@ would see three arguments.
.\" For an example of what happens when the parameter list overlaps a
.\" newline boundary,
.\" see the
@@ -420,88 +454,115 @@ would see three arguments.
-.Ss "Trailing Blank Space Characters"
+.Ss "Trailing space characters"
-can be confused by blank space characters at the end of a line.
-It is a wise preventive measure to globally remove all blank spaces
-.Ao blank-space Ac Ns Ao end-of-line Ac
-Should the need arise to use a blank character at the end of a line, it
-may be forced with an unpaddable space and the
-.Ql string\e\ \e& .
+.\" XXX: This claim of confusion is nonsense. The formatter ignores
+.\" them. If mdoc doesn't, that's a bug or design flaw. It's still
+.\" good style not to have them. Whitespace churn makes diff(1) and
+.\" revision control users unhappy.
+.\"can be confused by space characters at the end of a line.
+It is wise to remove trailing spaces from the ends of input lines.
-.Ss "Escaping Special Characters"
+Should the need arise to put a formattable space at the end of a line,
+do so with the unadjustable or unbreakable space escape sequences.
-Special characters like the newline character
-are handled by replacing the
-.Ql \een )
-to preserve the backslash.
+.Ss "Formatting the backslash glyph"
-.Ss "Other Possible Pitfalls"
+When you need the
+to appear in the output,
-A warning is emitted when an empty input line is found outside of
+formats the current escape character;
+it works reliably as long as no
+request is used to change it,
+which should never happen in man pages.
+is a special character escape sequence that explicitly formats the
+.Dq "reverse solidus"
-(It is even better to use
-macros to avoid the usage of low-level commands.)
+.Ss "Other possible pitfalls"
+.Xr "groff mdoc"
+emits a warning when an empty input line is found outside of a
+.Em display ,
+a topic presented in subsection
+.Sx "Examples and displays"
-Leading spaces will cause a break and are output directly.
+Leading spaces cause a break and are formatted.
Avoid this behaviour if possible.
-Similarly, do not use more than one space character between words in an
-ordinary text line; contrary to other text formatters, they are
-replaced with a single space.
+do not put more than one space between words in an ordinary text line;
+they are not
+to a single space as other text formatters might do.
-You can't pass
+Don't try to use the neutral double quote character
-directly as an argument.
+to represent itself in an argument.
+Use the special character escape sequence
+to format it.
+this glyph should not be used for conventional quotation;
+offers several quotation macros.
+.Sx "Enclosure and quoting macros"
-inserts two space characters after a punctuation mark ending a
+The formatter attempts to detect the endings of sentences and puts the
+equivalent of two spaces between sentences on the same output line.
-are treated transparently,
-not influencing the sentence-ending behaviour.
+after sentence-ending punctuation are ignored for this purpose.
-To change this,
+Sometimes you will want to end an input line with a
+.Ql \&. ,
+.Ql \&? ,
+that does not end a sentence.
+In a list of macro arguments,
-before or after the dot:
+before the punctuation mark.
-.Bd -literal -offset indent
+.Bd -literal -offset indent -compact
@@ -517,11 +578,9 @@ test
-.Bd -filled -offset indent
+.Bd -filled -offset indent -compact
@@ -543,32 +602,39 @@ test
-As can be seen in the first and third line,
+As can be seen in the first and third lines,
handles punctuation characters specially in macro arguments.
This will be explained in section
-.Sx General Syntax
+.Sx "General syntax"
-In the same way, you have to protect trailing full stops of
-abbreviations with a trailing non-printing input break:
-.Ql e.g.\e& .
+sentence-ending punctuation characters at the end of an input line that
+be suffixed with
+to keep them from being interpreted as sentence endings.
-A comment in the source file of a man page can be either started with
+A comment in the source file of a man page can begin with
-on a single line,
+at the start of an input line,
-after some input, or
+after other input,
(the last is a
-the rest of such a line is ignored.
+the remainder of any such line is ignored.
.Sh "A manual page template"
@@ -632,8 +698,8 @@ These commands identify the page and are discussed below in
-The remaining items in the template are section headers
-.Pf ( Li .Sh ) ;
+The remaining items in the template are section headings
+.Pf ( Ql \&Sh ) ;
.Em Name ,
.Em Synopsis ,
|[Prev in Thread]
||[Next in Thread]|
- [groff] 37/49: groff_mdoc(7): Revise "Getting started" section.,
G. Branden Robinson <=