summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--mandoc.199
1 files changed, 64 insertions, 35 deletions
diff --git a/mandoc.1 b/mandoc.1
index e4fdf2b5..19d0528f 100644
--- a/mandoc.1
+++ b/mandoc.1
@@ -40,41 +40,50 @@ The
.Nm
utility formats
.Ux
-manual pages for display. The arguments are as follows:
+manual pages for display.
+The arguments are as follows:
.
.Bl -tag -width Ds
.It Fl f Ns Ar option...
-Comma-separated compiler options. See
+Comma-separated compiler options.
+See
.Sx Compiler Options
for details.
.
.It Fl m Ns Ar format
-Input format. See
+Input format.
+See
.Sx Input Formats
-for available formats. Defaults to
+for available formats.
+Defaults to
.Fl m Ns Ar andoc .
.
.It Fl O Ns Ar option...
-Comma-separated output options. See
+Comma-separated output options.
+See
.Sx Output Options
for details.
.
.It Fl T Ns Ar output
-Output format. See
+Output format.
+See
.Sx Output Formats
-for available formats. Defaults to
+for available formats.
+Defaults to
.Fl T Ns Ar ascii .
.
.It Fl V
Print version and exit.
.
.It Fl W Ns Ar err...
-Comma-separated warning options. Use
+Comma-separated warning options.
+Use
.Fl W Ns Ar all
to print warnings,
.Fl W Ns Ar error
for warnings to be considered errors and cause utility
-termination. Multiple
+termination.
+Multiple
.Fl W
arguments may be comma-separated, such as
.Fl W Ns Ar error,all .
@@ -82,7 +91,8 @@ arguments may be comma-separated, such as
.It Ar infile...
Read input from zero or more
.Ar infile .
-If unspecified, reads from stdin. If multiple files are specified,
+If unspecified, reads from stdin.
+If multiple files are specified,
.Nm
will halt with the first failed parse.
.El
@@ -115,7 +125,8 @@ input with
.Fl m Ns Ar doc
and
.Fl m Ns Ar an ,
-respectively. The
+respectively.
+The
.Xr mdoc 7
format is
.Em strongly
@@ -141,7 +152,8 @@ parser is used.
If multiple
files are specified with
.Fl m Ns Ar andoc ,
-each has its file-type determined this way. If multiple files are
+each has its file-type determined this way.
+If multiple files are
specified and
.Fl m Ns Ar doc
or
@@ -160,15 +172,19 @@ arguments (see
.Bl -tag -width Ds
.It Fl T Ns Ar ascii
Produce 7-bit ASCII output, backspace-encoded for bold and underline
-styles. This is the default. See
+styles.
+This is the default.
+See
.Sx ASCII Output .
.
.It Fl T Ns Ar html
-Produce strict HTML-4.01 output, with a sane default style. See
+Produce strict HTML-4.01 output, with a sane default style.
+See
.Sx HTML Output .
.
.It Fl T Ns Ar xhtml
-Produce strict XHTML-1.0 output, with a sane default style. See
+Produce strict XHTML-1.0 output, with a sane default style.
+See
.Sx XHTML Output .
.
.It Fl T Ns Ar tree
@@ -195,7 +211,8 @@ flag.
.Bl -tag -width Ds
.It Fl f Ns Ar ign-scope
When rewinding the scope of a block macro, forces the compiler to ignore
-scope violations. This can seriously mangle the resulting tree.
+scope violations.
+This can seriously mangle the resulting tree.
.Pq mdoc only
.
.It Fl f Ns Ar ign-escape
@@ -220,8 +237,8 @@ and
.Fl f Ns Ar no-ign-chars .
.
.It Fl f Ns Ar ign-errors
-When parsing multiple files, don't halt when one errors out. Useful
-with
+When parsing multiple files, don't halt when one errors out.
+Useful with
.Fl T Ns Ar lint
over a large set of manuals passed on the command line.
.El
@@ -237,7 +254,8 @@ accepts output options:
.It Fl O Ns Ar style=style.css
The file
.Ar style.css
-is used for an external style-sheet. This must be a valid absolute or
+is used for an external style-sheet.
+This must be a valid absolute or
relative URI.
.It Fl O Ns Ar includes=fmt
The string
@@ -246,9 +264,11 @@ for example,
.Ar ../src/%I.html ,
is used as a template for linked header files (usually via the
.Sq \&In
-macro). Instances of
+macro).
+Instances of
.Sq \&%I
-are replaced with the include filename. The default is not to present a
+are replaced with the include filename.
+The default is not to present a
hyperlink.
.It Fl O Ns Ar man=fmt
The string
@@ -257,12 +277,14 @@ for example,
.Ar ../html%S/%N.%S.html ,
is used as a template for linked manuals (usually via the
.Sq \&Xr
-macro). Instances of
+macro).
+Instances of
.Sq \&%N
and
.Sq %S
are replaced with the linked manual's name and section, respectively.
-If no section is included, section 1 is assumed. The default is not to
+If no section is included, section 1 is assumed.
+The default is not to
present a hyperlink.
.El
.
@@ -276,7 +298,8 @@ a body composed of sections and sub-sections, and a footer.
The text style of output characters (non-macro characters, punctuation,
and white-space) is dictated by context.
.Pp
-White-space is generally stripped from input. This can be changed with
+White-space is generally stripped from input.
+This can be changed with
character escapes (specified in
.Xr mandoc_char 7 )
or literal modes (specified in
@@ -330,7 +353,8 @@ is rendered as
.Sq _ Ns \e[bs] Ns c ,
where
.Sq \e[bs]
-is the back-space character number 8. Emboldened characters are rendered as
+is the back-space character number 8.
+Emboldened characters are rendered as
.Sq c Ns \e[bs] Ns c .
.Pp
The special characters documented in
@@ -346,8 +370,9 @@ Output produced by
.Fl T Ns Ar html
conforms to HTML-4.01 strict.
.Pp
-Font styles and page structure are applied using CSS2. By default, no
-font style is applied to any text, although CSS2 is hard-coded to format
+Font styles and page structure are applied using CSS2.
+By default, no font style is applied to any text,
+although CSS2 is hard-coded to format
the basic structure of output.
.Pp
The
@@ -374,7 +399,7 @@ output modes are identical.
To page manuals to the terminal:
.
.Pp
-.D1 % mandoc \-Wall,error \-fstrict mandoc.1 2>&1 | less
+.D1 % mandoc \-Wall,error \-fstrict mandoc.1 2\*(Gt&1 | less
.D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less
.
.Pp
@@ -382,7 +407,7 @@ To produce HTML manuals with
.Ar style.css
as the style-sheet:
.Pp
-.D1 % mandoc \-Thtml -Ostyle=style.css mdoc.7 > mdoc.7.html
+.D1 % mandoc \-Thtml -Ostyle=style.css mdoc.7 \*(Gt mdoc.7.html
.Pp
To check over a large set of manuals:
.
@@ -425,7 +450,8 @@ the
.Xr mdoc 7
macro does not underline when scoped under an
.Sq \&It
-in the FILES section. This behaves correctly in
+in the FILES section.
+This behaves correctly in
.Nm .
.
.It
@@ -467,8 +493,10 @@ The
escape will revert the font to the previous
.Sq \ef
escape, not to the last rendered decoration, which is now dictated by
-CSS instead of hard-coded. It also will not span past the current
-scope, for the same reason. Note that in
+CSS instead of hard-coded.
+It also will not span past the current scope,
+for the same reason.
+Note that in
.Sx ASCII Output
mode, this will work fine.
.It
@@ -491,9 +519,9 @@ lists render similarly.
.
.
.Sh SEE ALSO
+.Xr man 7 ,
.Xr mandoc_char 7 ,
-.Xr mdoc 7 ,
-.Xr man 7
+.Xr mdoc 7
.
.Sh AUTHORS
The
@@ -519,7 +547,8 @@ and
.Fl T Ns Ar xhtml ,
the maximum size of an element attribute is determined by
.Dv BUFSIZ ,
-which is usually 1024 bytes. Be aware of this when setting long link
+which is usually 1024 bytes.
+Be aware of this when setting long link
formats, e.g.,
.Fl O Ns Ar style=really/long/link .
.