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

[mandoc.git] / mandoc.1

diff --git a/mandoc.1 b/mandoc.1
index 552e2102c8d65b45a940e4c7d343075c4a9b9fa6..ae7200821eea3d3cbf80020fbfa82fad152f19ac 100644 (file)
--- a/mandoc.1
+++ b/mandoc.1
@@ -1,4 +1,4 @@
-.\"    $Id: mandoc.1,v 1.186 2017/05/17 22:43:56 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,7 +15,7 @@
 .\" 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: May 17 2017 $
+.Dd $Mdocdate: June 13 2017 $

 .Dt MANDOC 1
 .Os
 .Sh NAME
 .Dt MANDOC 1
 .Os
 .Sh NAME


@@ -75,6 +75,11 @@ and for the
 .Xr man 7
 .Ic \&TH
 macro.
 .Xr man 7
 .Ic \&TH
 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


@@ -219,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.


@@ -253,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


@@ -299,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


@@ -635,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


@@ -746,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"


@@ -1346,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


@@ -1693,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