[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[bug #58653] want the short mdoc(7) page that Linux man-pages used to sh
From: |
G. Branden Robinson |
Subject: |
[bug #58653] want the short mdoc(7) page that Linux man-pages used to ship |
Date: |
Thu, 30 Mar 2023 11:06:21 -0400 (EDT) |
Update of bug #58653 (project groff):
Status: None => Wont Fix
Assigned to: schwarze => gbranden
Open/Closed: Open => Closed
_______________________________________________________
Follow-up Comment #10:
It looks like nobody has the desire to resolve this as the submitter
requested.
I would point out, however, that since last updating this ticket over a year
ago, I have significantly revised the opening sections of the _groff_mdoc_(7)
man page (and some other spots within it).
I shelved this work before I had completely revised the page because we got
our maintainer back and it was long past time to get into release candidate
phase. (But that process has been a bit fitful too, so I worked on _groff_'s
_mm_ implementation some.)
Long story short, here's how the beginning of _groff_mdoc_(7) reads now, and
how I expect it to look in groff 1.23.0.
There's some UTF-8 in here.
groff_mdoc(7) Miscellaneous Information Manual groff_mdoc(7)
Name
groff_mdoc — compose BSD‐style manual (man) pages with GNU roff
Synopsis
groff -mdoc file ...
Description
The GNU implementation of the mdoc macro package is part of the
groff(1) document formatting system. mdoc is a structurally‐ and
semantically‐oriented package for writing Unix manual pages with
troff(1). Its predecessor, the man(7) package, primarily addressed
page layout and presentational concerns, leaving the selection of
fonts and other typesetting details to the individual author. This
discretion has led to divergent styling practices among authors
using it.
mdoc organizes its macros into domains. The page structure domain
lays out the page and comprises titles, section headings, displays,
and lists. The general text domain supplies macros to quote or
style text, or to interpolate common noun phrases. The manual
domain offers semantic macros corresponding to the terminology used
by practitioners in discussion of Unix commands, routines, and
files. Manual domain macros distinguish command‐line arguments and
options, function names, function parameters, pathnames, variables,
cross references to other manual pages, and so on. These terms are
meaningful both to the author and the readers of a manual page. It
is hoped that the resulting increased consistency of the man page
corpus will enable easier translation to future documentation tools.
Throughout Unix documentation, a manual entry is referred simply to
as a “man page”, regardless of its length, without gendered
implication, and irrespective of the macro package selected for its
composition.
Getting started
The mdoc package attempts to simplify man page authorship and
maintenance without requiring mastery of the roff language. This
document presents only essential facts about roff. For further
background, including a discussion of basic typographical concepts
like “breaking”, “filling”, and “adjustment”, see roff(7).
Specialized units of measurement also arise, namely ens, vees,
inches, and points, abbreviated “n”, “v”, “i”, and “p”,
respectively; see section “Measurements” of groff(7).
For brief examples, we employ an arrow notation illustrating a
transformation of input on the left to rendered output on the right.
Consider the .Dq macro, which double‐quotes its arguments.
.Dq man page → “man page”
Usage
An mdoc macro is called by placing the roff control character, ‘.’
(dot) at the beginning of a line followed by its name. In this
document, we often discuss a macro name with this leading dot to
identify it clearly, but the dot is not part of its name. Space or
tab characters can separate the dot from the macro name. Arguments
may follow, separated from the macro name and each other by spaces,
but not tabs. The dot at the beginning of the line prepares the
formatter to expect a macro name. A dot followed immediately by a
newline is ignored; this is called the empty request. To begin an
input line with a dot (or a neutral apostrophe ‘'’) in some context
other than a macro call, precede it with the ‘\&’ escape sequence;
this is a dummy character, not formatted for output. The backslash
is the roff escape character; it can appear anywhere and it always
followed by at least one more character. If followed by a newline,
the backslash escapes the input line break; you can thus keep input
lines to a reasonable length without affecting their interpretation.
Macros in GNU troff accept an unlimited number of arguments, in
contrast to other troffs that often can’t handle more than nine. In
limited cases, arguments may be continued or extended on the next
input line without resort to the ‘\newline’ escape sequence; see
subsection “Extended arguments” below. Neutral double quotes " can
be used to group multiple words into an argument; see subsection
“Passing space characters in an argument” below.
Most of mdoc’s general text and manual domain macros parse their
argument lists for callable macro names. This means that an
argument in the list matching a general text or manual domain macro
name (and defined to be callable) will be called with the remaining
arguments when it is encountered. In such cases, the argument,
although the name of a macro, is not preceded by a dot. Macro calls
can thus be nested. This approach to macro argument processing is a
unique characteristic of the mdoc package, not a general feature of
roff syntax.
For example, the option macro, .Op, may call the flag and argument
macros, .Fl and .Ar, to specify an optional flag with an argument.
.Op Fl s Ar bytes → [-s bytes]
To prevent a word from being interpreted as a macro name, precede it
with the escape sequence ‘\&’.
.Op \&Fl s \&Ar bytes → [Fl s Ar bytes]
In this document, macros whose argument lists are parsed for
callable arguments are referred to as parsed, and those that may be
called from an argument list are referred to as callable. This
usage is a technical faux pas, since all mdoc macros are in fact
interpreted (unless prevented with ‘\&’), but as it is cumbersome to
constantly refer to macros as “being able to call other macros”, we
employ the term “parsed” instead. Except where explicitly stated,
all mdoc macros are parsed and callable.
In the following, we call an mdoc macro that starts a line (with a
leading dot) a command if a distinction from those appearing as
arguments of other macros is necessary.
Passing space characters in an argument
Sometimes it is desirable to give a macro an argument containing one
or more space characters, for instance to specify a particular
arrangement of arguments demanded by the macro. Additionally,
quoting multi‐word arguments that are to be treated the same makes
mdoc work faster; macros that parse arguments do so once (at most)
for each. For example, the function command .Fn expects its first
argument to be the name of a function and any remaining arguments to
be function parameters. Because C language standards mandate the
inclusion of types and identifiers in the parameter lists of
function definitions, each ‘Fn’ parameter after the first will be at
least two words in length, as in “int foo”.
There are a few ways to embed a space in a macro argument. One is
to use the unadjustable space escape sequence \space. The formatter
treats this escape sequence as if it were any other printable
character, and will not break a line there as it would a word space
when the output line is full. This method is useful for macro
arguments that are not expected to straddle an output line boundary,
but has a drawback: this space does not adjust as others do when the
output line is formatted. An alternative is to use the unbreakable
space escape sequence, ‘\~’, which cannot break but does adjust.
This groff extension is widely but not perfectly portable. Another
method is to enclose the string in double quotes.
.Fn fetch char\ *str → fetch(char *str)
.Fn fetch char\~*str → fetch(char *str)
.Fn fetch "char *str" → fetch(char *str)
If the ‘\’ before the space in the first example or the double
quotes in the third example were omitted, ‘.Fn’ would see three
arguments, and the result would contain an undesired comma.
.Fn fetch char *str → fetch(char, *str)
Trailing space characters
It is wise to remove trailing spaces from the ends of input lines.
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.
Formatting the backslash glyph
When you need the roff escape character ‘\’ to appear in the output,
use ‘\e’ or ‘\(rs’ instead. Technically, ‘\e’ formats the
current
escape character; it works reliably as long as no roff request is
used to change it, which should never happen in man pages. ‘\(rs’
is a groff special character escape sequence that explicitly formats
the “reverse solidus” (backslash) glyph.
Other possible pitfalls
groff mdoc warns when an empty input line is found outside of a
display, a topic presented in subsection “Examples and displays”
below. Use empty requests to space the source document for
maintenance.
Leading spaces cause a break and are formatted. Avoid this
behaviour if possible. Similarly, do not put more than one space
between words in an ordinary text line; they are not “normalized” to
a single space as other text formatters might do.
Don’t try to use the neutral double quote character ‘"’ to
represent
itself in an argument. Use the special character escape sequence
‘\(dq’ to format it. Further, this glyph should not be used for
conventional quotation; mdoc offers several quotation macros. See
subsection “Enclosure and quoting macros” below.
The formatter attempts to detect the ends of sentences and by
default puts the equivalent of two spaces between sentences on the
same output line; see roff(7). To defeat this detection in a parsed
list of macro arguments, put ‘\&’ before the punctuation mark.
Thus,
The
.Ql .
character.
.Pp
The
.Ql \&.
character.
.Pp
.No test .
test
.Pp
.No test.
test
gives
The ‘’. character
The ‘.’ character.
test. test
test. test
as output. As can be seen in the first and third output lines, mdoc
handles punctuation characters specially in macro arguments. This
will be explained in section “General syntax” below.
A comment in the source file of a man page can begin with ‘.\"’ at
the start of an input line, ‘\"’ after other input, or ‘\#’
anywhere
(the last is a groff extension); the remainder of any such line is
ignored.
A man page template
Use mdoc to construct a man page from the following template.
.\" The following three macro calls are required.
.Dd date
.Dt topic [section‐identifier [section‐keyword‐or‐title]]
.Os [package‐or‐operating system [version‐or‐release]]
.Sh Name
.Nm topic
.Nd summary‐description
.\" The next heading is used in sections 2 and 3.
.\" .Sh Library
.\" The next heading is used in sections 1‐4, 6, 8, and 9.
.Sh Synopsis
.Sh Description
.\" Uncomment and populate the following sections as needed.
.\" .Sh "Implementation notes"
.\" The next heading is used in sections 2, 3, and 9.
.\" .Sh "Return values"
.\" The next heading is used in sections 1, 3, 6, and 8.
.\" .Sh Environment
.\" .Sh Files
.\" The next heading is used in sections 1, 6, and 8.
.\" .Sh "Exit status"
.\" .Sh Examples
.\" The next heading is used in sections 1, 4, 6, 8, and 9.
.\" .Sh Diagnostics
.\" .Sh Compatibility
.\" The next heading is used in sections 2, 3, 4, and 9.
.\" .Sh Errors
.\" .Sh "See also"
.\" .Sh Standards
.\" .Sh History
.\" .Sh Authors
.\" .Sh Caveats
.\" .Sh Bugs
The first items in the template are the commands .Dd, .Dt, and .Os.
They identify the page and are discussed below in section “Title
macros”.
The remaining items in the template are section headings (.Sh); of
which “Name” and “Description” are mandatory. These headings are
discussed in section “Page structure domain”, which follows section
“Manual domain”. Familiarize yourself with manual domain macros
first; we use them to illustrate the use of page structure domain
macros.
Conventions
In the descriptions of macros below, square brackets surround
optional arguments. An ellipsis (‘...’) represents repetition of
the preceding argument zero or more times. Alternative values of a
parameter are separated with ‘|’. If a mandatory parameter can take
one of several alternative values, use braces to enclose the set,
with spaces and ‘|’ separating the items.
ztar {c | x} [-w [-y | -z]] [-f archive] member ...
An alternative to using braces is to separately synopsize distinct
operation modes, particularly if the list of valid optional
arguments is dependent on the user’s choice of a mandatory
parameter.
ztar c [-w [-y | -z]] [-f archive] member ...
ztar x [-w [-y | -z]] [-f archive] member ...
Most macros affect subsequent arguments until another macro or a
newline is encountered. For example, ‘.Li ls Bq Ar file’ doesn’t
produce ‘ls [file]’, but ‘ls [file]’. Consequently, a warning
message is emitted for many commands if the first argument is 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 literal.
.Li "ls [file]" → ls [file] # list any files named e, f, i,
or l
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 mdoc package. Explicit -width and -offset
arguments to the .Bl and .Bd macros are preferable.
Title macros
We present the mandatory title macros first due to their importance
even though they formally belong to the page structure domain
macros. They designate the topic, date of last revision, and the
operating system or software project associated with the page. Call
each once at the beginning of the document. They populate the page
headers and footers, which are in roff parlance termed “titles”.
.Dd date
This first macro of any mdoc manual records the last
modification date of the document source. Arguments are
concatenated and separated with space characters.
Historically, date was written in U.S. traditional format,
“Month day , year” where Month is the full month name in
English, day an integer without a leading zero, and year the
four‐digit year. This localism is not enforced, however.
You may prefer ISO 8601 format, YYYY‐MM‐DD. A date of the
form ‘$Mdocdate: Month day year $’ is also recognized. It
is used in OpenBSD manuals to automatically insert the
current date when committing.
This macro is neither callable nor parsed.
.Dt topic [section‐identifier [section‐keyword‐or‐title]]
topic is the subject of the man page. A section‐identifier
that begins with an integer in the range 1–9 or is one of
the words ‘unass’, ‘draft’, or ‘paper’ selects a
predefined
section title. This use of “section” has nothing to do with
the section headings otherwise discussed in this page; it
arises from the organizational scheme of printed and bound
Unix manuals.
In this implementation, the following titles are defined for
integral section numbers.
1 General Commands Manual
2 System Calls Manual
3 Library Functions Manual
4 Kernel Interfaces Manual
5 File Formats Manual
6 Games Manual
7 Miscellaneous Information Manual
8 System Manager’s Manual
9 Kernel Developer’s Manual
A section title may be arbitrary or one of the following
abbreviations.
USD User’s Supplementary Documents
PS1 Programmer’s Supplementary Documents
AMD Ancestral Manual Documents
SMM System Manager’s Manual
URM User’s Reference Manual
PRM Programmer’s Manual
KM Kernel Manual
IND Manual Master Index
LOCAL Local Manual
CON Contributed Software Manual
For compatibility, ‘MMI’ can be used for ‘IND’, and
‘LOC’
for ‘LOCAL’. Values from the previous table will specify a
new section title. If section‐keyword‐or‐title designates
a
computer architecture recognized by groff mdoc, its value is
prepended to the default section title as specified by the
second parameter. By default, the following architecture
keywords are defined.
acorn26, acorn32, algor, alpha, amd64, amiga, amigappc,
arc, arm, arm26, arm32, armish, atari, aviion, beagle,
bebox, cats, cesfic, cobalt, dreamcast, emips, evbarm,
evbmips, evbppc, evbsh3, ews4800mips, hp300, hp700,
hpcarm, hpcmips, hpcsh, hppa, hppa64, i386, ia64,
ibmnws, iyonix, landisk, loongson, luna68k, luna88k,
m68k, mac68k, macppc, mips, mips64, mipsco, mmeye,
mvme68k, mvme88k, mvmeppc, netwinder, news68k, newsmips,
next68k, ofppc, palm, pc532, playstation2, pmax, pmppc,
powerpc, prep, rs6000, sandpoint, sbmips, sgi, sgimips,
sh3, shark, socppc, solbourne, sparc, sparc64, sun2,
sun3, tahoe, vax, x68k, x86_64, xen, zaurus
If a section title is not determined after the above matches
have been attempted, section‐keyword‐or‐title is used.
The effects of varying ‘.Dt’ arguments on the page header
content are shown below. Observe how ‘\&’ prevents the
numeral 2 from being used to look up a predefined section
title.
.Dt foo 2 → foo(2) System Calls Manual foo(2)
.Dt foo 2 m68k → foo(2) m68k System Calls Manual foo(2)
.Dt foo 2 baz → foo(2) System Calls Manual foo(2)
.Dt foo \&2 baz → foo(2) baz foo(2)
.Dt foo "" baz → foo baz foo
.Dt foo M Z80 → foo(M) Z80 foo(M)
roff strings define section titles and architecture
identifiers. Site‐specific additions might be found in the
file mdoc.local; see section “Files” below.
This macro is neither callable nor parsed.
.Os [operating‐system‐or‐package‐name [version‐or‐release]]
This macro associates the document with a software
distribution. When composing a man page to be included in
the base installation of an operating system, do not provide
an argument; mdoc will supply it. In this implementation,
that default is “GNU”. It may be overridden in the site
configuration file, mdoc.local; see section “Files” below.
A portable software package maintaining its own man pages
can supply its name and version number or release identifier
as optional arguments. A version‐or‐release argument should
use the standard nomenclature for the software specified.
In the following table, recognized version‐or‐release
arguments for some predefined operating systems are listed.
As with .Dt, site additions might be defined in mdoc.local.
ATT 7th, 7, III, 3, V, V.2, V.3, V.4
BSD 3, 4, 4.1, 4.2, 4.3, 4.3t, 4.3T, 4.3r,
4.3R, 4.4
NetBSD 0.8, 0.8a, 0.9, 0.9a, 1.0, 1.0a, 1.1, 1.2,
1.2a, 1.2b, 1.2c, 1.2d, 1.2e, 1.3, 1.3a,
1.4, 1.4.1, 1.4.2, 1.4.3, 1.5, 1.5.1,
1.5.2, 1.5.3, 1.6, 1.6.1, 1.6.2, 1.6.3,
2.0, 2.0.1, 2.0.2, 2.0.3, 2.1, 3.0, 3.0.1,
3.0.2, 3.0.3, 3.1, 3.1.1, 4.0, 4.0.1, 5.0,
5.0.1, 5.0.2, 5.1, 5.1.2, 5.1.3, 5.1.4,
5.2, 5.2.1, 5.2.2, 6.0, 6.0.1, 6.0.2,
6.0.3, 6.0.4, 6.0.5, 6.0.6, 6.1, 6.1.1,
6.1.2, 6.1.3, 6.1.4, 6.1.5, 7.0, 7.0.1,
7.0.2, 7.1, 7.1.1, 7.1.2, 7.2, 8.0, 8.1
FreeBSD 1.0, 1.1, 1.1.5, 1.1.5.1, 2.0, 2.0.5, 2.1,
2.1.5, 2.1.6, 2.1.7, 2.2, 2.2.1, 2.2.2,
2.2.5, 2.2.6, 2.2.7, 2.2.8, 2.2.9, 3.0,
3.1, 3.2, 3.3, 3.4, 3.5, 4.0, 4.1, 4.1.1,
4.2, 4.3, 4.4, 4.5, 4.6, 4.6.2, 4.7, 4.8,
4.9, 4.10, 4.11, 5.0, 5.1, 5.2, 5.2.1, 5.3,
5.4, 5.5, 6.0, 6.1, 6.2, 6.3, 6.4, 7.0,
7.1, 7.2, 7.3, 7.4, 8.0, 8.1, 8.2, 8.3,
8.4, 9.0, 9.1, 9.2, 9.3, 10.0, 10.1, 10.2,
10.3, 10.4, 11.0, 11.1, 11.2, 11.3, 12.0,
12.1
OpenBSD 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7,
2.8, 2.9, 3.0, 3.1, 3.2, 3.3, 3.4, 3.5,
3.6, 3.7, 3.8, 3.9, 4.0, 4.1, 4.2, 4.3,
4.4, 4.5, 4.6, 4.7, 4.8, 4.9, 5.0, 5.1,
5.2, 5.3, 5.4, 5.5, 5.6, 5.7, 5.8, 5.9,
6.0, 6.1, 6.2, 6.3, 6.4, 6.5, 6.6
DragonFly 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7,
1.8, 1.8.1, 1.9, 1.10, 1.11, 1.12, 1.12.2,
1.13, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6,
2.7, 2.8, 2.9, 2.9.1, 2.10, 2.10.1, 2.11,
2.12, 2.13, 3.0, 3.0.1, 3.0.2, 3.1, 3.2,
3.2.1, 3.2.2, 3.3, 3.4, 3.4.1, 3.4.2,
3.4.3, 3.5, 3.6, 3.6.1, 3.6.2, 3.7, 3.8,
3.8.1, 3.8.2, 4.0, 4.0.1, 4.0.2, 4.0.3,
4.0.4, 4.0.5, 4.0.6, 4.1, 4.2, 4.2.1,
4.2.2, 4.2.3, 4.2.4, 4.3, 4.4, 4.4.1,
4.4.2, 4.4.3, 4.5, 4.6, 4.6.1, 4.6.2, 4.7,
4.8, 4.8.1, 4.9, 5.0, 5.0.1, 5.0.2, 5.1,
5.2, 5.2.1, 5.2.2, 5.3, 5.4, 5.4.1, 5.4.2,
5.4.3, 5.5, 5.6, 5.6.1, 5.6.2
Darwin 8.0.0, 8.1.0, 8.2.0, 8.3.0, 8.4.0, 8.5.0,
8.6.0, 8.7.0, 8.8.0, 8.9.0, 8.10.0, 8.11.0,
9.0.0, 9.1.0, 9.2.0, 9.3.0, 9.4.0, 9.5.0,
9.6.0, 9.7.0, 9.8.0, 10.0.0, 10.1.0,
10.2.0, 10.3.0, 10.4.0, 10.5.0, 10.6.0,
10.7.0, 10.8.0, 11.0.0, 11.1.0, 11.2.0,
11.3.0, 11.4.0, 11.5.0, 12.0.0, 12.1.0,
12.2.0, 13.0.0, 13.1.0, 13.2.0, 13.3.0,
13.4.0, 14.0.0, 14.1.0, 14.2.0, 14.3.0,
14.4.0, 14.5.0, 15.0.0, 15.1.0, 15.2.0,
15.3.0, 15.4.0, 15.5.0, 15.6.0, 16.0.0,
16.1.0, 16.2.0, 16.3.0, 16.4.0, 16.5.0,
16.6.0, 17.0.0, 17.1.0, 17.2.0, 17.3.0,
17.4.0, 17.5.0, 17.6.0, 17.7.0, 18.0.0,
18.1.0, 18.2.0, 18.3.0, 18.4.0, 18.5.0,
18.6.0, 18.7.0, 19.0.0, 19.1.0, 19.2.0
Historically, the first argument used with .Dt was BSD or
ATT. An unrecognized version argument after ATT is replaced
with “Unix”; for other predefined abbreviations, it is
ignored and a warning diagnostic emitted. Otherwise,
unrecognized arguments are displayed verbatim in the page
footer. For instance, this page uses “.Os groff
1.23.0.rc3.107‐ac98” whereas a locally produced page might
employ “.Os "UXYZ CS Department"”, omitting versioning.
This macro is neither callable nor parsed.
_______________________________________________________
Reply to this item at:
<https://savannah.gnu.org/bugs/?58653>
_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
- [bug #58653] want the short mdoc(7) page that Linux man-pages used to ship,
G. Branden Robinson <=