mandoc/mandoc.1 - diff

Return to mandoc.1 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mandoc.1 between version 1.193 and 1.208

version 1.193, 2017/06/03 12:17:25

version 1.208, 2017/06/27 12:18:00

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 219 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 296 Increasing this is not recommended; it may result in d

Line 315 Increasing this is not recommended; it may result in d

for example overfull lines or ugly line breaks.

.It Cm width Ns = Ns Ar width

The output width is set to

.Ar width ,

.Ar width .

which will normalise to \(>=58.

.El

.Ss HTML Output

Output produced by

Line 592 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 632 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 665 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 728 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 742 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, 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

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

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.

.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 763 macro that could be represented using

Line 881 macro that could be represented using

.Ic \&Fx ,

.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

.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

.Ic \&Xr

macro.

.El

.Ss Warnings related to the document prologue

.Bl -ohang

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

Line 1175 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 1135 A

Line 1285 A

.Ic \&Bl ,

.Ic \&D1 ,

.Ic \&Dl ,

.Ic \&MT ,

.Ic \&RS ,

.Ic \&UR

Line 1270 An empty pair of square brackets is shown.

Line 1421 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 1369 or

Line 1522 or

.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

.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

Line 1616 An

Line 1775 An

.Xr mdoc 7

block closing macro, a

.Xr man 7

.Ic \&RE

.Ic \&ME , \&RE

.Ic \&UE

macro, an

Line 1650 At the end of the document, an explicit

Line 1809 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 1716 whatever mode was active before the block.

Line 1875 whatever mode was active before the block.

.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

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

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