mandoc/mandoc.1 - diff

Return to mandoc.1 CVS log

Up to [cvsweb.bsd.lv] / mandoc

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

version 1.196, 2017/06/08 00:23:30

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

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 301 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 597 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 637 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 670 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 733 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 747 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 757 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.

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

Line 902 number.

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 1057 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 1165 A

Line 1285 A

.Ic \&Bl ,

.Ic \&D1 ,

.Ic \&Dl ,

.Ic \&MT ,

.Ic \&RS ,

.Ic \&UR

Line 1300 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 1652 An

Line 1775 An

.Xr mdoc 7

block closing macro, a

.Xr man 7

.Ic \&RE

.Ic \&ME , \&RE

.Ic \&UE

macro, an

Line 1686 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 1858 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