mandoc/mandoc.1 - diff

Return to mandoc.1 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mandoc.1 between version 1.180 and 1.200

version 1.180, 2017/03/20 14:32:24

version 1.200, 2017/06/17 22:43:14

Line 20

.Os

.Sh NAME

.Nm mandoc

.Nd format and display UNIX manuals

.Nd format manual pages

.Sh SYNOPSIS

.Nm mandoc

.Op Fl acfhkl

.Op Fl ac

.Op Fl I Cm os Ns = Ns Ar name

.Op Fl K Ar encoding

.Op Fl mdoc | man

.Op Fl O Ar option

.Op Fl O Ar options

.Op Fl T Ar output

.Op Fl W Ar level

.Op Ar

Line 65 to paginate them.

This is the default.

It can be specified to override

.Fl a .

.It Fl f

A synonym for

.Xr whatis 1 .

This overrides any earlier

.Fl k

and

.Fl l

options.

.It Fl h

Display only the SYNOPSIS lines.

Implies

.Fl c .

.It Fl I Cm os Ns = Ns Ar name

Override the default operating system

.Ar name

Line 87 and for the

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 120 sequence, input is interpreted as

Line 113 sequence, input is interpreted as

Otherwise, input is interpreted as

.Cm iso-8859-1 .

.El

.It Fl k

A synonym for

.Xr apropos 1 .

This overrides any earlier

.Fl f

and

.Fl l

options.

.It Fl l

A synonym for

.Fl a .

Also reverts any earlier

.Fl f

and

.Fl k

options.

.It Fl mdoc | man

With

.Fl mdoc ,

Line 158 parser is used.

Line 135 parser is used.

With other arguments,

.Fl m

is silently ignored.

.It Fl O Ar option

.It Fl O Ar options

Comma-separated output options.

.It Fl T Ar output

Output format.

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

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

The

.Ar level

can be

.Cm style ,

.Cm warning ,

.Cm error ,

.Cm unsupp ;

.Cm all

is an alias for

.Cm warning .

.Cm style .

By default,

.Nm

is silent.

Line 211 If multiple files are specified,

Line 189 If multiple files are specified,

will halt with the first failed parse.

.El

.Pp

The options

.Fl fhklw

are also supported and are documented in man(1).

.Fl f

and

Line 218 and

Line 199 and

mode,

.Nm

also supports the options

.Fl CMmOSsw

.Fl CMmOSs

described in the

.Xr apropos 1

manual.

The options

.Fl fkl

are mutually exclusive and override each other.

.Ss Output Formats

The

.Nm

Line 240 See

Line 224 See

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

Line 274 See

Line 258 See

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

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

Line 301 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 616 option:

Line 596 option:

.Pp

.Bl -tag -width Ds -compact

.It 0

No warnings or errors occurred, or those that did were ignored because

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

they were lower than the requested

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

.Fl W Cm style

was specified.

.It 2

At least one warning occurred, but no error, and

.Fl W Cm warning

.Fl W Cm style

was specified.

.It 3

At least one parsing error occurred,

but no unsupported feature was encountered, and

.Fl W Cm error

or a lower

.Fl W Cm warning

.Ar level

was specified.

was requested.

.It 4

At least one unsupported feature was encountered, and

.Fl W Cm unsupp ,

.Fl W Cm unsupp

.Fl W Cm error

or a lower

.Ar level

.Fl W Cm warning

was requested.

was specified.

.It 5

Invalid command line arguments were specified.

No input files have been read.

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

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

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

.Dl $ mandoc \-W all,stop mandoc.1 2\*(Gt&1 | less

.Dl $ mandoc -l mandoc.1 man.1 apropos.1 makewhatis.8

.Dl $ mandoc mandoc.1 mdoc.3 mdoc.7 | less

.Pp

To produce HTML manuals with

.Pa mandoc.css

Line 736 rendering can be produced.

Line 720 rendering can be produced.

Documents causing warnings may render poorly when using other

formatting tools instead of

.Nm .

.It Cm style

An input file uses dubious or discouraged style.

This is not a complaint about the syntax, and probably neither

formatting nor portability are in danger.

While great care is taken to avoid false positives on the higher

message levels, the

.Cm style

level tries to reduce the probability that issues go unnoticed,

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.

.El

.Pp

Messages of the

.Cm style ,

.Cm warning ,

.Cm error ,

and

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

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

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 "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 "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 "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 "useless macro"

.Pq mdoc

.Ic \&Bt ,

.Ic \&Tn ,

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

.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

.It Sy "missing manual title, using UNTITLED"

Line 1127 or

Line 1232 or

.Ic \&Bl

.Fl offset

.Fl width.

.Fl width .

.It Sy "missing display type, using -ragged"

.Pq mdoc

The

Line 1349 or

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

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

CVSweb