diff options
Diffstat (limited to 'mandoc.1')
| -rw-r--r-- | mandoc.1 | 101 |
1 files changed, 71 insertions, 30 deletions
@@ -1,4 +1,4 @@ -.\" $Id: mandoc.1,v 1.201 2017/06/17 23:07:00 schwarze Exp $ +.\" $Id: mandoc.1,v 1.202 2017/06/24 14:38:32 schwarze Exp $ .\" .\" 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. .\" -.Dd $Mdocdate: June 17 2017 $ +.Dd $Mdocdate: June 24 2017 $ .Dt MANDOC 1 .Os .Sh NAME @@ -75,11 +75,6 @@ and for the .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 @@ -151,14 +146,33 @@ to be reported on the standard error output and to affect the exit status. The .Ar level can be +.Cm base , .Cm style , .Cm warning , .Cm error , or -.Cm unsupp ; +.Cm unsupp . +The +.Cm base +level automatically derives the operating system from the contents of the +.Ic \&Os +macro, from the +.Fl Ios +command line option, or from the +.Xr uname 3 +return value. +The levels +.Cm openbsd +and +.Cm netbsd +are variants of +.Cm base +that bypass autodetection and request validation of base system +conventions for a particular operating system. +The level .Cm all is an alias for -.Cm style . +.Cm base . By default, .Nm is silent. @@ -224,7 +238,7 @@ See .It Fl T Cm lint Parse only: produce no output. Implies -.Fl W Cm style . +.Fl W Cm all . .It Fl T Cm locale Encode output using the current locale. This is the default. @@ -596,19 +610,23 @@ option: .Pp .Bl -tag -width Ds -compact .It 0 -No style suggestions, warnings or errors occurred, or those that -did were ignored because they were lower than the requested +No base system convention violations, style suggestions, warnings, +or errors occurred, or those that did were ignored because they +were lower than the requested .Ar level . .It 1 -At least one style suggestion occurred, but no warning or error, and +At least one base system convention violation or style suggestion +occurred, but no warning or error, and +.Fl W Cm base +or .Fl W Cm style was specified. .It 2 At least one warning occurred, but no error, and .Fl W Cm warning -or -.Fl W Cm style -was specified. +or a lower +.Ar level +was requested. .It 3 At least one parsing error occurred, but no unsupported feature was encountered, and @@ -636,7 +654,7 @@ to exit at once, possibly in the middle of parsing or formatting a file. Note that selecting .Fl T Cm lint output mode implies -.Fl W Cm style . +.Fl W Cm all . .Sh EXAMPLES To page manuals to the terminal: .Pp @@ -669,12 +687,19 @@ parser: Messages displayed by .Nm follow this format: -.Pp -.D1 Nm Ns : Ar file : Ns Ar line : Ns Ar column : level : message : macro args +.Bd -ragged -offset indent +.Nm Ns : +.Ar file : Ns Ar line : Ns Ar column : level : message : macro args +.Pq Ar os +.Ed .Pp Line and column numbers start at 1. Both are omitted for messages referring to an input file as a whole. Macro names and arguments are omitted where meaningless. +The +.Ar os +operating system specifier is omitted for messages that are relevant +for all operating systems. Fatal messages about invalid command line arguments or operating system errors, for example when memory is exhausted, may also omit the @@ -732,9 +757,15 @@ 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. +.It Cm base +A convertion used in the base system of a specific operating system +is not adhered to. +These are not markup mistakes, and neither the quality of formatting +nor portability are in danger. .El .Pp Messages of the +.Cm base , .Cm style , .Cm warning , .Cm error , @@ -746,9 +777,15 @@ are hidden unless their level, or a lower level, is requested using a 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 +.Pp +As indicated below, all +.Cm base +and some +.Cm style +checks are only performed if a specific operating system name occurs +in the arguments of the +.Fl W +command line option, of the .Ic \&Os macro, of the .Fl Ios @@ -756,6 +793,7 @@ command line option, or, if neither are present, in the return value of the .Xr uname 3 function. +.Ss Conventions for base system manuals .Bl -ohang .It Sy "Mdocdate found" .Pq mdoc , Nx @@ -778,6 +816,17 @@ macro does not use CVS keyword substitution, but using it is conventionally expected in the .Ox base system. +.It Sy "RCS id missing" +.Pq Ox , Nx +The manual page lacks the comment line with the RCS identifier +generated by CVS +.Ic OpenBSD +or +.Ic NetBSD +keyword substitution as conventionally used in these operating systems. +.El +.Ss Style suggestions +.Bl -ohang .It Sy "legacy man(7) date format" .Pq mdoc The @@ -791,14 +840,6 @@ Consider using the conventional date format .Dq "Month dd, yyyy" instead. -.It Sy "RCS id missing" -.Pq Ox , Nx -The manual page lacks the comment line with the RCS identifier -generated by CVS -.Ic OpenBSD -or -.Ic NetBSD -keyword substitution as conventionally used in these operating systems. .It Sy "duplicate RCS id" A single manual page contains two copies of the RCS identifier for the same operating system. |