[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 01/01: groff_man(7): Expand and revise.
|
From: |
G. Branden Robinson |
|
Subject: |
[groff] 01/01: groff_man(7): Expand and revise. |
|
Date: |
Sun, 4 Nov 2018 12:26:18 -0500 (EST) |
gbranden pushed a commit to branch master
in repository groff.
commit 4c8775e39cc13c3be71448536d4fc5fe76319efc
Author: G. Branden Robinson <address@hidden>
Date: Sun Nov 4 08:21:50 2018 -0500
groff_man(7): Expand and revise.
* tmac/groff_man.7.man:
+ Mark (with source comments) sections of the page that can
be moved to a separate groff man(7) tutorial document. My
plans for that will likely have to wait until after 1.22.4.
+ Refer to font "style" macros rather than font "face", for
consistency with groff terminology and to emphasize that
portable man pages have limited control over font selection.
+ Use the term "bold" instead of "boldface".
+ Refer to '\:' escape as a "discretionary break" rather than
"breakpoint", for better consistency with groff terminology
elsewhere. (E.g., a "break" is almost always a line break
on the output.)
+ Consistently refer to macros with the leading dot.
+ Follow the font-styling advice we give users.
+ Wordsmith language in general.
+ Macro reference preliminaries:
- Describe groff as a programming "system", not simply a
language.
- Parallelize use of infinitives.
+ Document structure macros:
- .TH: Name arguments more helpfully.
- .TH: Note when header-middle (man section) argument is
not necessary.
- .TH: Document style convention for footer-middle and
footer-outside arguments (formerly "extra1" and "extra2".)
- .SH: Use hyphenated noun phrase for macro argument.
- .SH: Note how text after the section heading is set, to
help man page writers avoid redundant .PP calls after .SH.
- .SH: Tell readers how to write the contents of the Name
section.
- .SH: Note standardization of man page section headings and
refer reader to man(7).
- .SS: Note how text after the section heading is set, to
help man page writers avoid redundant .PP calls after .SH.
- .EX/.EE: Separate discussion of what the macros do from
what they're used for.
- .RS: Rename argument from "nnn" to "indent".
- .RS: Note what the "default" 'indentation level' is (1).
+ Paragraph macros:
- .PP: Note that man macros indent paragraphs by default.
- .PP: Refer to .PP, .LP, and .P as "synonyms", rather than
"mutual aliases", which implies circularity and infinite
recursion when resolving them.
- .TP: Rename argument from "nnn" to "indent".
- .TQ: Note that .TQ was used to describe .LP, .PP, and .P.
+ Command synopsis macros:
- Improve introduction.
- .SY: Note that hyphenation is turned off.
- .OP: Note how arguments are set in terms of font styling.
- Describe use case for multiple .SY/.YS blocks.
- Describe use case for multiple .SYs before a .YS.
- Extend example to cover the above use cases.
- Explain utility of empty request.
+ Hyperlink and email macros:
- Add introductory paragraph.
- .MT/.ME: Cite RFC 6068 for format of email addresses.
- .MT/.ME: Note that the address argument may not be visible
in the document.
- .UR/.UE: Cite RFC 3986 for format of URLs.
- .UR/.UE: Note that the URL argument may not be visible
in the document.
+ Font style macros:
- Add introductory paragraphs. Admit long-standing problems
up front: (1) All you can get portably is roman, bold, and
italics. (2) Size changes with .SM and .SB are invisible
on nroff devices. (3) The three-font-problem sucks. (4)
It sure would have been nice to have semantic macros back
in the day instead of (just) presentational ones.
- .B: Add paragraph with usage recommendations.
- .I: Add paragraph with usage recommendations.
- .SM: Warn users that this macro has no visible effect on
nroff-style devices.
- .SB: Warn users that this macro has no visible effect on
nroff-style devices.
- Offer further markup and style advice.
- Add paragraph introducing two-font macros.
- Add real-life example of usage of each two-font macro,
drawn from groff's own man page corpus.
+ Add "Number registers" subsection for symmetry with other
macro packages' man pages, but forward-reference to the
"OPTIONS" section.
+ String registers:
- Describe existing string registers more precisely,
including conditional behavior.
+ Portability:
- Flag section for future migration to tutorial and style
guide.
- Undocument "\ " escape in favor of "\~". I checked its
portability a few months ago but lost my notes; the bottom
line is that I am personally convinced (for whatever
that's worth) that \~ is highly portable in the real world
and to be preferred over "\ " in man page usage. The only
other use case for "\ " that I can find is better served
by simply double-quoting macro arguments.
- Use a real example of \c from pdfroff(1).
- \f: Include parallel examples of solving the three-font
problem with \f and \c, so that readers can decide for
themselves which side to choose in the \f vs. \c (Ingo vs.
Branden) cold war. ;-)
+ Deprecated features:
- Describe what .AT actually does.
- Describe what .UC actually does.
- .HP: Rename argument from "nnn" to "indent".
- .PD: Rename argument from "nnn" to "vertical-space".
+ Add "History" subsection.
+ OPTIONS: Give arguments meaningful names.
+ NOTES: Offer a second method for getting desirable
indentation from .RS.
+ AUTHORS:
- Claim an authorship credit; I've done enough damage to get
some blame now.
- Credit Ingo with most of the material on portable escapes.
+ SEE ALSO:
- Lead off with a reference to the Texinfo manual.
- Explain some of the man page cross-references.
Signed-off-by: G. Branden Robinson <address@hidden>
---
ChangeLog | 7 +
NEWS | 6 +
tmac/groff_man.7.man | 1862 +++++++++++++++++++++++++++++++++-----------------
3 files changed, 1252 insertions(+), 623 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 5e2dea9..b33f237 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2018-11-04 G. Branden Robinson <address@hidden>
+
+ * tmac/groff_man.7.man: Reorganize and largely rewrite to more
+ precisely document the macro package's behavior and to be more
+ helpful and accessible to man page writers who may never read
+ any other groff documentation.
+
2018-10-25 G. Branden Robinson <address@hidden>
Clarify meaning of \p escape. Also make more explicit that line
diff --git a/NEWS b/NEWS
index 0e9296f..e52753b 100644
--- a/NEWS
+++ b/NEWS
@@ -80,6 +80,12 @@ o eqn2graph no longer supports the "-unsafe" option. It did
nothing.
o groffer now supports the output of XHTML. Use the "--xhtml" or
"--mode=xhtml" command-line options to generate it.
+o Much work has been done, and is ongoing, to make groff's man pages better
+ examples for man page writers to follow. groff_man(7) itself has been
+ expanded and largely rewritten to more precisely document the macro
+ package's behavior and to be more helpful and accessible to man page
+ writers who may never read any other groff documentation.
+
VERSION 1.22.3
==============
diff --git a/tmac/groff_man.7.man b/tmac/groff_man.7.man
index 1ce1403..a0a8e42 100644
--- a/tmac/groff_man.7.man
+++ b/tmac/groff_man.7.man
@@ -53,7 +53,7 @@ groff_man \- GNU roff macro package for formatting man pages
.\" ====================================================================
.
The
-.B man
+.I man
macro package for
.I groff
is used to produce manual pages
@@ -81,28 +81,28 @@ Macro Meaning Subsection
.T&
lB l l.
_
-\&.B Boldface Font face macros
-\&.BI Boldface, italic alternating Font face macros
-\&.BR Boldface, roman alternating Font face macros
+\&.B Bold Font style macros
+\&.BI Bold, italic alternating Font style macros
+\&.BR Bold, roman alternating Font style macros
\&.EE Example end Document structure macros
\&.EX Example begin Document structure macros
-\&.I Italic Font face macros
-\&.IB Italic, boldface alternating Font face macros
+\&.I Italic Font style macros
+\&.IB Italic, bold alternating Font style macros
\&.IP Indented paragraph Paragraph macros
-\&.IR Italic, roman alternating Font face macros
+\&.IR Italic, roman alternating Font style macros
\&.LP (Left) paragraph Paragraph macros
\&.ME Mail-to end Hyperlink and email macros
\&.MT Mail-to start Hyperlink and email macros
\&.OP (Command-line) option Command synopsis macros
\&.P Paragraph Paragraph macros
\&.PP Paragraph Paragraph macros
-\&.RB Roman, boldface alternating Font face macros
+\&.RB Roman, bold alternating Font style macros
\&.RE Relative-indent end Document structure macros
-\&.RI Roman, italic alternating Font face macros
+\&.RI Roman, italic alternating Font style macros
\&.RS Relative-indent start Document structure macros
-\&.SB Small boldface Font face macros
+\&.SB Small bold Font style macros
\&.SH Section heading Document structure macros
-\&.SM Small Font face macros
+\&.SM Small Font style macros
\&.SS Subection heading Document structure macros
\&.SY Synopsis start Command synopsis macros
\&.TH Title heading Document structure macros
@@ -156,10 +156,10 @@ exceptions are noted.
.PP
Bear in mind that
.I groff
-is fundamentally a programming language for typesetting.
+is fundamentally a programming system for typesetting.
.
Consequently,
-the verb \(lqset\(rq is frequently used below in the sense of \(lqto
+the verb \(lqto set\(rq is frequently used below in the sense \(lqto
typeset\(rq.
.
.
@@ -172,15 +172,16 @@ group of macros.
.
.B .TH
(title heading) identifies the document as a man page and defines
-fundamental information enabling its indexing by
-.BR mandb (8).
+information enabling its indexing by
+.IR mandb (8)
+or a similar tool.
+.
.
Sections
.RB ( .SH ),
one of which is mandatory and many of which are standardized,
-facilitate quick location of relevant information by the reader and aid
-the man page writer to comprehensively discuss all essential aspects of
-the topic.
+facilitate quick location of relevant material by the reader and aid
+the man page writer to discuss all essential aspects of the topic.
.
Subsections
.RB ( .SS )
@@ -205,154 +206,229 @@ macros.
.
.
.TP
-.BI .TH " title section \fR[\fPextra1\fR]\fP \fR[\fPextra2\fR]\fP
\fR[\fPextra3\fR]"
-Set the title of the man page to
+.BI .TH " title section"\c
+.RI " [" footer-middle ]\c
+.RI " [" footer-outside ]\c
+.RI " [" header-middle ]
+Define the title of the man page as
.I title
-and the section to
-.IR section ,
-which must take on a value between 1 and\~8.
+and the section as
+.IR section .
.
-The value
-.I section
-may also have a string appended, e.g.\& \[oq]pm\[cq], to indicate a
-specific subsection of the man pages.
+See
+.IR man (1)
+for details on the section numbers and suffixes applicable to your
+system.
.
-Both
.I title
and
.I section
-are positioned at the left and right in the header line (with
+are positioned together at the left and right in the header line
+(with
.I section
in parentheses immediately appended to
-.IR title .
+.IR title ).
.
-.I extra1
-is positioned in the middle of the footer line.
+.I footer-middle
+is centered in the footer line.
.
-.I extra2
+.I footer-outside
is positioned at the left in the footer line (or at the left on
even pages and at the right on odd pages if double-sided printing is
active).
.
-.I extra3
+.I header-middle
is centered in the header line.
.
+If
+.I section
+is a simple integer between 1 and\~9 (inclusive),
+or is exactly \(lq3p\(rq,
+there is no need to specify
+.IR header-middle ;
+the macro package will supply text for it.
+.
.
.IP
For HTML output, headers and footers are completely suppressed.
.
.
.IP
-Additionally, this macro starts a new page; the new line number is\~1
-again (except if the \[oq]\-rC1\[cq] option is given on the command
-line).
+Additionally, this macro starts a new page; the page number is reset
+to\~1
+(unless the
+.B \-rC1
+option is given on the command line).
+.
+This feature is intended only for formatting multiple man pages.
+.
+.
+.IP
+A man page should contain exactly one
+.B .TH
+call at or near the beginning of the file,
+prior to any other macro calls.
.
-This feature is intended only for formatting multiple man pages;
-a single man page should contain exactly one
-.B TH
-macro at the beginning of the file.
+.
+.IP
+By convention,
+.I footer-middle
+is the most recent modification date of the man page source document,
+and
+.I footer-outside
+is the name and version or release of the project providing it.
.
.
.TP
-.BI .SH " \fR[\fPtext for a heading\fR]\fP"
-Set up an unnumbered section heading sticking out to the left.
+.BR .SH " ["\c
+.IR heading-text ]
+Set
+.I heading-text
+as a section heading flush left.
.
-Prints out all the text following
+The text following
.B .SH
-up to the end of the line (or the text in the next input line if there
-is no argument to
-.BR .SH )
-in bold face
-(or the font specified by the string
-.BR HF ),
-one size larger than the base document size.
+up to the end of the line,
+or the text on the next input line if
+.B .SH
+is given no arguments,
+is set in bold
+(or the font specified by the string register
+.BR HF )
+slightly larger than the base font size.
.
-Additionally, the left margin and the indentation for the following
-text is reset to the default values.
+Additionally,
+the left margin and indentation affecting subsequent text are reset to
+their default values.
.
+Text on input lines after
+.I heading-text
+is set as a normal paragraph
+.RB ( .PP ).
.
-.TP
-.BI .SS " \fR[\fPtext for a heading\fR]\fP"
-Set up a secondary, unnumbered section heading.
.
-Prints out all the text following
+.IP
+The content of
+.I heading-text
+and ordering of sections has been standardized by common practice,
+as has much of the layout of material within sections.
+.
+For example,
+a section called \(lqName\(rq or \(lqNAME\(rq must exist,
+must be the first section after the
+.B .TH
+call,
+and must contain only a line of the form
+.RS \" Invisibly move left margin to current .IP indent.
+.RS \" Now indent further, visibly.
+.IR page-topic [\c
+.BR , " \&.\|.\|.\&]"
+.B \e\-\ \c
+.I summary-description
+.RE \" Move left margin back to .IP indentation.
+for a man page to be properly indexed.
+.
+See
+.IR man (7)
+for the conventions prevailing on your system.
+.RE \" Move left margin back to standard position.
+.
+.
+.TP
+.BR .SS " ["\c
+.IR subheading-text ]
+Set
+.I subheading-text
+as a subsection heading indented (by default) partway between a section
+heading and a normally-indented paragraph
+.RB ( .PP ).
+.
+The text following
+.B .SS
+up to the end of the line,
+or the text on the next input line if
.B .SS
-up to the end of the line (or the text in the next input line if there
-is no argument to
-.BR .SS )
-in bold face
-(or the font specified by the string
-.BR HF ),
-at the same size as the base document size.
+is given no arguments,
+is set in bold
+(or the font specified by the string register
+.BR HF )
+at the base font size.
.
-Additionally, the left margin and the indentation for the following
-text is reset to the default values.
+Additionally,
+the left margin and indentation affecting subsequent text are reset to
+their default values.
+.
+Text on input lines after
+.I subheading-text
+is set as a normal paragraph
+.RB ( .PP ).
.
.
.TP
.B .EX
.TQ
.B .EE
-Example/End Example.
+Begin and end example.
.
After
.BR .EX ,
-filling is disabled and the font is set to constant-width.
+filling and hyphenation are disabled and a constant-width (monospaced)
+font is selected.
.
-This is useful for formatting code, command, and configuration-file
-examples.
+Calling
+.B .EE
+enables filling and restores the previous hyphenation setting and font.
.
-The
-.B EE
-macro restores filling and restores the previous font.
.
+.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.IP
+Example regions are useful for formatting code,
+shell sessions,
+and text file contents.
.
+.
+.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
.IP
These macros are defined on many (but not all) legacy Unix systems
-running classic troff.
+running classic
+.IR troff .
.
To be certain your page will be portable to those systems, copy
their definitions from the
.I \%an\-ext.tmac
file of a
-.BR groff
+.I groff
installation.
.
.
.TP
-.BI .RS " \fR[\fPnnn\fR]\fP"
-This macro moves the left margin to the right by the value
-.I nnn
-if specified (default unit is \[oq]n\[cq]); otherwise it is set to the
-previous indentation value specified with
-.BR .TP ,
-.BR .IP ,
-or
-.B .HP
-(or to the default value if none of them have been used yet).
-.
-The indentation value is then set to the default.
+.BR .RS " ["\c
+.IR indent ]
+Move the left margin to the right by the value
+.IR indent ,
+if specified,
+and by a default amount otherwise;
+see subsection \(lqHorizontal and vertical spacing\(rq,
+below.
.
+Calls to
+.B .RS
+can be nested;
+each call increments by\~1 the indentation level used by
+.BR .RE .
.
-.IP
-Calls to the
-.B RS
-macro can be nested.
+The indentation level prior to any
+.B .RS
+calls is\~1.
.
.
.TP
-.BI .RE " \fR[\fPnnn\fR]\fP"
-This macro moves the left margin back to level
-.IR nnn ,
-restoring the previous left margin.
+.BR .RE " ["\c
+.IR level ]
+Move the left margin back to that corresponding to indentation level
+.IR level .
.
-If no argument is given, it moves one level back.
-.
-The first level (i.e., no call to
-.B .RS
-yet) has number\~1, and each call to
-.B .RS
-increases the level by\~1.
+If no argument is given, move the left margin one level back.
.
.
.\" ====================================================================
@@ -361,7 +437,8 @@ increases the level by\~1.
.
A typical paragraph
.RB ( .PP )
-is set at the current left margin.
+is set at the current left margin,
+which by default is indented from the left margin of the output device.
.
In man pages and other technical literature,
definition lists are frequently encountered;
@@ -386,52 +463,54 @@ or to present an itemized or ordered list.
.B .PP
.TQ
.B .P
-These macros are mutual aliases.
+Begin a new paragraph;
+these macros are synonymous.
.
-Any of them causes a line break at the current position, followed by a
-vertical space downwards by the amount specified by the
+They break the output line at the current position,
+followed by a vertical space downward by a default amount
+(which can be changed by the deprecated
.B PD
-macro.
+macro).
.
-The font size and shape are reset to the default value (normally 10pt
-Roman).
+The font size and style are reset to defaults;
+see subsection \(lqFont style macros\(rq,
+below.
.
-Finally, the current left margin and the indentation is reset to the
-default values.
+Finally, the left margin and indentation are reset to default values.
.
.
.TP
-.BI .TP " \fR[\fPnnn\fR]\fP"
-Set up an indented paragraph with label.
-.
-The indentation is set to
-.I nnn
-if that argument is supplied (the default unit is \[oq]n\[cq] if omitted),
-otherwise it is set to the previous indentation value specified with
-.BR .TP ,
-.BR .IP ,
-or
-.B .HP
-(or to the default value if none of them have been used yet).
+.BR .TP " ["\c
+.IR indent ]
+Set a tagged, indented paragraph.
.
+The input line following this macro,
+known as the
+.IR tag ,
+is printed at the current left margin.
.
-.IP
-The first input line of text following this macro is interpreted as a
-string to be printed flush-left, as it is appropriate for a label.
+Subsequent text is indented by
+.IR indent ,
+if specified,
+and by a default amount otherwise;
+see subsection \(lqHorizontal and vertical spacing\(rq,
+below.
.
-It is not interpreted as part of a paragraph, so there is no attempt
-to fill the first line with text from the following input lines.
.
-Nevertheless, if the label is not as wide as the indentation the
-paragraph starts at the same line (but indented), continuing on the
-following lines.
+.IP
+If the tag is not as wide as the indentation,
+the paragraph starts on the same line as the tag,
+at the applicable indentation,
+and continues on the following lines.
.
-If the label is wider than the indentation the descriptive part of the
-paragraph begins on the line following the label, entirely indented.
+Otherwise,
+the descriptive part of the paragraph begins on the line following the
+tag,
+entirely indented.
.
-Note that neither font shape nor font size of the label is set to a
-default value; on the other hand, the rest of the text has default
-font settings.
+The line containing the tag can include a macro call,
+for instance to set the tag in bold with
+.BR .B .
.
.
.IP
@@ -445,161 +524,193 @@ the subsequent ones.
.
.TP
.B .TQ
-The
-.B TQ
-macro sets up header continuation for a
-.B TP
-macro.
+Set an additional tag for a paragraph tagged with
+.BR .TP .
.
-With it, you can stack up any number of labels (such as in a
-glossary, or list of commands) before beginning the indented
-paragraph.
+The pending output line is broken.
.
-For an example, look up the documentation of the
-.BR LP ,
-.BR PP ,
-and
-.BR P
-macros.
+The tag on the input line following this macro and subsequent lines are
+handled as with
+.BR .TP .
.
.
.IP
This macro is not defined on legacy Unix systems running classic
-troff.
+.IR troff .
.
To be certain your page will be portable to those systems,
copy its definition from the
.I \%an\-ext.tmac
file of a
-.BR groff
+.I groff
installation.
.
.
+.IP
+The descriptions of
+.BR .LP ,
+.BR .PP ,
+and
+.BR .P
+above were written using
+.B .TP
+and
+.BR .TQ .
+.
+.
.TP
-.BI .IP " \fR[\fPdesignator\fR]\fP \fR[\fPnnn\fR]\fP"
-Set up an indented paragraph, using
-.I designator
-as a tag to mark its beginning.
+.BR .IP " ["\c
+.IR tag "] "\c
+.RI [ indent ]
+Set an indented paragraph with an optional tag.
.
-The indentation is set to
-.I nnn
-if that argument is supplied (the default unit is \[oq]n\[cq] if
-omitted), otherwise it is set to the previous indentation value
-specified with
+The
+.I tag
+and
+.I indent
+arguments,
+if present,
+are handled as with
.BR .TP ,
-.BR .IP ,
-or
-.B .HP
-(or to the default value if none of them have been used yet).
-.
-Font size and face of the paragraph (but not the designator) are reset
-to its default values.
+with the exception that the
+.I tag
+argument to
+.B .IP
+cannot include a macro call.
.
.
+.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
.IP
-To start an indented paragraph with a particular indentation but
-without a designator, use \[oq]""\[cq] (two doublequotes) as the
-first argument.
-.
+Two convenient use cases for
+.B .IP
+are
.
-.IP
-For example, the following paragraphs were all set up with bullets as
-the designator, using \[oq].IP\ \e(bu\ 4\[cq].
.
-The whole block has been enclosed with
-.B .RS
+.RS \" Invisibly move left margin to current .IP indent.
+.RS \" Now indent further, visibly.
+.IP (1) 4n
+to start a new paragraph with the same indentation as the previous
+.B .IP
+or
+.B .TP
+paragraph,
+if no
+.I indent
+argument is given;
and
-.B .RE
-to set the left margin temporarily to the current indentation value.
.
.
-.RS
-.IP \(bu 4
-.B IP
-is one of the three macros used in the
-.B man
-package to format lists.
-.
+.IP (2)
+to set a paragraph with a short
+.I tag
+that is not semantically important,
+such as a bullet (\(bu)\(emobtained with the \(oq\e(bu\(cq character
+escape\(emor list enumerator,
+as seen in this very paragraph.
+.RE \" Move left margin back to .IP indentation.
+.RE \" Move left margin back to standard position.
.
-.IP \(bu 4
-.B HP
-is another.
.
-This macro produces a paragraph with a left hanging indentation.
+.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.\" ====================================================================
+.SS "Command synopsis macros"
+.\" ====================================================================
.
+Command synopses are a staple of section\~1 and\~8 man pages.
.
-.IP \(bu 4
-.B TP
-is another.
+These macros aid you to construct one that has the classical Unix
+appearance.
.
-This macro produces an unindented label followed by an indented
-paragraph.
-.RE
+Furthermore,
+some tools are able to interpret these macros semantically and treat
+them appropriately for localization and/or presentation.
.
+A command synopsis is wrapped in
+.BR .SY / .YS
+calls,
+with command-line options of some formats indicated by
+.BR .OP .
.
-.\" ====================================================================
-.SS "Command synopsis macros"
-.\" ====================================================================
.
-The following macros are not defined on legacy Unix systems
-running classic troff.
+.PP
+These macros are not defined on legacy Unix systems running classic
+.IR troff .
.
-To be certain your page will be portable to those systems, copy their
-definitions from the
+To be certain your page will be portable to those systems, copy
+their definitions from the
.I \%an\-ext.tmac
file of a
-.BR groff
+.I groff
installation.
.
.
-.PP
-These macros are a convenience for authors.
-.
-Together, they produce the traditional look of a Unix command synopsis.
-.
-They also assist automated translation tools and help browsers in
-recognizing command synopses and treating them differently from
-running text.
-.
-.
.TP
.BI .SY " command"
Begin synopsis.
.
-Takes a single argument, the name of a command.
+Hyphenation is turned off.
+.
+The
+.I command
+argument is set in bold.
.
-Text following, until closed by
-.BR .YS ,
-is set with a hanging indentation of the width of
+The output line is filled as normal,
+but if a break is required,
+subsequent output lines are indented by the width of
.I command
plus a space.
.
-Hyphenation is turned off.
-.
.
.TP
.BI .OP " option-name"\/\c
.RI " [" option-argument ]
Indicate an optional command parameter called
-.IR option-name .
+.IR option-name ,
+which is set in bold.
.
If the option takes an argument, specify
.I option-argument
using a noun, abbreviation, or hyphenated noun phrase.
.
+If present,
+.I option-argument
+is preceded by a space and set in italics.
+.
+Square brackets (in roman) surround both arguments.
+.
.
.TP
.B .YS
End synopsis.
.
-Restores indentation and hyphenation to previous values.
+Restore indentation and hyphenation to previous values.
.
.
.PP
+Multiple
+.B .SY/.YS
+blocks can be specified,
+for instance to distinguish differing modes of operation of a complex
+command like
+.IR tar (1);
+each will be separated by a paragraph space.
+.
+.
+.PP
+.B .SY
+can also be repeated multiple times before a closing
+.BR .YS ,
+which is useful to indicate synonymous ways of invoking a particular
+mode of operation.
+.
+.
+.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.PP
For example,
.
.
.IP
+.\" from src/roff/groff/groff.1.man
.EX
\&.SY groff
\&.OP \e\-abcegiklpstzCEGNRSUVXZ
@@ -621,6 +732,16 @@ For example,
\&.RI [ file
\e&.\e|.\e|.\e&]
\&.YS
+\&.
+\&.SY groff
+\&.B \e\-h
+\&.SY groff
+\&.B \e\-\e\-help
+\&.YS
+.
+.
+.IP
+
.EE
.
.
@@ -650,35 +771,40 @@ produces the following output.
.RI [ file
\&.\|.\|.\&]
.YS
+.
+.SY groff
+.B \-h
+.SY groff
+.B \-\-help
+.YS
.RE
.
.
.PP
-Multiple
-.B .SY/.YS
-blocks can be specified,
-for instance to distinguish differing modes of operation of a complex
-command like
-.BR tar (1);
-each will be separated by a paragraph space.
+Several features of the above example are of note.
+.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.\" TODO: Some of the normative discussion below can go there, too.
.
-If necessary, you can use a
-.B br
-request to insert a mandatory line break.
.
+.IP \(bu
+The empty request (.),
+which does nothing,
+is used for vertical spacing in the input file for readability by the
+document maintainer.
.
-.PP
-Several features of the above example are of note.
+Do not put empty lines in a
+.I roff
+source document.
.
.
.IP \(bu
The command and option names are presented in
-.B boldface
+.B bold
to cue the user that they should be input literally.
.
.
.IP \(bu
-Option dashes are specified with the \(lq\e\-\(rq escape sequence;
+Option dashes are specified with the \(oq\e\-\(cq escape sequence;
this is an important practice to make them clearly visible and to
facilitate cut-and-paste from the rendered man page to a shell prompt or
text file.
@@ -693,7 +819,7 @@ to cue the user that they must be replaced with appropriate
text.
.
.IP \(bu
Symbols that are neither to be typed literally nor simply replaced
-appear in plain (roman) style;
+appear in the roman style;
brackets surround optional arguments,
and an ellipsis indicates that the previous syntactical element may be
repeated arbitrarily.
@@ -702,7 +828,7 @@ repeated arbitrarily.
.IP
Some man pages use a brace-and-pipe notation such as
.RB \(lq{ \-\-diff | \-\-compare }\(rq
-to indicate that one and only one of the \(lq|\(rq-separated items
+to indicate that one and only one of the \(oq|\(cq-separated items
within the braces must be input.
.
If this braced construct is furthermore surrounded by square brackets,
@@ -711,229 +837,515 @@ it means that at most one of the items is accepted.
.
.IP
Authors of man pages should note the use of the zero-width space
-escape sequence \(lq\e&\(rq on both sides of the ellipsis;
+escape sequence \(oq\e&\(cq on both sides of the ellipsis;
this is a good practice to avoid surprises in the event the ellipsis
-gets reflowed in your text editor.
+gets refilled in your text editor.
.
See \(lqPortability\(rq, below.
.
The morbidly curious may consult
-.BR groff (7)
-regarding the narrow-space escape sequence \(lq\e|\(rq.
+.IR groff (7)
+regarding the narrow-space escape sequence \(oq\e|\(cq.
.
.
.\" ====================================================================
.SS "Hyperlink and email macros"
.\" ====================================================================
.
-The following macros are not defined on legacy Unix systems
-running classic troff.
+Email addresses are bracketed with
+.BR .MT / .ME
+and URL hyperlinks with
+.BR .UR / .UE .
+.
+.
+.PP
+These macros are not defined on legacy Unix systems running classic
+.IR troff .
.
To be certain your page will be portable to those systems, copy
their definitions from the
.I \%an\-ext.tmac
file of a
-.B groff
+.I groff
installation.
.
.
-.PP
-Using these macros helps ensure that you get hyperlinks when your
-manual page is rendered in a browser or other program that is
-Web-enabled.
-.
-.
.TP
.BI .MT " address"
.TQ
-.BI .ME " \fR[\fPpunctuation\fR]\fP"
-Wrap an email address.
+.BR .ME " ["\c
+.IR punctuation ]
+Identify
+.I address
+as an RFC 6068
+.I addr-spec
+for a \(lqmailto:\(rq URI with the text between the two macro
+calls as the link text.
+.
+A
+.I punctuation
+argument to
+.B .ME
+is placed at the end of the link text without intervening space.
.
-The argument of
-.B .MT
-is the address; text following, until
-.BR .ME ,
-is a name to be associated with the address.
-.
-Any argument to the
-.B ME
-macro is pasted to the end of the link text.
+Note that
+.I address
+may not be visible in the output text,
+particularly if the man page is being viewed as HTML.
.
On a device that is not a browser,
+.I address
+is set in angle brackets after the link text and before
+.IR punctuation .
.
.
+.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.IP
+When rendered by
+.I groff
+to a TTY or PostScript output device,
.RS
.IP
.EX
-contact
+Contact
\&.MT address@hidden:fubar.net
Fred Foonly
\&.ME
-for more information
+for more information.
.EE
.RE
.
.
.IP
-usually displays like this: \[lq]contact Fred Foonly
-<address@hidden:fubar.net> for more information\[rq].
+displays as: \(lqContact Fred Foonly
+\(address@hidden:fubar.net\(ra for more information.\(rq.
.
.
.IP
-The use of
-.B \e:
-to insert hyphenless breakpoints is a groff extension and can
-be omitted.
+The use of \(oq\e:\(cq to insert hyphenless discretionary breaks is a
+.I groff
+extension and can be omitted.
.
.
+.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
.TP
.BI .UR " URL"
.TQ
-.BI .UE " \fR[\fPpunctuation\fR]\fP"
-Wrap a World Wide Web hyperlink.
-.
-The argument to
-.B .UR
-is the URL; thereafter, lines until
+.BR .UE " ["\c
+.IR punctuation ]
+Identify
+.I URL
+as an RFC 3986 URI hyperlink with the text between the two macro calls
+as the link text.
+.
+A
+.I punctuation
+argument to
.B .UE
-are collected and used as the link text.
+is placed at the end of the link text without intervening space.
.
-Any argument to the
-.B UE
-macro is pasted to the end of the text.
+Note that
+.I URL
+may not be visible in the output text,
+particularly if the man page is being viewed as HTML.
.
On a device that is not a browser,
+.I URL
+is set in angle brackets after the link text and before
+.IR punctuation .
.
.
+.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.IP
+When rendered by
+.I groff
+to a TTY or PostScript output device,
.RS
.IP
.EX
-this is a link to
-\&.UR http://\e:randomsite.org/\e:fubar
-some random site
-\&.UE ,
-given as an example
+The GNU Project of the Free Software Foundation hosts the
+\&.UR https://\e:www.gnu.org/\e:software/\e:groff/
+Groff home page
+\&.UE .
.EE
.RE
.
.
.IP
-usually displays like this: \[lq]this is a link to some random
-site \[la]http://\:randomsite.org/\:fubar\[ra], given as an
-example\[rq].
+displays as: \(lqThe GNU Project of the Free Software Foundation hosts
+the Groff home page
+\(lahttps://\:www.gnu.org/\:software/\:groff/\(ra.\(rq.
.
.
.IP
-The use of
-.B \e:
-to insert hyphenless breakpoints is a groff extension and can be
-omitted.
+The use of \(oq\e:\(cq to insert hyphenless discretionary breaks is a
+.I groff
+extension and can be omitted.
.
.
+.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
.\" ====================================================================
-.SS "Font face macros"
+.SS "Font style macros"
.\" ====================================================================
.
+The
+.I man
+macro package is limited in its font styling options,
+offering only
+.BR bold \~( .B ),
+.I italic\c
+.RB \~( .I ),
+and roman (the default).
+.
+Italic text is usually set underscored instead on terminals and other
+classical
+.IR nroff -style
+output devices.
+.
+The
+.B .SM
+and
+.B .SB
+macros set text in roman or bold, respectively, at a smaller point size;
+these differ visually from regular-sized roman or bold text only on
+.IR troff -style
+output devices.
+.
+The foregoing macros cause word breaks before and after their arguments,
+but it is often necessary to set text in different styles without
+intervening whitespace.
+.
+The macros
+.BR .BI ,
+.BR .BR ,
+.BR .IB ,
+.BR .IR ,
+.BR .RB ,
+and
+.BR .RI ,
+where \(oqB\(cq, \(oqI\(cq, and \(oqR\(cq indicate bold, italic, and
+roman, respectively,
+set their odd- and even-numbered arguments in alternating styles,
+with no whitespace separating them.
+.
+.
+.PP
+Because font styles are presentational rather than semantic,
+conflicting traditions have arisen regarding which font styles should be
+used to mark file or path names,
+environment variables,
+in-line literals,
+and even man page cross-references.
+.
+.
+.PP
The default font size and family (for
.I troff
output devices)
is 10-point Times.
.
-The default face is roman.
+The default style is roman.
.
.
.TP
-.BI .B " \fR[\fPtext\fR]\fP"
-Causes
+.BR .B \~[\c
+.IR text ]
+Set
.I text
-to appear in bold face.
+in bold.
+.
+If the macro is given no arguments,
+the text of the next input line is set in bold.
+.
+.
+.\" BEGIN USAGE (TODO: move to tutorial/style guide when we have it)
+.IP
+Use bold
+for literal portions of syntax synopses,
+for command-line options in running text,
+and for literals that are major topics of the subject under discussion;
+for example,
+this page uses bold for macro and register names.
+.
+In
+.BR .EX / .EE
+examples of interactive I/O (such as a shell session),
+set only the user-typed input in bold.
.
-If no text is present on the line where the macro is called the text
-of the next input line appears in bold face.
.
.
+.\" END USAGE (TODO: move to tutorial/style guide when we have it)
.TP
-.BI .I " \fR[\fPtext\fR]\fP"
-Causes
+.BR .I \~[\c
+.IR text ]
+Set
.I text
-to appear in italic.
+in italics.
.
-If no text is present on the line where the macro is called the text
-of the next input line appears in italic.
+If the macro is given no arguments,
+the text of the next input line is set in italics.
.
.
-.TP
-.BI .SM " \fR[\fPtext\fR]\fP"
-Causes the text on the same line or the text on the next input line to
-appear in a font that is one point size smaller than the default font.
+.\" BEGIN USAGE (TODO: move to tutorial/style guide when we have it)
+.IP
+Use italics
+for file and path names,
+for environment variables,
+for enumeration or preprocessor constants in C,
+for variable (user-determined) portions of syntax synopses,
+for the first occurrence only of a technical concept being introduced,
+for names of works of software
+(including commands and functions,
+.\" The following is an interesting exception that seems to have arisen
+.\" organically and nearly universally.
+but excluding names of operating systems or their kernels),
+and anywhere a parameter requiring replacement by the user is
+encountered.
+.
+An exception involves variable text in a context that is already marked
+up in italics,
+such as file or path names with variable components;
+in such cases,
+follow the convention of mathematical typography:
+set the file or path name in italics as usual
+(see
+.B .IR
+below),
+but use roman for the variable part,
+and italics again in running roman text when referring to the variable
+material.
+.
+.
+.\" END USAGE (TODO: move to tutorial/style guide when we have it)
+.TP
+.BR .SM \~[\c
+.IR text ]
+Set
+.I text
+one point size smaller that the default size.
.
+If the macro is given no arguments,
+the text of the next input line is set smaller.
.
-.TP
-.BI .SB " \fR[\fPtext\fR]\fP"
-Causes the text on the same line or the text on the next input line to
-appear in boldface font, one point size smaller than the default font.
.
+.IP
+.IR Note :
+.IR nroff -style
+output devices,
+such as terminals,
+will render
+.I text
+at the normal font size instead.
.
-.TP
-.BI ".BI " text
-Causes text on the same line to appear alternately in bold face and
-italic.
+Do not rely upon
+.B .SM
+to communicate semantic information distinct from using roman style at
+the normal size;
+it will be hidden from readers using such devices.
.
-The text must be on the same line as the macro call.
.
-Thus
+.TP
+.BR .SB \~[\c
+.IR text ]
+Set
+.I text
+in bold,
+one point size smaller that the default size.
+.
+If the macro is given no arguments,
+the text of the next input line is set smaller and in bold.
.
.
-.RS
.IP
-\&.BI this "word and" that
+.IR Note :
+.IR nroff -style
+output devices,
+such as terminals,
+will render
+.I text
+in bold at the normal font size instead.
+.
+Do not rely upon
+.B .SB
+to communicate semantic information distinct from using bold style at
+the normal size;
+it will be hidden from readers using such devices.
.
.
+.\" BEGIN USAGE (TODO: move to tutorial/style guide when we have it)
.PP
-would cause \[oq]this\[cq] and \[oq]that\[cq] to appear in bold face,
-while \[oq]word and\[cq] appears in italics.
+Note what is
+.I not
+prescribed for setting in bold or italics above:
+elements of \(lqsynopsis language\(rq such as ellipses and brackets
+around options;
+proper names and adjectives;
+titles of anything other than works of literature or software;
+identifiers for standards documents or technical reports such as
+CSTR\~#54,
+RFC\~1918,
+Unicode\~11.0,
+or
+POSIX.1-2017;
+acronyms;
+and occurrences after the first of a technical term or piece of jargon.
+.
+Again,
+the names of operating systems and their kernels are,
+by practically universal convention,
+set in roman.
+.
+.
+.PP
+Be frugal with the use of italics for emphasis,
+and particularly with the use of bold.
+.
+Brief runs of literal text,
+such as references to individual characters or short strings,
+including section and subsection headings of man pages,
+are suitable objects for quotation;
+see the
+\(oq\e(lq\(cq,
+\(oq\e(rq\(cq,
+\(oq\e(oq\(cq,
+and
+\(oq\e(cq\(cq
+escapes in the subsection \(lqPortability\(rq,
+below.
+.
+.
+.\" END USAGE (TODO: move to tutorial/style guide when we have it)
+.PP
+Unlike the above font style macros,
+the font alternation macros below accept only arguments on the same
+line as the macro call.
+.
+If whitespace is required within one of the arguments,
+first consider whether the same result could be achieved with as much
+clarity by using the single-style macros on separate input lines.
+.
+When it cannot,
+double-quote an argument with one or more embedded space characters.
+.
+Setting all three different styles within one whitespace-delimited word
+presents challenges;
+it is possible with the \(oq\ec\(cq and/or \(oq\ef\(cq escapes,
+but see subsection \(lqPortability\(rq below for caveats.
+.
+.
+.TP
+.BI .BI " bold-text italic-text"\c
+\~\&.\|.\|.\&
+Set each argument in bold and italics, alternately.
+.
+.
+.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.RS
+.IP
+.\" from src/roff/troff/troff.1.man
+.EX
+\&.BI \e\-r name = n
+.EE
.RE
.
.
+.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
.TP
-.BI ".BR " text
-Causes text on the same line to appear alternately in bold face and
-roman.
+.BI .BR " bold-text roman-text"\c
+\~\&.\|.\|.\&
+Set each argument in bold and roman, alternately.
.
-The text must be on the same line as the macro call.
+.
+.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.RS
+.IP
+.\" from tmac/groff_ms.7.man
+.EX
+Any such change becomes effective with the first use of
+\&.BR .NH ,
+\&.I after
+the new alias is defined.
+.EE
+.RE
.
.
+.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
.TP
-.BI ".IB " text
-Causes text to appear alternately in italic and bold face.
+.BI .IB " italic-text bold-text"\c
+\~\&.\|.\|.\&
+Set each argument in italics and bold, alternately.
.
-The text must be on the same line as the macro call.
+.
+.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.RS
+.IP
+.\" from man/groff_tmac.5.man
+.EX
+All macro package files must be named
+\&.IB name .tmac
+to fully use the
+\&.I tmac
+mechanism.
+.EE
+.RE
.
.
+.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
.TP
-.BI ".IR " text
-Causes text on the same line to appear alternately in italic and
-roman.
+.BI .IR " italic-text roman-text"\c
+\~\&.\|.\|.\&
+Set each argument in italics and roman, alternately.
+.
.
-The text must be on the same line as the macro call.
+.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.RS
+.IP
+.\" from man/groff_out.5.man
+.EX
+This is the first command of the
+\&.IR prologue .
+.EE
+.RE
.
.
+.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
.TP
-.BI ".RB " text
-Causes text on the same line to appear alternately in roman and bold
-face.
+.BI .RB " roman-text bold-text"\c
+\~\&.\|.\|.\&
+Set each argument in roman and bold, alternately.
+.
.
-The text must be on the same line as the macro call.
+.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.RS
+.IP
+.\" from src/preproc/eqn/eqn.1.man
+.EX
+Also, the statement
+\&.RB \e(oq "delim on" \e(cq
+is not handled specially.
+.RE
+.EE
.
.
+.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
.TP
-.BI ".RI " text
-Causes text on the same line to appear alternately in roman and
-italic.
+.BI .RI " roman-text italic-text"\c
+\~\&.\|.\|.\&
+Set each argument in roman and italics, alternately.
.
-The text must be on the same line as the macro call.
+.
+.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
+.RS
+.IP
+.\" from contrib/mm/groff_mm.7.man
+.EX
+\&.RI [ file
+\e&.\e|.\e|.\e&]
+.EE
+.RE
.
.
+.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
.\" ====================================================================
.SS "Horizontal and vertical spacing"
.\" ====================================================================
@@ -973,7 +1385,7 @@ or (2)
.BR .SS ,
or
.B .PP
-or its synonyms is made;
+or its synonyms is called;
these clear the indent entirely.
.
.
@@ -999,10 +1411,10 @@ is 7.2n in
.I troff
mode and 7n in
.I nroff
-mode,
-except for
-.BR grohtml ,
-which ignores indentation.
+mode.
+.
+The HTML output device is an exception;
+it ignores indentation completely.
.
This same indentation is used again (additively) for the defaults of
.BR .IP ,
@@ -1032,23 +1444,29 @@ check,
or which is developed in the future.
.
The table preprocessor
-.BR tbl (1)
+.IR @address@hidden (@MAN1EXT@)
can likely meet your needs.
.
.
.PP
The following macros cause a line break with the
insertion of vertical space:
-.BR SH ,
-.BR SS ,
-.BR TP ,
-.BR TQ ,
-.B LP
-.RB ( PP ,
-.BR P ),
-.BR IP ,
+.BR .SH ,
+.BR .SS ,
+.BR .TP ,
+.BR .TQ ,
+.B .PP
+(and its synonyms),
+.BR .IP ,
and the deprecated
-.BR HP .
+.BR .HP .
+.
+The default inter-section and inter-paragraph spacing is 1\~line in
+.I nroff
+mode,
+and 0.4v in
+.I troff
+mode.
.
(The deprecated macro
.B .PD
@@ -1056,50 +1474,64 @@ can change this vertical spacing,
but its use is discouraged.)
.
The macros
-.BR RS ,
-.BR RE ,
-.BR EX ,
+.BR .RS ,
+.BR .RE ,
+.BR .EX ,
and
-.B EE
+.B .EE
also cause a break but no insertion of vertical space.
.
.
.\" ====================================================================
+.SS "Number registers"
+.\" ====================================================================
+.
+Number registers are described in section \(lqOPTIONS\(rq, below.
+.
+.
+.\" ====================================================================
.SS "String registers"
.\" ====================================================================
.
-The following strings are defined:
+The following strings are defined.
.
.
.TP
.B \e*R
-The \[oq]registered\[cq] sign.
+expands to the character escape for the \(lqregistered sign\(rq glyph,
+\(oq\e(rg\(cq,
+if available,
+and \(lq(Reg.)\(rq otherwise.
+.
.
.
.TP
.B \e*S
-Switch back to the default font size.
+expands to an escape setting the font size to the document default.
.
.
.TP
-.B \e*(lq
-.TQ
-.B \e*(rq
-Left and right quote.
+.B \e*(HF
+expands to the font identifier used to print headings and subheadings.
.
-This is equal to \[oq]\e(lq\[cq] and \[oq]\e(rq\[cq], respectively.
+The default is \(oqB\(cq.
.
.
.TP
-.B \e*(HF
-The typeface used to print headings and subheadings.
-.
-The default is \[oq]B\[cq].
+.B \e*(lq
+.TQ
+.B \e*(rq
+expand to the character escapes for left and right double-quotation
+marks,
+\(oq\e(lq\(cq and \(oq\e(rq\(cq, respectively.
.
.
.TP
.B \e*(Tm
-The \[oq]trademark\[cq] sign.
+expands to the character escape for the \(lqtrade mark sign\(rq glyph,
+\(oq\e(tm\(cq,
+if available,
+and \(lq(TM)\(rq otherwise.
.
.
.\" ====================================================================
@@ -1117,7 +1549,7 @@ of a man page look like this:
.
.PP
.RS
-.BI \(aq\e"\ word
+.BI "\(aq\e\(dq " word
.RE
.
.
@@ -1128,13 +1560,13 @@ and that a single space character follows the double
quote.
The
.I word
consists of one letter for each needed preprocessor:
-\[oq]e\[cq] for
-.BR @address@hidden ,
-\[oq]r\[cq] for
-.BR @address@hidden ,
+\(oqe\(cq for
+.IR @address@hidden ,
+\(oqr\(cq for
+.IR @address@hidden ,
and
-\[oq]t\[cq] for
-.BR @address@hidden .
+\(oqt\(cq for
+.IR @address@hidden .
.
Modern implementations of the
.I man
@@ -1162,49 +1594,51 @@ output devices are extremely limited in presentation of
mathematical
equations.
.
.
+.\" TODO BEGIN: move subsection to tutorial/style guide when we have it
.\" ====================================================================
.SS Portability
.\" ====================================================================
.
-Since the
-.B man
-macros consist of groups of
-.I groff
-requests, one can, in principle, supplement the functionality of the
-.B man
-macros with individual
-.I groff
-requests where necessary.
+The two major syntactical categories of
+.I roff
+languages are requests and escapes.
.
-See the
+Since the
+.I man
+macros are implemented in terms of
.I groff
-info pages for a complete reference of all requests.
+requests and escapes,
+one can,
+in principle,
+supplement the functionality of
+.I man
+with these lower-level elements where necessary.
.
.
.PP
-Note, however, that using raw troff requests is likely to make your
-page render poorly on the class of viewers that transform it to HTML.
+Note,
+however,
+that using raw
+.I groff
+requests is likely to make your page render poorly on the class of
+viewers that transform it to HTML.
.
-Troff requests make implicit assumptions about things like character
-and page sizes that may break in an HTML environment; also, many of
-these viewers don't interpret the full troff vocabulary, a problem
-that can lead to portions of your text being silently dropped.
+Some requests make implicit assumptions about things like character
+and page sizes that may not hold in an HTML environment;
+also,
+many of these viewers don't interpret the full
+.I groff
+vocabulary,
+a problem that can lead to portions of your text being silently dropped.
.
.
.PP
-For portability to modern viewers, it is best to write your page
-entirely in the requests described on this page.
+For portability to modern viewers,
+it is best to write your page entirely with the macros described in this
+page
+(except for the ones identified as deprecated,
+which should be avoided).
.
-Further, it is best to completely avoid those we have described as
-\[oq]presentation-level\[cq]
-.RB ( .HP ,
-.BR .PD ,
-and
-.BR .DT )
-in \(lqDeprecated features\(rq, below.
-.
-.
-.PP
The macros we have described as extensions
.RB ( .EX / .EE ,
.BR .SY / .OP / .YS ,
@@ -1214,43 +1648,63 @@ and
should be used with caution, as they may not yet be built in to
some viewer that is important to your audience.
.
-If in doubt, copy the implementation onto your page.
+If in doubt, copy the implementation into your page\(emafter the
+.B .TH
+call and the \(lqName\(rq section,
+to accommodate timid
+.I mandb
+implementations.
.
.
.PP
-In a way similar to using
-.I groff
-requests, it is possible to use the facilities documented in the
-ESCAPE SEQUENCES section of the
-.BR groff (7)
-manual page and in the
-.BR groff_char (7)
-manual page.
-.
-Regarding portability, similar caveats apply as with respect to
-.I groff
-requests.
+Similar caveats apply to escapes.
.
Some escape sequences are however required for correct typesetting
-even in manual pages and usually do not cause portability problems:
+even in man pages and usually do not cause portability problems:
+.
+.
+.TP
+.B \e\(dq
+Comment.
+.
+Everything after the double-quote to the end of the input line is
+ignored.
+.
+Whole-line comments are frequently placed immediately after the empty
+request \(oq.\(cq.
+.
.
.TP
-.RB \(dq \e\ \(dq
-Unpaddable non-breaking space character.
+.BI \e newline
+Join the next input line to the current one.
.
-(The double-quotes are to make the presence of the space character
-clear in this document, and are not necessary in the input file.)
+Except for the update of the input line counter (used for diagnostic
+messages and related purposes),
+a series of lines ending in backslash-newline is transparent to
+.IR groff .
+.
+Use this escape to break excessively input long lines for document
+maintenance.
+.
+.
+.TP
+.B \e\(ti
+Adjustable, non-breaking space character.
+.
+Use this escape to prevent a break inside a short phrase or between a
+numerical quantity and its corresponding unit(s).
.
-Useful for preventing breaking between a numerical quantity and its
-corresponding unit(s), for instance:
.
.RS
.IP
.EX
-There are 2.54\e\ cm in an inch, and 1,024\e\ bytes in 1\e\ kiB.
+Before starting the motor, set the output speed to\e\(ti1.
+There are 1,024\e\(tibytes in 1\e\(tikiB.
+CSTR\e\(ti#8 documents the B language.
.EE
.RE
.
+.
.TP
.B \e&
Zero-width space.
@@ -1262,14 +1716,16 @@ beginning of a
.I roff
request.
.
+.
.TP
.B \e(aq
ASCII apostrophe.
.
-Useful for syntax elements of programming languages because some
+Use for syntax elements of programming languages because some
output devices might replace unescaped apostrophes with right single
quotation marks.
.
+.
.TP
.B \e(oq
Opening single quotation mark.
@@ -1278,17 +1734,20 @@ Opening single quotation mark.
.B \e(cq
Closing single quotation mark.
.
+.
.IP
Use these for paired directional single quotes, \(oqlike this\(cq.
.
+.
.TP
.B \e(dq
ASCII double-quote.
.
-Sometimes needed on macro lines to prevent the interpretation of the
+Sometimes needed after macro calls to prevent the interpretation of the
ASCII quotation mark character \(oq\(dq\(cq as the beginning or end
of a macro argument.
.
+.
.TP
.B \e(lq
Left double quotation mark.
@@ -1297,58 +1756,67 @@ Left double quotation mark.
.B \e(rq
Right double quotation mark.
.
+.
.IP
Use these for paired directional double quotes, \(lqlike this\(rq.
.
+.
.TP
.B \e(em
Em-dash.
.
-Used as a punctuation mark for an interruption in a sentence\(emlike
-in this one.
+Use for an interruption in a sentence\(emsuch as this one.
+.
.
.TP
.B \e(en
En-dash.
.
-Used to separate the two ends of a range, in particular between
-numbers, for example: the digits 1\(en9.
+Use to separate the two ends of a range,
+in particular between numbers,
+for example: the digits 1\(en9.
+.
.
.TP
.B \e(ga
ASCII grave accent.
.
-Useful for syntax elements of programming languages, for example
-shell command substitutions, because some output devices might
-replace unescaped grave accents with left single quotation marks.
+Use for syntax elements of programming languages,
+for example shell command substitutions,
+because some output devices might replace unescaped grave accents with
+left single quotation marks.
+.
.
.TP
.B \e(ha
ASCII circumflex accent.
.
-Useful for syntax elements of programming languages because some
-output devices might replace unescaped circumflex accents with
-non-ASCII glyphs like the Unicode U+02C6 modifier letter circumflex.
+Use for syntax elements of programming languages because some output
+devices might replace unescaped circumflex accents with non-ASCII glyphs
+like the Unicode U+02C6 modifier letter circumflex.
+.
.
.TP
.B \e(ti
ASCII tilde.
.
-Useful for syntax elements of programming languages because some
-output devices might replace unescaped tildes with non-ASCII glyphs
-like the Unicode U+02DC small tilde.
+Use for syntax elements of programming languages because some output
+devices might replace unescaped tildes with non-ASCII glyphs like the
+Unicode U+02DC small tilde.
+.
.
.TP
-.B \e-
+.B \e\-
Minus sign.
.
Also use this to display syntax elements that require the ASCII
-hyphen-minus character, for example command-line options and C
-language operators.
+hyphen-minus character,
+for example command-line options and C language operators.
.
The unescaped \(oq\-\(cq input character is not appropriate for
these cases because it may render as a hyphen on some output devices.
.
+.
.TP
.B \ec
.
@@ -1357,30 +1825,33 @@ space is inserted between the last glyph on it and the
first glyph
resulting from the next input line.
.
This is occasionally useful when three different fonts are needed
-in a single word, for example:
+in a single word.
+.
.
.RS
.IP
+.\" contrib/pdfmark/pdfroff.1.man
.EX
-\&.BR "dd if" =\ec
-\&.I file
+Normally, the final output file should be named
+\&.IB file .pdf\ec
+\e&.
.EE
.RE
.
+.
.IP
Note that when using this trick with the
.B .BI
or
.B .RI
macros, you will need to manually add an italic correction escape
-.B \e/
-before the
-.B \ec
-due to way macros expand their arguments.
+\(oq\e/\(cq before the \(oq\ec\(cq due to way macros expand their
+arguments.
.
.
.RS
.IP
+.\" from contrib/mom/groff_mom.7.man
.EX
Files processed with
\&.B groff \e\-mom
@@ -1392,16 +1863,15 @@ Files processed with
.
.
.IP
-Alternatively, and perhaps with better portability, the
-.B \ef
-font escape sequence can be used; see below.
+Alternatively,
+and perhaps with better portability,
+the \(oq\ef\(cq font escape sequence can be used;
+see below.
.
-Attempting to use
-.B \ec
-to include the output from more than one macro line into the next-line
-argument of a
+Using \(oq\ec\(cq to include the output from more than one input line
+into the next-line argument of a
.B .TP
-macro will misrender with
+macro will render incorrectly with
.I groff
1.22.3,
.I mandoc
@@ -1409,63 +1879,74 @@ macro will misrender with
older versions of these programs,
and perhaps with some other formatters.
.
+.
.TP
.B \ee
-Widely used in manual pages to represent a backslash output glyph.
+Widely used in man pages to represent a backslash output glyph.
.
It works reliably as long as the
.B .ec
-request is not used, which should never happen in manual pages, and
-it is slightly more portable than the more exact
-.B \e(rs
-(\[lq]reverse solidus\[rq])
-escape sequence.
+request is not used,
+which should never happen in man pages,
+and it is slightly more portable than the more exact \(oq\e(rs\(cq
+(\(lqreverse solidus\(rq) escape sequence.
+.
.
.TP
.BR \efB ,\ \efI ,\ \efR ,\ \efP
Switch to bold, italic, roman, or back to the previous font,
respectively.
.
-This is needed when three different fonts are required on a single
-input line, for example:
+Either these or \(oq\ec\(cq is needed when three different fonts are
+required in a single whitespace-delimited word.
+.
.
.RS
.IP
+.\" second example from contrib/pdfmark/pdfroff.1.man
.EX
-\&.TP
-\efBif\efP=\efIfile\efP
+\&.RB [ \e\-\e\-reference\e\-dictionary=\efI\e,name\e/\efP ]
+.IP
+\&.RB [ \e\-\e\-reference\e\-dictionary=\ec
+\&.IR name ]
.EE
.RE
.
+.
.IP
-It can also be used if three different fonts are needed in a
-single word.
-It may be more portable than
-.BR \ec .
+Font escapes may be more portable than \(oq\ec\(cq.
.
-It is up to you to account for italic corrections with
-.B \e/
-and
-.BR \e, ,
-which are themselves
+As shown above,
+it is up to you to account for italic corrections with \(oq\e/\(cq and
+\(oq\e,\(cq, which are themselves
.I groff
extensions,
if desired and if supported by your implementation.
.
.
.IP
-As long as at most two fonts are needed in any one whitespace-delimited
+Note that
+\(oq\efP\(cq reliably returns to the style in use immediately preceding
+the previous \(oq\ef\(cq escape only if no
+sectioning,
+paragraph,
+or font face macro calls have intervened.
+.
+.
+.IP
+As long as only two fonts are needed in any single whitespace-delimited
word,
-using font alternation macros like
-.B .BR
-usually results in more readable source code.
+font alternation macros like
+.B .BI
+usually result in more readable source code than \(oq\ef\(cq escapes do.
.
.
.PP
For maximum portability, escape sequences and special characters
-not listed above are better avoided in manual pages.
+not listed above are better avoided in man pages.
.
.
+.\" TODO END: move subsection to tutorial/style guide when we have it
.\" ====================================================================
.SS "Deprecated features"
.\" ====================================================================
@@ -1474,19 +1955,53 @@ Use of the following is discouraged.
.
.
.TP
-.BI .AT " \fR[\fPsystem \fR[\fPrelease\fR]]\fP"
-Alter the footer for use with AT&T man pages.
+.BR .AT " ["\c
+.IR system " [" release ]]
+Alter the footer for use with AT&T man pages,
+overriding any definition of the
+.I footer-outside
+argument to
+.BR .TH .
.
This macro exists only for compatibility; don't use it.
.
-See the
-.I groff
-info manual for more.
+.
+.IP
+The first argument
+.I system
+can be:
+.
+.
+.RS \" Invisibly move left margin to current .IP indent.
+.RS \" Now indent further, visibly.
+.TP
+3
+7th edition
+.I (default)
+.
+.
+.TP
+4
+System III
+.
+.
+.TP
+5
+System V
+.RE \" Move left margin back to .IP indentation.
+.RE \" Move left margin back to standard position.
+.
+.
+.IP
+The optional second argument
+.I release
+specifies the release number,
+such as in \(lqSystem V Release 3\(rq.
.
.
.TP
.B .BT
-Print the footer string.
+Set the page footer.
.
Redefine this macro to get control of the footer.
.
@@ -1496,7 +2011,7 @@ Redefine this macro to get control of the footer.
Set tabs every 0.5\~inches.
.
Since this macro is always called during a
-.B TH
+.B .TH
macro, it makes sense to call it only if the tab positions have been
changed.
.
@@ -1513,44 +2028,21 @@ to express are likely to be lost.
.
If you feel tempted to use it, you should probably be composing a
table using
-.BR @address@hidden (@MAN1EXT@)
+.IR @address@hidden (@MAN1EXT@)
markup instead.
.
.
.TP
-.BI .HP " \fR[\fPnnn\fR]\fP"
-Set up a paragraph with hanging left indentation.
-.
-The indentation is set to
-.I nnn
-if that argument is supplied (the default unit is \[oq]n\[cq] if
-omitted), otherwise it is set to the previous indentation value
-specified with
-.BR .TP ,
-.BR .IP ,
-or
-.B .HP
-(or to the default value if none of them have been used yet).
-.
-Font size and face are reset to its default values.
+.BR .HP " ["\c
+.IR indent ]
+Set up a paragraph with a hanging left indentation.
.
-The following paragraph illustrates the effect of this macro with
-hanging indentation set to\~4 (enclosed by
-.B .RS
-and
-.B .RE
-to set the left margin temporarily to the current indentation):
-.
-.
-.RS
-.HP 4
-This is a paragraph following an invocation of the
-.B HP
-macro.
-.
-As you can see, it produces a paragraph where all lines but the first
-are indented.
-.RE
+The
+.I indent
+argument,
+if present,
+is handled as with
+.BR .TP .
.
.
.IP
@@ -1566,25 +2058,18 @@ indentation may be lost.
.
.
.TP
-.BI .PD " \fR[\fPnnn\fR]\fP"
-Adjust the empty space before a new paragraph or section.
+.BR .PD " ["\c
+.IR vertical-space ]
+Define the vertical space between paragraphs or (sub)sections.
.
-The optional argument gives the amount of space (default unit is
-\[oq]v\[cq]); without parameter, the value is reset to its default
-value (1\~line in nroff mode, 0.4v\~otherwise).
+The optional argument
+.I vertical-space
+specifies the amount of space;
+the default scaling is \(oqv\(cq).
.
-This affects the macros
-.BR SH ,
-.BR SS ,
-.BR TP ,
-.B LP
-(resp.\&
-.B PP
-and
-.BR P ),
-.BR IP ,
-and
-.BR HP .
+Without an argument,
+the spacing is reset to its default value;
+see \(lqHorizontal and vertical spacing\(rq above.
.
.
.IP
@@ -1600,61 +2085,139 @@ to express are likely to be lost.
.
.TP
.B .PT
-Print the header string.
+Set the page header.
.
Redefine this macro to get control of the header.
.
.
.TP
-.BI .UC " \fR[\fPversion\fR]\fP"
-Alter the footer for use with BSD man pages.
+.BR .UC " ["\c
+.IR version ]
+Alter the footer for use with BSD man pages,
+overriding any definition of the
+.I footer-outside
+argument to
+.BR .TH .
.
This macro exists only for compatibility; don't use it.
.
-See the
-.I groff
-info manual for more.
+.
+.IP
+The argument
+.I version
+can be:
+.
+.
+.RS \" Invisibly move left margin to current .IP indent.
+.RS \" Now indent further, visibly.
+.TP
+3
+3rd Berkeley Distribution
+.I (default)
+.
+.
+.TP
+4
+4th Berkeley Distribution
.
.
+.TP
+5
+4.2 Berkeley Distribution
+.
+.
+.TP
+6
+4.3 Berkeley Distribution
+.
+.
+.TP
+7
+4.4 Berkeley Distribution
+.RE \" Move left margin back to .IP indentation.
+.RE \" Move left margin back to standard position.
+.
+.
+.\" ====================================================================
+.SS "History"
+.\" ====================================================================
+.
+According to its own
+.IR man (7)
+page,
+Version 7 Unix (1979) supported all of the macros described in this page
+not listed as GNU extensions,
+except
+.BR .P ,
+.BR .SB ,
+.BR .SS ,
+and the deprecated
+.BR .AT ,
+.BR .BT ,
+.BR .PT ,
+and
+.BR .UC .
+.
+The only string registers defined were
+.B R
+and
+.BR S ;
+no number registers were documented.
.
.
.\" ====================================================================
.SH OPTIONS
.\" ====================================================================
.
-The
-.B man
-macros understand the following command-line options (which define
-various registers).
+The following
+.I groff
+options set number registers recognized and used by the
+.I man
+macro package.
.
.
.TP
.B \-rcR=1
-This option (the default if in nroff mode) creates a single, very
-long page instead of multiple pages.
+Continuous rendering.
+.
+Create a single,
+very long page instead of multiple pages.
+.
+This is the default in
+.I nroff
+mode.
.
-Say
+Use
.B \-rcR=0
to disable it.
.
.
.TP
.B \-rC1
-If more than one manual page is given on the command line, number the
+Number pages continuously.
+.
+If more than one man page is given on the command line, number the
pages continuously, rather than starting each at\~1.
.
.
.TP
.B \-rD1
-Double-sided printing.
+Enable double-sided printing.
.
-Footers for even and odd pages are formatted differently.
+Footers for even and odd pages are formatted differently;
+see the description of
+.B .TH
+in \(lqDocument structure macros\(rq,
+above.
.
.
.TP
-.BI \-rFT= dist
-Set distance of the footer relative to the bottom of the page if
-negative or relative to the top if positive.
+.BI \-rFT= footer-distance
+Set distance of the footer,
+relative to the bottom of the page if negative or relative to the top if
+positive,
+to
+.IR footer-distance .
.
The default is \-0.5i.
.
@@ -1663,14 +2226,18 @@ The default is \-0.5i.
.BI \-rHY= flags
Set hyphenation flags.
.
-Possible values are 1\~to not hyphenate the first and last character
-of a word, 2\~to not hyphenate the last word on a page, 4\~to not
-hyphenate the last two characters of a word, 8\~to not hyphenate the
-first two characters of a word, 16\~to enable hyphenation before the
-last character of a word, and 32 to enable hyphenation after the
-first character of a word.
+Possible values of
+.I flags
+are 1\~to not hyphenate the first and last character of a word,
+2\~to not hyphenate the last word on a page,
+4\~to not hyphenate the last two characters of a word,
+8\~to not hyphenate the first two characters of a word,
+16\~to enable hyphenation before the last character of a word,
+and
+32\~to enable hyphenation after the first character of a word.
.
-These values are additive; the default is\~6.
+These values are additive;
+the default is\~6.
.
Values 4 and\~16 can't be used together since they contradict each
other;
@@ -1678,19 +2245,18 @@ the same holds for values 8 and\~32.
.
.
.TP
-.BI \-rIN= width
-Set body text indentation to
-.IR width .
+.BI \-rIN= indent
+Set the body text indentation (for normal paragraphs) to
+.IR indent .
.
-The default is 7n for
-.IR nroff ,
-7.2n for
-.IR troff .
+See \(lqHorizontal and vertical spacing\(rq above for the default
+indentation value.
.
For
.IR nroff ,
-this value should always be an integer multiple of unit \[oq]n\[cq] to
-get consistent indentation.
+.I indent
+should always be an integer multiple of unit \(oqn\(cq to get consistent
+indentation.
.
.
.TP
@@ -1698,10 +2264,12 @@ get consistent indentation.
Set line length.
.
If this option is not given, the line length is set to respect any
-value set by a prior \[oq].ll\[cq] request (which
+value set by a prior \(lq.ll\(rq request (which
.I must
-be in effect when the \[oq].TH\[cq] macro is invoked),
-if this differs from the built\-in default for the formatter;
+be in effect when the
+.B .TH
+macro is invoked),
+if this differs from the built-in default for the formatter;
otherwise it defaults to 78n in
.I nroff
mode and 6.5i in
@@ -1710,25 +2278,31 @@ mode.
.
.
.IP
-Note that the use of a \[oq].ll\[cq] request to initialize the line
+Note that the use of a \(lq.ll\(rq request to initialize the line
length is supported for backward compatibility with some versions of
the
-.B man
+.I man
program;
-direct initialization of the \[oq]LL\[cq] register should
+direct initialization of the
+.B LL
+register should
.I always
be preferred to the use of such a request.
.
-In particular, note that a \[oq].ll\ 65n\[cq] request does
+In particular, note that a \(lq.ll\~65n\(rq request does
.I not
preserve the normal
.I nroff
default line length,
(the
-.B man
-default initialization to 78n prevails), whereas, the
-\[oq]\-rLL=65n\[cq] option, or an equivalent \[oq].nr\ LL\ 65n\[cq]
-request preceding the use of the \[oq]TH\[cq] macro,
+.I man
+default initialization to 78n prevails),
+whereas the
+.B \-rLL=65n
+option,
+or an equivalent \(lq.nr\~LL\~65n\(rq request preceding the use of the
+.B .TH
+macro,
.I does
set a line length of 65n.
.
@@ -1742,40 +2316,46 @@ length.
.
.
.TP
-.BI \-rP nnn
-Enumeration of pages start with
-.I nnn
-rather than with\~1.
+.BI \-rP n
+Start enumeration of pages at
+.I n
+rather than\~1.
.
.
.TP
-.BI \-rS xx
-Base document font size is
-.I xx
-points
-.RI ( xx
-can be 10, 11, or\~12) rather than 10\~points.
+.BI \-rS point-size
+Use
+.I point-size
+as the base document font size.
+.
+Acceptable values are 10, 11, or 12.
+.
+See subsection \(lqFont style macros\(rq above for the default.
.
.
.TP
-.BI \-rSN= width
-Set sub-subheading indentation to
-.IR width .
-The default is 3n.
+.BI \-rSN= subsection-indent
+Set subsection indentation to
+.IR subsection-indent .
+.
+See \(lqHorizontal and vertical spacing\(rq above for the default
+indentation value.
.
.
.TP
-.BI \-rX nnn
-After page\~\c
-.IR nnn ,
+.BI \-rX p
+After
+.RI page " p" ,
number pages as
-.IR nnn a,
-.IR nnn b,
-.IR nnn c,
-etc.
+.IR p a,
+.IR p b,
+.IR p c,
+and so forth.
.
-For example, the option \[oq]\-rX2\[cq] produces the following page
-numbers: 1, 2, 2a, 2b, 2c, etc.
+For example, the option
+.B \-rX2
+produces the following page
+numbers: 1, 2, 2a, 2b, 2c, and so on.
.
.
.\" ====================================================================
@@ -1897,7 +2477,10 @@ and the deprecated
.BR .HP .
.
If you need to start an indent relative to an indented paragraph,
-give
+call
+.B .RS
+repeatedly until an acceptable indentation is achieved,
+or give
.B .RS
an indentation argument that is at least as much as the paragraph's
indentation amount relative to an adjacent
@@ -1959,6 +2542,7 @@ have no effect.
.\" ====================================================================
.SH AUTHORS
.\" ====================================================================
+.
The GNU version of the
.I man
macro package was written by James Clark and contributors.
@@ -1979,21 +2563,52 @@ This document was originally written for the Debian
GNU/Linux system by
Susan G.\& Kleinmann
.ME .
.
-It was corrected and updated by Werner Lemberg.
+It was corrected and updated by Werner Lemberg and G.\& Branden
+Robinson.
.
The extension macros were documented by Eric S.\& Raymond;
-he also originated the portability advice.
+he also originated the portability section,
+to which Ingo Schwarze contributed most of the material on escape
+sequences.
.
.
.\" ====================================================================
.SH "SEE ALSO"
.\" ====================================================================
-.BR @address@hidden (@MAN1EXT@),
-.BR @address@hidden (@MAN1EXT@),
-.BR @address@hidden (@MAN1EXT@),
-.BR man (1),
-.BR man (7),
-.BR groff_mdoc (7)
+.
+.IR "Groff: The GNU Implementation of troff" ,
+by Trent A.\& Fisher and Werner Lemberg,
+is the main
+.I groff
+documentation.
+.
+You can browse it interactively with \(lqinfo groff\(rq.
+.
+.
+.PP
+.IR @address@hidden (@MAN1EXT@),
+.IR @address@hidden (@MAN1EXT@),
+and
+.IR @address@hidden (@MAN1EXT@)
+are preprocessors used with man pages.
+.
+.
+.PP
+.IR man (1)
+describes the man page formatter on your system.
+.
+.
+.PP
+.IR groff_mdoc (@MAN7EXT@)
+describes the
+.I groff
+version of the BSD-originated alternative macro package for man pages.
+.
+.
+.PP
+.IR groff (@MAN7EXT@),
+.IR groff_char (@MAN7EXT@),
+.IR man (7)
.
.
.\" Restore compatibility mode (for, e.g., Solaris 10/11).
@@ -2004,5 +2619,6 @@ he also originated the portability advice.
.\" ### Emacs settings:
.\" Local Variables:
.\" mode: nroff
+.\" fill-column: 72
.\" End:
-.\" vim: set filetype=groff:
+.\" vim: set filetype=groff textwidth=72:
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 01/01: groff_man(7): Expand and revise.,
G. Branden Robinson <=