simple implementation of the roff(7) .als (macro alias) request,

[mandoc.git] / mandoc.1

diff --git a/mandoc.1 b/mandoc.1
index c5f38c2bb8a51396f0fe0b45c17a94fd318cfdf0..ae7200821eea3d3cbf80020fbfa82fad152f19ac 100644 (file)
--- a/mandoc.1
+++ b/mandoc.1
@@ -1,4 +1,4 @@
-.\"    $Id: mandoc.1,v 1.176 2017/03/04 17:17:34 schwarze Exp $
+.\"    $Id: mandoc.1,v 1.199 2017/06/13 15:06:56 schwarze Exp $

 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2012, 2014-2017 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2012, 2014-2017 Ingo Schwarze <schwarze@openbsd.org>


@@ -15,19 +15,19 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"

-.Dd $Mdocdate: March 4 2017 $
+.Dd $Mdocdate: June 13 2017 $

 .Dt MANDOC 1
 .Os
 .Sh NAME
 .Nm mandoc
 .Dt MANDOC 1
 .Os
 .Sh NAME
 .Nm mandoc

-.Nd format and display UNIX manuals
+.Nd format manual pages

 .Sh SYNOPSIS
 .Nm mandoc
 .Sh SYNOPSIS
 .Nm mandoc

-.Op Fl acfhkl
+.Op Fl ac

 .Op Fl I Cm os Ns = Ns Ar name
 .Op Fl K Ar encoding
 .Op Fl I Cm os Ns = Ns Ar name
 .Op Fl K Ar encoding

-.Op Fl m Ns Ar format
-.Op Fl O Ar option
+.Op Fl mdoc | man
+.Op Fl O Ar options

 .Op Fl T Ar output
 .Op Fl W Ar level
 .Op Ar
 .Op Fl T Ar output
 .Op Fl W Ar level
 .Op Ar


@@ -44,9 +44,7 @@ reads
 .Xr mdoc 7
 or
 .Xr man 7
 .Xr mdoc 7
 or
 .Xr man 7

-text from stdin, implying
-.Fl m Ns Cm andoc ,
-and produces
+text from stdin and produces

 .Fl T Cm locale
 output.
 .Pp
 .Fl T Cm locale
 output.
 .Pp


@@ -67,28 +65,21 @@ to paginate them.
 This is the default.
 It can be specified to override
 .Fl a .
 This is the default.
 It can be specified to override
 .Fl a .

-.It Fl f
-A synonym for
-.Xr whatis 1 .
-This overrides any earlier
-.Fl k
-and
-.Fl l
-options.
-.It Fl h
-Display only the SYNOPSIS lines.
-Implies
-.Fl c .

 .It Fl I Cm os Ns = Ns Ar name
 Override the default operating system
 .Ar name
 for the
 .Xr mdoc 7
 .It Fl I Cm os Ns = Ns Ar name
 Override the default operating system
 .Ar name
 for the
 .Xr mdoc 7

-.Sq \&Os
+.Ic \&Os

 and for the
 .Xr man 7
 and for the
 .Xr man 7

-.Sq \&TH
+.Ic \&TH

 macro.
 macro.

+This can also be used to perform style checks according to the
+conventions of one operating system while running on a different
+operating system; see
+.Sx Style messages
+for details.

 .It Fl K Ar encoding
 Specify the input encoding.
 The supported
 .It Fl K Ar encoding
 Specify the input encoding.
 The supported


@@ -122,30 +113,29 @@ sequence, input is interpreted as
 Otherwise, input is interpreted as
 .Cm iso-8859-1 .
 .El
 Otherwise, input is interpreted as
 .Cm iso-8859-1 .
 .El

-.It Fl k
-A synonym for
-.Xr apropos 1 .
-This overrides any earlier
-.Fl f
-and
-.Fl l
-options.
-.It Fl l
-A synonym for
-.Fl a .
-Also reverts any earlier
-.Fl f
-and
-.Fl k
-options.
-.It Fl m Ns Ar format
-Input format.
-See
-.Sx Input Formats
-for available formats.
-Defaults to
-.Fl m Ns Cm andoc .
-.It Fl O Ar option
+.It Fl mdoc | man
+With
+.Fl mdoc ,
+all input files are interpreted as
+.Xr mdoc 7 .
+With
+.Fl man ,
+all input files are interpreted as
+.Xr man 7 .
+By default, the input language is automatically detected for each file:
+if the the first macro is
+.Ic \&Dd
+or
+.Ic \&Dt ,
+the
+.Xr mdoc 7
+parser is used; otherwise, the
+.Xr man 7
+parser is used.
+With other arguments,
+.Fl m
+is silently ignored.
+.It Fl O Ar options

 Comma-separated output options.
 .It Fl T Ar output
 Output format.
 Comma-separated output options.
 .It Fl T Ar output
 Output format.


@@ -161,13 +151,14 @@ to be reported on the standard error output and to affect the exit status.
 The
 .Ar level
 can be
 The
 .Ar level
 can be

+.Cm style ,

 .Cm warning ,
 .Cm error ,
 or
 .Cm unsupp ;
 .Cm all
 is an alias for
 .Cm warning ,
 .Cm error ,
 or
 .Cm unsupp ;
 .Cm all
 is an alias for

-.Cm warning .
+.Cm style .

 By default,
 .Nm
 is silent.
 By default,
 .Nm
 is silent.


@@ -198,6 +189,9 @@ If multiple files are specified,
 will halt with the first failed parse.
 .El
 .Pp
 will halt with the first failed parse.
 .El
 .Pp

+The options
+.Fl fhklw
+are also supported and are documented in man(1).

 In
 .Fl f
 and
 In
 .Fl f
 and


@@ -205,53 +199,13 @@ and
 mode,
 .Nm
 also supports the options
 mode,
 .Nm
 also supports the options

-.Fl CMmOSsw
+.Fl CMmOSs

 described in the
 .Xr apropos 1
 manual.
 described in the
 .Xr apropos 1
 manual.

-.Ss Input Formats
-The
-.Nm
-utility accepts
-.Xr mdoc 7
-and
-.Xr man 7
-input with
-.Fl m Ns Cm doc
-and
-.Fl m Ns Cm an ,
-respectively.
-The
-.Xr mdoc 7
-format is
-.Em strongly
-recommended;
-.Xr man 7
-should only be used for legacy manuals.
-.Pp
-A third option,
-.Fl m Ns Cm andoc ,
-which is also the default, determines encoding on-the-fly: if the first
-non-comment macro is
-.Sq \&Dd
-or
-.Sq \&Dt ,
-the
-.Xr mdoc 7
-parser is used; otherwise, the
-.Xr man 7
-parser is used.
-.Pp
-If multiple
-files are specified with
-.Fl m Ns Cm andoc ,
-each has its file-type determined this way.
-If multiple files are
-specified and
-.Fl m Ns Cm doc
-or
-.Fl m Ns Cm an
-is specified, then this format is used exclusively.
+The options
+.Fl fkl
+are mutually exclusive and override each other.

 .Ss Output Formats
 The
 .Nm
 .Ss Output Formats
 The
 .Nm


@@ -270,7 +224,7 @@ See
 .It Fl T Cm lint
 Parse only: produce no output.
 Implies
 .It Fl T Cm lint
 Parse only: produce no output.
 Implies

-.Fl W Cm warning .
+.Fl W Cm style .

 .It Fl T Cm locale
 Encode output using the current locale.
 This is the default.
 .It Fl T Cm locale
 Encode output using the current locale.
 This is the default.


@@ -304,9 +258,6 @@ See
 Encode output in the UTF\-8 multi-byte format.
 See
 .Sx UTF\-8 Output .
 Encode output in the UTF\-8 multi-byte format.
 See
 .Sx UTF\-8 Output .

-.It Fl T Cm xhtml
-This is a synonym for
-.Fl T Cm html .

 .El
 .Pp
 If multiple input files are specified, these will be processed by the
 .El
 .Pp
 If multiple input files are specified, these will be processed by the


@@ -350,8 +301,7 @@ Increasing this is not recommended; it may result in degraded formatting,
 for example overfull lines or ugly line breaks.
 .It Cm width Ns = Ns Ar width
 The output width is set to
 for example overfull lines or ugly line breaks.
 .It Cm width Ns = Ns Ar width
 The output width is set to

-.Ar width ,
-which will normalise to \(>=58.
+.Ar width .

 .El
 .Ss HTML Output
 Output produced by
 .El
 .Ss HTML Output
 Output produced by


@@ -391,7 +341,7 @@ The string
 for example,
 .Ar ../src/%I.html ,
 is used as a template for linked header files (usually via the
 for example,
 .Ar ../src/%I.html ,
 is used as a template for linked header files (usually via the

-.Sq \&In
+.Ic \&In

 macro).
 Instances of
 .Sq \&%I
 macro).
 Instances of
 .Sq \&%I


@@ -404,7 +354,7 @@ The string
 for example,
 .Ar ../html%S/%N.%S.html ,
 is used as a template for linked manuals (usually via the
 for example,
 .Ar ../html%S/%N.%S.html ,
 is used as a template for linked manuals (usually via the

-.Sq \&Xr
+.Ic \&Xr

 macro).
 Instances of
 .Sq \&%N
 macro).
 Instances of
 .Sq \&%N


@@ -450,7 +400,7 @@ If the input format is
 .Xr man 7 ,
 the input is copied to the output, expanding any
 .Xr roff 7
 .Xr man 7 ,
 the input is copied to the output, expanding any
 .Xr roff 7

-.Sq so
+.Ic so

 requests.
 The parser is also run, and as usual, the
 .Fl W
 requests.
 The parser is also run, and as usual, the
 .Fl W


@@ -465,6 +415,16 @@ input to the
 format conforming to
 .Lk http://daringfireball.net/projects/markdown/syntax.text\
  "John Gruber's 2004 specification" .
 format conforming to
 .Lk http://daringfireball.net/projects/markdown/syntax.text\
  "John Gruber's 2004 specification" .

+The output also almost conforms to the
+.Lk http://commonmark.org/ CommonMark
+specification.
+.Pp
+The character set used for the markdown output is ASCII.
+Non-ASCII characters are encoded as HTML entities.
+Since that is not possible in literal font contexts, because these
+are rendered as code spans and code blocks in the markdown output,
+non-ASCII characters are transliterated to ASCII approximations in
+these contexts.

 .Pp
 Markdown is a very weak markup language, so all semantic markup is
 lost, and even part of the presentational markup may be lost.
 .Pp
 Markdown is a very weak markup language, so all semantic markup is
 lost, and even part of the presentational markup may be lost.


@@ -601,8 +561,16 @@ Meta data is not available in this case.
 .It Ev MANPAGER
 Any non-empty value of the environment variable
 .Ev MANPAGER
 .It Ev MANPAGER
 Any non-empty value of the environment variable
 .Ev MANPAGER

-will be used instead of the standard pagination program,
-.Xr more 1 .
+is used instead of the standard pagination program,
+.Xr more 1 ;
+see
+.Xr man 1
+for details.
+Only used if
+.Fl a
+or
+.Fl l
+is specified.

 .It Ev PAGER
 Specifies the pagination program to use when
 .Ev MANPAGER
 .It Ev PAGER
 Specifies the pagination program to use when
 .Ev MANPAGER


@@ -610,7 +578,12 @@ is not defined.
 If neither PAGER nor MANPAGER is defined,
 .Xr more 1
 .Fl s
 If neither PAGER nor MANPAGER is defined,
 .Xr more 1
 .Fl s

-will be used.
+is used.
+Only used if
+.Fl a
+or
+.Fl l
+is specified.

 .El
 .Sh EXIT STATUS
 The
 .El
 .Sh EXIT STATUS
 The


@@ -623,27 +596,32 @@ option:
 .Pp
 .Bl -tag -width Ds -compact
 .It 0
 .Pp
 .Bl -tag -width Ds -compact
 .It 0

-No warnings or errors occurred, or those that did were ignored because
-they were lower than the requested
+No style suggestions, warnings or errors occurred, or those that
+did were ignored because they were lower than the requested

 .Ar level .
 .Ar level .

+.It 1
+At least one style suggestion occurred, but no warning or error, and
+.Fl W Cm style
+was specified.

 .It 2
 At least one warning occurred, but no error, and
 .Fl W Cm warning
 .It 2
 At least one warning occurred, but no error, and
 .Fl W Cm warning

+or
+.Fl W Cm style

 was specified.
 .It 3
 At least one parsing error occurred,
 but no unsupported feature was encountered, and
 .Fl W Cm error
 was specified.
 .It 3
 At least one parsing error occurred,
 but no unsupported feature was encountered, and
 .Fl W Cm error

-or
-.Fl W Cm warning
-was specified.
+or a lower
+.Ar level
+was requested.

 .It 4
 At least one unsupported feature was encountered, and
 .It 4
 At least one unsupported feature was encountered, and

-.Fl W Cm unsupp ,
-.Fl W Cm error
-or
-.Fl W Cm warning
-was specified.
+.Fl W Cm unsupp
+or a lower
+.Ar level
+was requested.

 .It 5
 Invalid command line arguments were specified.
 No input files have been read.
 .It 5
 Invalid command line arguments were specified.
 No input files have been read.


@@ -658,12 +636,11 @@ to exit at once, possibly in the middle of parsing or formatting a file.
 Note that selecting
 .Fl T Cm lint
 output mode implies
 Note that selecting
 .Fl T Cm lint
 output mode implies

-.Fl W Cm warning .
+.Fl W Cm style .

 .Sh EXAMPLES
 To page manuals to the terminal:
 .Pp
 .Sh EXAMPLES
 To page manuals to the terminal:
 .Pp

-.Dl $ mandoc \-W all,stop mandoc.1 2\*(Gt&1 | less
-.Dl $ mandoc mandoc.1 mdoc.3 mdoc.7 | less
+.Dl $ mandoc -l mandoc.1 man.1 apropos.1 makewhatis.8

 .Pp
 To produce HTML manuals with
 .Pa mandoc.css
 .Pp
 To produce HTML manuals with
 .Pa mandoc.css


@@ -743,9 +720,22 @@ rendering can be produced.
 Documents causing warnings may render poorly when using other
 formatting tools instead of
 .Nm .
 Documents causing warnings may render poorly when using other
 formatting tools instead of
 .Nm .

+.It Cm style
+An input file uses dubious or discouraged style.
+This is not a complaint about the syntax, and probably neither
+formatting nor portability are in danger.
+While great care is taken to avoid false positives on the higher
+message levels, the
+.Cm style
+level tries to reduce the probability that issues go unnoticed,
+so it may occasionally issue bogus suggestions.
+Please use your good judgement to decide whether any particular
+.Cm style
+suggestion really justifies a change to the input file.

 .El
 .Pp
 Messages of the
 .El
 .Pp
 Messages of the

+.Cm style ,

 .Cm warning ,
 .Cm error ,
 and
 .Cm warning ,
 .Cm error ,
 and


@@ -756,6 +746,72 @@ are hidden unless their level, or a lower level, is requested using a
 option or
 .Fl T Cm lint
 output mode.
 option or
 .Fl T Cm lint
 output mode.

+.Ss Style messages
+As indicated below, some style checks are only performed if a
+specific operating system name occurs in the arguments of the
+.Ic \&Os
+macro, of the
+.Fl Ios
+command line option, or, if neither are present, in the return value
+of the
+.Xr uname 3
+function.
+.Bl -ohang
+.It Sy "useless macro"
+.Pq mdoc
+A
+.Ic \&Bt ,
+.Ic \&Tn ,
+or
+.Ic \&Ud
+macro was found.
+Simply delete it: it serves no useful purpose.
+.It Sy "consider using OS macro"
+.Pq mdoc
+A string was found in plain text or in a
+.Ic \&Bx
+macro that could be represented using
+.Ic \&Ox ,
+.Ic \&Nx ,
+.Ic \&Fx ,
+or
+.Ic \&Dx .
+.It Sy "errnos out of order"
+.Pq mdoc, Nx
+The
+.Ic \&Er
+items in a
+.Ic \&Bl
+list are not in alphabetical order.
+.It Sy "duplicate errno"
+.Pq mdoc, Nx
+A
+.Ic \&Bl
+list contains two consecutive
+.Ic \&It
+entries describing the same
+.Ic \&Er
+number.
+.It Sy "description line ends with a full stop"
+.Pq mdoc
+Do not use punctuation at the end of an
+.Ic \&Nd
+block.
+.It Sy "no blank before trailing delimiter"
+.Pq mdoc
+The last argument of a macro that supports trailing delimiter
+arguments is longer than one byte and ends with a trailing delimiter.
+Consider inserting a blank such that the delimiter becomes a separate
+argument, thus moving it out of the scope of the macro.
+.It Sy "function name without markup"
+.Pq mdoc
+A word followed by an empty pair of parentheses occurs on a text line.
+Consider using an
+.Ic \&Fn
+or
+.Ic \&Xr
+macro.
+.El

 .Ss Warnings related to the document prologue
 .Bl -ohang
 .It Sy "missing manual title, using UNTITLED"
 .Ss Warnings related to the document prologue
 .Bl -ohang
 .It Sy "missing manual title, using UNTITLED"


@@ -908,6 +964,14 @@ The
 .Ic \&Nd
 macro lacks the required argument.
 The title line of the manual will end after the dash.
 .Ic \&Nd
 macro lacks the required argument.
 The title line of the manual will end after the dash.

+.It Sy "description line outside NAME section"
+.Pq mdoc
+An
+.Ic \&Nd
+macro appears outside the NAME section.
+The arguments are printed anyway and the following text is used for
+.Xr apropos 1 ,
+but none of that behaviour is portable.

 .It Sy "sections out of conventional order"
 .Pq mdoc
 A standard section occurs after another section it usually precedes.
 .It Sy "sections out of conventional order"
 .Pq mdoc
 A standard section occurs after another section it usually precedes.


@@ -1126,7 +1190,7 @@ or
 .Ic \&Bl
 .Fl offset
 or
 .Ic \&Bl
 .Fl offset
 or

-.Fl width.
+.Fl width .

 .It Sy "missing display type, using -ragged"
 .Pq mdoc
 The
 .It Sy "missing display type, using -ragged"
 .Pq mdoc
 The


@@ -1348,6 +1412,12 @@ or
 .Ic \&Fn
 macro contains an opening or closing parenthesis; that's probably wrong,
 parentheses are added automatically.
 .Ic \&Fn
 macro contains an opening or closing parenthesis; that's probably wrong,
 parentheses are added automatically.

+.It Sy "unknown library name"
+.Pq mdoc, not on Ox
+An
+.Ic \&Lb
+macro has an unknown name argument and will be rendered as
+.Qq library Dq Ar name .

 .It Sy "invalid content in Rs block"
 .Pq mdoc
 An
 .It Sy "invalid content in Rs block"
 .Pq mdoc
 An


@@ -1695,6 +1765,11 @@ whatever mode was active before the block.
 A
 .Ic \&Bl
 macro fails to specify the list type.
 A
 .Ic \&Bl
 macro fails to specify the list type.

+.It Sy "argument is not numeric, using 1"
+.Pq roff
+The argument of a
+.Ic \&ce
+request is not a number.

 .It Sy "missing manual name, using \(dq\(dq"
 .Pq mdoc
 The first call to
 .It Sy "missing manual name, using \(dq\(dq"
 .Pq mdoc
 The first call to