mandoc/mandoc.1 - diff

Return to mandoc.1 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mandoc.1 between version 1.19 and 1.30

version 1.19, 2009/06/15 09:35:16

version 1.30, 2009/08/19 09:14:50

Line 34

.Sh DESCRIPTION

The

.Nm

utility formats

.Ux

manual pages for display. The arguments are as follows:

.Bl -tag -width Ds

.\" ITEM

.It Fl f Ns Ar option...

Override default compiler behaviour. See

.Sx Compiler Options

for details.

.\" ITEM

Line 60 for available formats. Defaults to

Print version and exit.

.\" ITEM

.It Fl W Ns Ar err...

Print warning messages. May be set to

Configure warning messages. Use

.Fl W Ns Ar all

for all warnings,

to print warnings,

.Ar compat

.Fl W Ns Ar error

for groff/troff-compatibility warnings, or

for warnings to be considered errors and cause utility

.Ar syntax

termination. Multiple

for syntax warnings. If

.Fl W Ns Ar error

is specified, warnings are considered errors and cause utility

termination. Multiple

.Fl W

arguments may be comma-separated, such as

.Fl W Ns Ar error,all .

Line 83 will halt with the first failed parse.

Line 79 will halt with the first failed parse.

.El

.\" PARAGRAPH

.Pp

By default,

.Nm

reads

.Xr mdoc 7

.Xr man 7

Line 98 were provided.

Line 94 were provided.

.Pp

.Ex -std mandoc

.\" SUB-SECTION

.Ss Punctuation

.Ss Punctuation and Spacing

If punctuation is set apart from words, such as in the phrase

.Dq to be \&, or not to be ,

it's processed by

.Nm

according to the following rules. Opening punctuation

according to the following rules: opening punctuation

.Po

.Sq \&( ,

.Sq \&[ ,

and

.Sq \&{

.Pc

is not followed by a space. Closing punctuation

is not followed by a space; closing punctuation

.Po

.Sq \&. ,

.Sq \&, ,

.Sq \&; ,

.Sq \&: ,

.Sq \&? ,

.Sq \&! ,

.Sq \&) ,

.Sq \&]

and

.Sq \&}

.Pc

is not preceded by whitespace.

.Pp

If the input is

.Xr mdoc 7 ,

these rules are also applied to macro arguments when appropriate.

.Pp

White-space, in non-literal (normal) mode, is stripped from input and

replaced on output by a single space. Thus, if you wish to preserve

multiple spaces, they must be space-escaped

.Sq \e\

or used in a literal display mode, e.g.,

.Sq \&Bd \-literal

.Xr mdoc 7 .

.\" SUB-SECTION

.Ss Input Formats

The

Line 144 respectively. The

Line 149 respectively. The

.Xr mdoc 7

format is

.Em strongly

recommended;

.Xr man 7

should only be used for legacy manuals.

.Pp

A third option,

.Fl m Ns Ar andoc ,

which is also the default, determines encoding on-the-fly: if the first

non-comment macro is

.Sq \&.Dd

.Sq \&Dd

.Sq \&.Dt ,

.Sq \&Dt ,

the

.Xr mdoc 7

parser is used; otherwise, the

.Xr man 7

parser is used.

.Pp

If multiple

files are specified with

.Fl m Ns Ar andoc ,

each has its file-type determined this way. If multiple files are

specified and

.Fl m Ns Ar doc

Line 210 flag.

Line 215 flag.

When rewinding the scope of a block macro, forces the compiler to ignore

scope violations. This can seriously mangle the resulting tree.

.Pq mdoc only

.It Fl f Ns Ar ign-escape

.It Fl f Ns Ar no-ign-escape

Ignore invalid escape sequences.

Don't ignore invalid escape sequences.

.It Fl f Ns Ar ign-macro

Ignore unknown macros at the start of input lines (default for

.Xr man 7

parsing).

.It Fl f Ns Ar no-ign-macro

Do not ignore unknown macros at the start of input lines (default for

Do not ignore unknown macros at the start of input lines.

.Xr mdoc 7

.It Fl f Ns Ar no-ign-chars

parsing).

Do not ignore disallowed characters.

.It Fl f Ns Ar strict

Implies

.Fl f Ns Ar no-ign-escape ,

.Fl f Ns Ar no-ign-macro

and

.Fl f Ns Ar no-ign-chars .

.It Fl f Ns Ar ign-errors

Don't halt when encountering parse errors. Useful with

.Fl T Ns Ar lint

over a large set of manuals passed on the command line.

.El

.\" PARAGRAPH

.Pp

Line 228 As with the

Line 239 As with the

flag, multiple

.Fl f

options may be grouped and delimited with a comma. Using

.Fl f Ns Ar ign-scope,ign-escape ,

.Fl f Ns Ar ign-scope,no-ign-escape ,

for example, will try to ignore scope and character-escape errors.

for example, will try to ignore scope and not ignore character-escape

errors.

.\" SECTION

.Sh EXAMPLES

To page manuals to the terminal:

.\" PARAGRAPH

.Pp

.D1 % mandoc \-Wall,error mandoc.1 2>&1 | less

.D1 % mandoc \-Wall,error \-fstrict mandoc.1 2>&1 | less

.Pp

.D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less

.\" PARAGRAPH

.Pp

To check over a large set of manuals:

.\" PARAGRAPH

.Pp

.Dl % mandoc \-Tlint \-fign-errors `find /usr/src -name \e*\e.[1-9]`

.\" SECTION

.Sh SEE ALSO

.Sh COMPATIBILITY

.Xr mandoc_char 7 ,

This section summarises

.Xr mdoc 7 ,

.Xr man 7

.\"

.Sh AUTHORS

The

.Nm

utility was written by

compatibility with

.An Kristaps Dzonsons Aq kristaps@kth.se .

.Xr groff 1 .

.\" SECTION

.Sh CAVEATS

The

.Nm

utility in

.Fl T Ns Ar ascii

mode doesn't yet know how to display the following:

.Pp

.Bl -bullet -compact

.\" LIST-ITEM

.It

The \-hang

The

.Sq \&.Bl

.Sq \e~

list is not yet supported.

special character doesn't produce expected behaviour.

.El

.\" LIST-ITEM

.Pp

Other macros still aren't supported by virtue of nobody complaining

about their absence. Please report any omissions: this is a work in

progress.

.Pp

The following list documents differences between traditional

.Xr nroff 1

output and

.Nm :

.Pp

.Bl -bullet -compact

.It

A list of display following

.Sq \&.Ss

does not assert a prior vertical break, just as it doesn't with

.Sq \&.Sh .

.It

Special characters don't follow the current font style.

.Xr groff 1 ,

the

.Sq \&Pa

macro does not underline when under a

.Sq \&It

in the FILES section. This behaves correctly in

.Nm .

.\" LIST-ITEM

.It

The \-literal and \-unfilled

A list or display following

.Sq \&.Bd

.Sq \&Ss

does not assert a prior vertical break, just as it doesn't with

.Sq \&Sh .

.It

The \-literal and \-unfilled

.Sq \&Bd

displays types are synonyms, as are \-filled and \-ragged.

.\" LIST-ITEM

.It

Words aren't hyphenated.

.\" LIST-ITEM

.It

In normal mode (not a literal block), blocks of spaces aren't preserved,

so double spaces following sentence closure are reduced to a single space.

.El

.\" SECTION

.Sh SEE ALSO

.Xr mandoc_char 7 ,

.Xr mdoc 7 ,

.Xr man 7

.\" SECTION

.Sh AUTHORS

The

.Nm

utility was written by

.An Kristaps Dzonsons Aq kristaps@kth.se .

CVSweb