version 1.225, 2018/05/03 14:21:46 |
version 1.236, 2019/01/01 08:18:11 |
|
|
is the back-space character number 8. |
is the back-space character number 8. |
Emboldened characters are rendered as |
Emboldened characters are rendered as |
.Sq c Ns \e[bs] Ns c . |
.Sq c Ns \e[bs] Ns c . |
|
This markup is typically converted to appropriate terminal sequences by |
|
the pager or |
|
.Xr ul 1 . |
|
To remove the markup, pipe the output to |
|
.Xr col 1 |
|
.Fl b |
|
instead. |
.Pp |
.Pp |
The special characters documented in |
The special characters documented in |
.Xr mandoc_char 7 |
.Xr mandoc_char 7 |
Line 290 One useful application is for checking that |
|
Line 297 One useful application is for checking that |
|
output formats in the same way as the |
output formats in the same way as the |
.Xr mdoc 7 |
.Xr mdoc 7 |
source it was generated from. |
source it was generated from. |
|
.It Cm tag Ns Op = Ns Ar term |
|
If the formatted manual page is opened in a pager, |
|
go to the definition of the |
|
.Ar term |
|
rather than showing the manual page from the beginning. |
|
If no |
|
.Ar term |
|
is specified, reuse the first command line argument that is not a |
|
.Ar section |
|
number. |
|
If that argument is in |
|
.Xr apropos 1 |
|
.Ar key Ns = Ns Ar val |
|
format, only the |
|
.Ar val |
|
is used rather than the argument as a whole. |
|
This is useful for commands like |
|
.Ql man -akO tag Ic=ulimit |
|
to search for a keyword and jump right to its definition |
|
in the matching manual pages. |
.It Cm width Ns = Ns Ar width |
.It Cm width Ns = Ns Ar width |
The output width is set to |
The output width is set to |
.Ar width |
.Ar width |
Line 308 Equations rendered from |
|
Line 335 Equations rendered from |
|
.Xr eqn 7 |
.Xr eqn 7 |
blocks use MathML. |
blocks use MathML. |
.Pp |
.Pp |
The |
The file |
.Pa mandoc.css |
.Pa /usr/share/misc/mandoc.css |
file documents style-sheet classes available for customising output. |
documents style-sheet classes available for customising output. |
If a style-sheet is not specified with |
If a style-sheet is not specified with |
.Fl O Cm style , |
.Fl O Cm style , |
.Fl T Cm html |
.Fl T Cm html |
|
|
are replaced with the include filename. |
are replaced with the include filename. |
The default is not to present a |
The default is not to present a |
hyperlink. |
hyperlink. |
.It Cm man Ns = Ns Ar fmt |
.It Cm man Ns = Ns Ar fmt Ns Op ; Ns Ar fmt |
The string |
The string |
.Ar fmt , |
.Ar fmt , |
for example, |
for example, |
Line 361 are replaced with the linked manual's name and section |
|
Line 388 are replaced with the linked manual's name and section |
|
If no section is included, section 1 is assumed. |
If no section is included, section 1 is assumed. |
The default is not to |
The default is not to |
present a hyperlink. |
present a hyperlink. |
|
If two formats are given and a file |
|
.Ar %N.%S |
|
exists in the current directory, the first format is used; |
|
otherwise, the second format is used. |
.It Cm style Ns = Ns Ar style.css |
.It Cm style Ns = Ns Ar style.css |
The file |
The file |
.Ar style.css |
.Ar style.css |
is used for an external style-sheet. |
is used for an external style-sheet. |
This must be a valid absolute or |
This must be a valid absolute or |
relative URI. |
relative URI. |
|
.It Cm toc |
|
If an input file contains at least two non-standard sections, |
|
print a table of contents near the beginning of the output. |
.El |
.El |
.Ss Locale Output |
.Ss Locale Output |
By default, |
By default, |
Line 667 To page manuals to the terminal: |
|
Line 701 To page manuals to the terminal: |
|
.Dl $ mandoc -l mandoc.1 man.1 apropos.1 makewhatis.8 |
.Dl $ mandoc -l mandoc.1 man.1 apropos.1 makewhatis.8 |
.Pp |
.Pp |
To produce HTML manuals with |
To produce HTML manuals with |
.Pa mandoc.css |
.Pa /usr/share/misc/mandoc.css |
as the style-sheet: |
as the style-sheet: |
.Pp |
.Pp |
.Dl $ mandoc \-T html -O style=mandoc.css mdoc.7 \*(Gt mdoc.7.html |
.Dl $ mandoc \-T html -O style=/usr/share/misc/mandoc.css mdoc.7 > mdoc.7.html |
.Pp |
.Pp |
To check over a large set of manuals: |
To check over a large set of manuals: |
.Pp |
.Pp |
Line 678 To check over a large set of manuals: |
|
Line 712 To check over a large set of manuals: |
|
.Pp |
.Pp |
To produce a series of PostScript manuals for A4 paper: |
To produce a series of PostScript manuals for A4 paper: |
.Pp |
.Pp |
.Dl $ mandoc \-T ps \-O paper=a4 mdoc.7 man.7 \*(Gt manuals.ps |
.Dl $ mandoc \-T ps \-O paper=a4 mdoc.7 man.7 > manuals.ps |
.Pp |
.Pp |
Convert a modern |
Convert a modern |
.Xr mdoc 7 |
.Xr mdoc 7 |
Line 688 format, for use on systems lacking an |
|
Line 722 format, for use on systems lacking an |
|
.Xr mdoc 7 |
.Xr mdoc 7 |
parser: |
parser: |
.Pp |
.Pp |
.Dl $ mandoc \-T man foo.mdoc \*(Gt foo.man |
.Dl $ mandoc \-T man foo.mdoc > foo.man |
.Sh DIAGNOSTICS |
.Sh DIAGNOSTICS |
Messages displayed by |
Messages displayed by |
.Nm |
.Nm |
follow this format: |
follow this format: |
.Bd -ragged -offset indent |
.Bd -ragged -offset indent |
.Nm : |
.Nm : |
.Ar file : Ns Ar line : Ns Ar column : level : message : macro args |
.Ar file : Ns Ar line : Ns Ar column : level : message : macro arguments |
.Pq Ar os |
.Pq Ar os |
.Ed |
.Ed |
.Pp |
.Pp |
Line and column numbers start at 1. |
The first three fields identify the |
|
.Ar file |
|
name, |
|
.Ar line |
|
number, and |
|
.Ar column |
|
number of the input file where the message was triggered. |
|
The line and column numbers start at 1. |
Both are omitted for messages referring to an input file as a whole. |
Both are omitted for messages referring to an input file as a whole. |
Macro names and arguments are omitted where meaningless. |
All |
|
.Ar level |
|
and |
|
.Ar message |
|
strings are explained below. |
|
The name of the |
|
.Ar macro |
|
triggering the message and its |
|
.Ar arguments |
|
are omitted where meaningless. |
The |
The |
.Ar os |
.Ar os |
operating system specifier is omitted for messages that are relevant |
operating system specifier is omitted for messages that are relevant |
Line 853 Consider using the conventional |
|
Line 903 Consider using the conventional |
|
date format |
date format |
.Dq "Month dd, yyyy" |
.Dq "Month dd, yyyy" |
instead. |
instead. |
|
.It Sy "normalizing date format to" : No ... |
|
.Pq mdoc , man |
|
The |
|
.Ic \&Dd |
|
or |
|
.Ic \&TH |
|
macro provides an abbreviated month name or a day number with a |
|
leading zero. |
|
In the formatted output, the month name is written out in full |
|
and the leading zero is omitted. |
.It Sy "lower case character in document title" |
.It Sy "lower case character in document title" |
.Pq mdoc , man |
.Pq mdoc , man |
The title is still used as given in the |
The title is still used as given in the |
|
|
.Cm off . |
.Cm off . |
The invalid argument is moved out of the macro, which leaves the macro |
The invalid argument is moved out of the macro, which leaves the macro |
empty, causing it to toggle the spacing mode. |
empty, causing it to toggle the spacing mode. |
|
.It Sy "argument contains two font escapes" |
|
.Pq roff |
|
The second argument of a |
|
.Ic char |
|
request contains more than one font escape sequence. |
|
A wrong font may remain active after using the character. |
.It Sy "unknown font, skipping request" |
.It Sy "unknown font, skipping request" |
.Pq man , tbl |
.Pq man , tbl |
A |
A |
Line 1641 Start it on a new input line to help formatters produc |
|
Line 1707 Start it on a new input line to help formatters produc |
|
.It Sy "invalid escape sequence" |
.It Sy "invalid escape sequence" |
.Pq roff |
.Pq roff |
An escape sequence has an invalid opening argument delimiter, lacks the |
An escape sequence has an invalid opening argument delimiter, lacks the |
closing argument delimiter, or the argument has too few characters. |
closing argument delimiter, the argument is of an invalid form, or it is |
|
a character escape sequence with an invalid name. |
If the argument is incomplete, |
If the argument is incomplete, |
.Ic \e* |
.Ic \e* |
and |
and |
|
|
.Ic \ew |
.Ic \ew |
to the length of the incomplete argument. |
to the length of the incomplete argument. |
All other invalid escape sequences are ignored. |
All other invalid escape sequences are ignored. |
|
.It Sy "undefined escape, printing literally" |
|
.Pq roff |
|
In an escape sequence, the first character |
|
right after the leading backslash is invalid. |
|
That character is printed literally, |
|
which is equivalent to ignoring the backslash. |
.It Sy "undefined string, using \(dq\(dq" |
.It Sy "undefined string, using \(dq\(dq" |
.Pq roff |
.Pq roff |
If a string is used without being defined before, |
If a string is used without being defined before, |
|
|
macro. |
macro. |
It may be mistyped or unsupported. |
It may be mistyped or unsupported. |
The request or macro is discarded including its arguments. |
The request or macro is discarded including its arguments. |
|
.It Sy "skipping request outside macro" |
|
.Pq roff |
|
A |
|
.Ic shift |
|
or |
|
.Ic return |
|
request occurs outside any macro definition and has no effect. |
.It Sy "skipping insecure request" |
.It Sy "skipping insecure request" |
.Pq roff |
.Pq roff |
An input file attempted to run a shell command |
An input file attempted to run a shell command |
Line 1906 When parsing for a request or a user-defined macro nam |
|
Line 1986 When parsing for a request or a user-defined macro nam |
|
only the escape sequence is discarded. |
only the escape sequence is discarded. |
The characters preceding it are used as the request or macro name, |
The characters preceding it are used as the request or macro name, |
the characters following it are used as the arguments to the request or macro. |
the characters following it are used as the arguments to the request or macro. |
|
.It Sy "using macro argument outside macro" |
|
.Pq roff |
|
The escape sequence \e$ occurs outside any macro definition |
|
and expands to the empty string. |
|
.It Sy "argument number is not numeric" |
|
.Pq roff |
|
The argument of the escape sequence \e$ is not a digit; |
|
the escape sequence expands to the empty string. |
.It Sy "NOT IMPLEMENTED: Bd -file" |
.It Sy "NOT IMPLEMENTED: Bd -file" |
.Pq mdoc |
.Pq mdoc |
For security reasons, the |
For security reasons, the |
Line 1934 macro fails to specify the list type. |
|
Line 2022 macro fails to specify the list type. |
|
The argument of a |
The argument of a |
.Ic \&ce |
.Ic \&ce |
request is not a number. |
request is not a number. |
|
.It Sy "argument is not a character" |
|
.Pq roff |
|
The first argument of a |
|
.Ic char |
|
request is neither a single ASCII character |
|
nor a single character escape sequence. |
|
The request is ignored including all its arguments. |
.It Sy "missing manual name, using \(dq\(dq" |
.It Sy "missing manual name, using \(dq\(dq" |
.Pq mdoc |
.Pq mdoc |
The first call to |
The first call to |
|
|
.Ic \&gsize |
.Ic \&gsize |
statement has a non-numeric or negative argument or no argument at all. |
statement has a non-numeric or negative argument or no argument at all. |
The invalid request or statement is ignored. |
The invalid request or statement is ignored. |
|
.It Sy "excessive shift" |
|
.Pq roff |
|
The argument of a |
|
.Ic shift |
|
request is larger than the number of arguments of the macro that is |
|
currently being executed. |
|
All macro arguments are deleted and \en(.$ is set to zero. |
.It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq" |
.It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq" |
.Pq roff |
.Pq roff |
For security reasons, |
For security reasons, |
Line 2090 implementations but not by |
|
Line 2192 implementations but not by |
|
.Nm |
.Nm |
was found in an input file. |
was found in an input file. |
It is replaced by a question mark. |
It is replaced by a question mark. |
|
.It Sy "unsupported escape sequence" |
|
.Pq roff |
|
An input file contains an escape sequence supported by GNU troff |
|
or Heirloom troff but not by |
|
.Nm , |
|
and it is likely that this will cause information loss |
|
or considerable misformatting. |
.It Sy "unsupported roff request" |
.It Sy "unsupported roff request" |
.Pq roff |
.Pq roff |
An input file contains a |
An input file contains a |