mandoc/mandoc.1 - diff

Return to mandoc.1 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mandoc.1 between version 1.199 and 1.210

version 1.199, 2017/06/13 15:06:56

version 1.210, 2017/07/01 09:47:30

Line 75 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

Line 151 to be reported on the standard error output and to aff

Line 146 to be reported on the standard error output and to aff

The

.Ar level

can be

.Cm base ,

.Cm style ,

.Cm warning ,

.Cm error ,

.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.

Line 224 See

Line 238 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.

Line 596 option:

Line 610 option:

.Pp

.Bl -tag -width Ds -compact

.It 0

No style suggestions, warnings or errors occurred, or those that

No base system convention violations, style suggestions, warnings,

did were ignored because they were lower than the requested

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

.Fl W Cm style

was specified.

.It 2

At least one warning occurred, but no error, and

.Fl W Cm warning

or a lower

.Fl W Cm style

.Ar level

was specified.

was requested.

.It 3

At least one parsing error occurred,

but no unsupported feature was encountered, and

Line 636 to exit at once, possibly in the middle of parsing or

Line 654 to exit at once, possibly in the middle of parsing or

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

Line 669 parser:

Line 687 parser:

Messages displayed by

.Nm

follow this format:

.Bd -ragged -offset indent

.Nm :

.Ar file : Ns Ar line : Ns Ar column : level : message : macro args

.Pq Ar os

.Ed

.Pp

.D1 Nm Ns : Ar file : Ns Ar line : Ns Ar column : level : message : macro args

.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

Line 732 so it may occasionally issue bogus suggestions.

Line 757 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 ,

Line 746 are hidden unless their level, or a lower level, is re

Line 777 are hidden unless their level, or a lower level, is re

option or

.Fl T Cm lint

output mode.

.Ss Style messages

.Pp

As indicated below, some style checks are only performed if a

As indicated below, all

specific operating system name occurs in the arguments of the

.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

Line 756 command line option, or, if neither are present, in th

Line 793 command line option, or, if neither are present, in th

of the

.Xr uname 3

function.

.Ss Conventions for base system manuals

.Bl -ohang

.It Sy "Mdocdate found"

.Pq mdoc , Nx

The

.Ic \&Dd

macro uses CVS

.Ic Mdocdate

keyword substitution, which is not supported by the

.Nx

base system.

Consider using the conventional

.Dq "Month dd, yyyy"

format instead.

.It Sy "Mdocdate missing"

.Pq mdoc , Ox

The

.Ic \&Dd

macro does not use CVS

.Ic Mdocdate

keyword substitution, but using it is conventionally expected in the

.Ox

base system.

.It Sy "unknown architecture"

.Pq mdoc , Ox , Nx

The third argument of the

.Ic \&Dt

macro does not match any of the architectures this operating system

is running on.

.It Sy "operating system explicitly specified"

.Pq mdoc , Ox , Nx

The

.Ic \&Os

macro has an argument.

In the base system, it is conventionally left blank.

.It Sy "RCS id missing"

.Pq Ox , Nx

The manual page lacks the comment line with the RCS identifier

generated by CVS

.Ic OpenBSD

.Ic NetBSD

keyword substitution as conventionally used in these operating systems.

.It Sy "referenced manual not found"

.Pq mdoc

.Ic \&Xr

macro references a manual page that is not found in the base system.

The path to look for base system manuals is configurable at compile

time and defaults to

.Pa /usr/share/man : /usr/X11R6/man .

.El

.Ss Style suggestions

.Bl -ohang

.It Sy "legacy man(7) date format"

.Pq mdoc

The

.Ic \&Dd

macro uses the legacy

.Xr man 7

date format

.Dq yyyy-dd-mm .

Consider using the conventional

.Xr mdoc 7

date format

.Dq "Month dd, yyyy"

instead.

.It Sy "duplicate RCS id"

A single manual page contains two copies of the RCS identifier for

the same operating system.

Consider deleting the later instance and moving the first one up

to the top of the page.

.It Sy "typo in section name"

.Pq mdoc

Fuzzy string matching revealed that the argument of an

.Ic \&Sh

macro is similar, but not identical to a standard section name.

.It Sy "useless macro"

.Pq mdoc

Line 1070 The paragraph macro is moved after the end of the list

Line 1183 The paragraph macro is moved after the end of the list

.Pq mdoc

An input line begins with an

.Ic \&Ns

macro.

macro, or the next argument after an

.Ic \&Ns

macro is an isolated closing delimiter.

The macro is ignored.

.It Sy "blocks badly nested"

.Pq mdoc

Line 1111 list block contains text or macros before the first

Line 1226 list block contains text or macros before the first

.Ic \&It

macro.

The offending children are moved before the beginning of the list.

.It Sy "first macro on line"

Inside a

.Ic \&Bl Fl column

list, a

.Ic \&Ta

macro occurs as the first macro on a line, which is not portable.

.It Sy "fill mode already enabled, skipping"

.Pq man

Line 1178 A

Line 1299 A

.Ic \&Bl ,

.Ic \&D1 ,

.Ic \&Dl ,

.Ic \&MT ,

.Ic \&RS ,

.Ic \&UR

Line 1255 list, an

Line 1377 list, an

.Ic \&It

block is empty.

An empty list item is shown.

.It Sy "missing argument, using next line"

.Pq mdoc

.Ic \&It

macro in a

.Ic \&Bd Fl column

list has no arguments.

While

.Nm

uses the text or macros of the following line, if any, for the cell,

other formatters may misformat the list.

.It Sy "missing font type, using \efR"

.Pq mdoc

Line 1313 An empty pair of square brackets is shown.

Line 1446 An empty pair of square brackets is shown.

.It Sy "missing resource identifier, using \(dq\(dq"

.Pq man

The

.Ic \&MT

.Ic \&UR

macro is invoked without any argument.

An empty pair of angle brackets is shown.

Line 1665 An

Line 1800 An

.Xr mdoc 7

block closing macro, a

.Xr man 7

.Ic \&RE

.Ic \&ME , \&RE

.Ic \&UE

macro, an

Line 1699 At the end of the document, an explicit

Line 1834 At the end of the document, an explicit

block, a

.Xr man 7

next-line scope or

.Ic \&RS

.Ic \&MT , \&RS

.Ic \&UR

block, an equation, table, or

Line 1871 A macro or request is invoked with too many arguments:

Line 2006 A macro or request is invoked with too many arguments:

.Bl -dash -offset 2n -width 2n -compact

.It

.Ic \&Fo ,

.Ic \&MT ,

.Ic \&PD ,

.Ic \&RS ,

.Ic \&UR ,

CVSweb