version 1.248, 2015/01/03 00:59:13 |
version 1.255, 2015/09/24 18:41:22 |
|
|
must be one of the following: |
must be one of the following: |
.Bl -tag -width 13n -offset indent |
.Bl -tag -width 13n -offset indent |
.It Fl centered |
.It Fl centered |
Produce one output line from each input line, and centre-justify each line. |
Produce one output line from each input line, and center-justify each line. |
Using this display type is not recommended; many |
Using this display type is not recommended; many |
.Nm |
.Nm |
implementations render it poorly. |
implementations render it poorly. |
Line 822 which has no effect; |
|
Line 822 which has no effect; |
|
.Cm right , |
.Cm right , |
which justifies to the right margin; or |
which justifies to the right margin; or |
.Cm center , |
.Cm center , |
which aligns around an imagined centre axis. |
which aligns around an imagined center axis. |
.It |
.It |
A macro invocation, which selects a predefined width |
A macro invocation, which selects a predefined width |
associated with that macro. |
associated with that macro. |
|
|
A function name. |
A function name. |
Its syntax is as follows: |
Its syntax is as follows: |
.Bd -ragged -offset indent |
.Bd -ragged -offset indent |
.Pf \. Ns Sx \&Fn |
.Pf . Sx \&Fn |
.Op Ar functype |
.Op Ar functype |
.Ar funcname |
.Ar funcname |
.Op Oo Ar argtype Oc Ar argname |
.Op Oo Ar argtype Oc Ar argname |
Line 1758 is preferred for displaying code; the |
|
Line 1758 is preferred for displaying code; the |
|
.Sx \&Ic |
.Sx \&Ic |
macro is used when referring to specific instructions. |
macro is used when referring to specific instructions. |
.Ss \&In |
.Ss \&In |
An |
The name of an include file. |
.Dq include |
This macro is most often used in section 2, 3, and 9 manual pages. |
file. |
.Pp |
When invoked as the first macro on an input line in the |
When invoked as the first macro on an input line in the |
.Em SYNOPSIS |
.Em SYNOPSIS |
section, the argument is displayed in angle brackets |
section, the argument is displayed in angle brackets |
and preceded by |
and preceded by |
.Dq #include , |
.Qq #include , |
and a blank line is inserted in front if there is a preceding |
and a blank line is inserted in front if there is a preceding |
function declaration. |
function declaration. |
This is most often used in section 2, 3, and 9 manual pages. |
In other sections, it only encloses its argument in angle brackets |
|
and causes no line break. |
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.In sys/types.h |
.Dl \&.In sys/types.h |
|
|
.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv |
.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv |
.Ss \&Nd |
.Ss \&Nd |
A one line description of the manual's content. |
A one line description of the manual's content. |
This may only be invoked in the |
This is the mandatory last macro of the |
.Em SYNOPSIS |
.Em NAME |
section subsequent the |
section and not appropriate for other sections. |
.Sx \&Nm |
|
macro. |
|
.Pp |
.Pp |
Examples: |
Examples: |
.Dl Pf . Sx \&Nd mdoc language reference |
.Dl Pf . Sx \&Nd mdoc language reference |
Line 2094 It is suggested to leave it unspecified, in which case |
|
Line 2093 It is suggested to leave it unspecified, in which case |
|
.Xr mandoc 1 |
.Xr mandoc 1 |
uses its |
uses its |
.Fl Ios |
.Fl Ios |
argument, or, if that isn't specified either, |
argument or, if that isn't specified either, |
.Fa sysname |
.Fa sysname |
and |
and |
.Fa release |
.Fa release |
|
|
\&.%A J. D. Ullman |
\&.%A J. D. Ullman |
\&.%B Introduction to Automata Theory, Languages, and Computation |
\&.%B Introduction to Automata Theory, Languages, and Computation |
\&.%I Addison-Wesley |
\&.%I Addison-Wesley |
\&.%C Reading, Massachusettes |
\&.%C Reading, Massachusetts |
\&.%D 1979 |
\&.%D 1979 |
\&.Re |
\&.Re |
.Ed |
.Ed |
Line 3133 Manually switching the font using the |
|
Line 3132 Manually switching the font using the |
|
font escape sequences is never required. |
font escape sequences is never required. |
.Sh COMPATIBILITY |
.Sh COMPATIBILITY |
This section provides an incomplete list of compatibility issues |
This section provides an incomplete list of compatibility issues |
between mandoc and other troff implementations, at this time limited |
between mandoc and GNU troff |
to GNU troff |
|
.Pq Qq groff . |
.Pq Qq groff . |
The term |
|
.Qq historic groff |
|
refers to groff versions before 1.17, |
|
which featured a significant update of the |
|
.Pa doc.tmac |
|
file. |
|
.Pp |
.Pp |
Heirloom troff, the other significant troff implementation accepting |
|
\-mdoc, is similar to historic groff. |
|
.Pp |
|
The following problematic behaviour is found in groff: |
The following problematic behaviour is found in groff: |
.ds hist (Historic groff only.) |
|
.Pp |
.Pp |
.Bl -dash -compact |
.Bl -dash -compact |
.It |
.It |
Display macros |
|
.Po |
|
.Sx \&Bd , |
|
.Sx \&Dl , |
|
and |
|
.Sx \&D1 |
|
.Pc |
|
may not be nested. |
|
\*[hist] |
|
.It |
|
.Sx \&At |
|
with unknown arguments produces no output at all. |
|
\*[hist] |
|
Newer groff and mandoc print |
|
.Qq AT&T UNIX |
|
and the arguments. |
|
.It |
|
.Sx \&Bl Fl column |
|
does not recognise trailing punctuation characters when they immediately |
|
precede tabulator characters, but treats them as normal text and |
|
outputs a space before them. |
|
.It |
|
.Sx \&Bd Fl ragged compact |
|
does not start a new line. |
|
\*[hist] |
|
.It |
|
.Sx \&Dd |
.Sx \&Dd |
with non-standard arguments behaves very strangely. |
with non-standard arguments behaves very strangely. |
When there are three arguments, they are printed verbatim. |
When there are three arguments, they are printed verbatim. |
Line 3185 but without any arguments the string |
|
Line 3147 but without any arguments the string |
|
.Dq Epoch |
.Dq Epoch |
is printed. |
is printed. |
.It |
.It |
.Sx \&Fl |
|
does not print a dash for an empty argument. |
|
\*[hist] |
|
.It |
|
.Sx \&Fn |
|
does not start a new line unless invoked as the line macro in the |
|
.Em SYNOPSIS |
|
section. |
|
\*[hist] |
|
.It |
|
.Sx \&Fo |
|
with |
|
.Pf non- Sx \&Fa |
|
children causes inconsistent spacing between arguments. |
|
In mandoc, a single space is always inserted between arguments. |
|
.It |
|
.Sx \&Ft |
|
in the |
|
.Em SYNOPSIS |
|
causes inconsistent vertical spacing, depending on whether a prior |
|
.Sx \&Fn |
|
has been invoked. |
|
See |
|
.Sx \&Ft |
|
and |
|
.Sx \&Fn |
|
for the normalised behaviour in mandoc. |
|
.It |
|
.Sx \&In |
|
ignores additional arguments and is not treated specially in the |
|
.Em SYNOPSIS . |
|
\*[hist] |
|
.It |
|
.Sx \&It |
|
sometimes requires a |
|
.Fl nested |
|
flag. |
|
\*[hist] |
|
In new groff and mandoc, any list may be nested by default and |
|
.Fl enum |
|
lists will restart the sequence only for the sub-list. |
|
.It |
|
.Sx \&Li |
|
followed by a delimiter is incorrectly used in some manuals |
|
instead of properly quoting that character, which sometimes works with |
|
historic groff. |
|
.It |
|
.Sx \&Lk |
.Sx \&Lk |
only accepts a single link-name argument; the remainder is misformatted. |
only accepts a single link-name argument; the remainder is misformatted. |
.It |
.It |
Line 3245 can only be called by other macros, but not at the beg |
|
Line 3160 can only be called by other macros, but not at the beg |
|
.Sx \&%C |
.Sx \&%C |
is not implemented (up to and including groff-1.22.2). |
is not implemented (up to and including groff-1.22.2). |
.It |
.It |
Historic groff only allows up to eight or nine arguments per macro input |
|
line, depending on the exact situation. |
|
Providing more arguments causes garbled output. |
|
The number of arguments on one input line is not limited with mandoc. |
|
.It |
|
Historic groff has many un-callable macros. |
|
Most of these (excluding some block-level macros) are callable |
|
in new groff and mandoc. |
|
.It |
|
.Sq \(ba |
|
(vertical bar) is not fully supported as a delimiter. |
|
\*[hist] |
|
.It |
|
.Sq \ef |
.Sq \ef |
.Pq font face |
.Pq font face |
and |
and |
Line 3275 The following features are unimplemented in mandoc: |
|
Line 3177 The following features are unimplemented in mandoc: |
|
.Bl -dash -compact |
.Bl -dash -compact |
.It |
.It |
.Sx \&Bd |
.Sx \&Bd |
.Fl file Ar file . |
.Fl file Ar file |
|
is unsupported for security reasons. |
.It |
.It |
.Sx \&Bd |
.Sx \&Bd |
|
.Fl filled |
|
does not adjust the right margin, but is an alias for |
|
.Sx \&Bd |
|
.Fl ragged . |
|
.It |
|
.Sx \&Bd |
|
.Fl literal |
|
does not use a literal font, but is an alias for |
|
.Sx \&Bd |
|
.Fl unfilled . |
|
.It |
|
.Sx \&Bd |
.Fl offset Cm center |
.Fl offset Cm center |
and |
and |
.Fl offset Cm right . |
.Fl offset Cm right |
Groff does not implement centred and flush-right rendering either, |
don't work. |
|
Groff does not implement centered and flush-right rendering either, |
but produces large indentations. |
but produces large indentations. |
.El |
.El |
.Sh SEE ALSO |
.Sh SEE ALSO |