mandoc/mandoc.1 - diff

Return to mandoc.1 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mandoc.1 between version 1.51 and 1.59

version 1.51, 2010/03/22 14:03:03

version 1.59, 2010/04/13 05:26:49

Line 1

.\" $Id$

.\"

.\" Permission to use, copy, modify, and distribute this software for any

.\" purpose with or without fee is hereby granted, provided that the above

Line 17

.Dd $Mdocdate$

.Dt MANDOC 1

.Os

.Sh NAME

.Nm mandoc

.Nd format and display UNIX manuals

.Sh SYNOPSIS

.Nm mandoc

.Op Fl f Ns Ar option...

.Op Fl V

.Op Fl f Ns Ar option

.Op Fl m Ns Ar format

.Op Fl O Ns Ar option...

.Op Fl O Ns Ar option

.Op Fl T Ns Ar output

.Op Fl V

.Op Fl W Ns Ar err

.Op Fl W Ns Ar err...

.Op Ar file...

.Op Ar infile...

.Sh DESCRIPTION

The

.Nm

utility formats

.Ux

manual pages for display. The arguments are as follows:

manual pages for display.

The arguments are as follows:

.Bl -tag -width Ds

.It Fl f Ns Ar option...

.It Fl f Ns Ar option

Comma-separated compiler options. See

Comma-separated compiler options.

See

.Sx Compiler Options

for details.

.It Fl m Ns Ar format

Input format. See

Input format.

See

.Sx Input Formats

for available formats. Defaults to

for available formats.

.Fl m Ns Ar andoc .

Defaults to

.Fl m Ns Cm andoc .

.It Fl O Ns Ar option...

.It Fl O Ns Ar option

Comma-separated output options. See

Comma-separated output options.

See

.Sx Output Options

for details.

.It Fl T Ns Ar output

Output format. See

Output format.

See

.Sx Output Formats

for available formats. Defaults to

for available formats.

.Fl T Ns Ar ascii .

Defaults to

.Fl T Ns Cm ascii .

.It Fl V

Print version and exit.

.It Fl W Ns Ar err

.It Fl W Ns Ar err...

Comma-separated warning options.

Comma-separated warning options. Use

Use

.Fl W Ns Ar all

.Fl W Ns Cm all

to print warnings,

.Fl W Ns Ar error

.Fl W Ns Cm error

for warnings to be considered errors and cause utility

termination. Multiple

termination.

Multiple

.Fl W

arguments may be comma-separated, such as

.Fl W Ns Ar error,all .

.Fl W Ns Cm error , Ns Cm all .

.It Ar file

.It Ar infile...

Read input from zero or more files.

Read input from zero or more

If unspecified, reads from stdin.

.Ar infile .

If multiple files are specified,

If unspecified, reads from stdin. If multiple files are specified,

.Nm

will halt with the first failed parse.

.El

.Pp

By default,

.Nm

Line 95 reads

Line 90 reads

.Xr man 7

text from stdin, implying

.Fl m Ns Ar andoc ,

.Fl m Ns Cm andoc ,

and produces

.Fl T Ns Ar ascii

.Fl T Ns Cm ascii

output.

.Pp

.Ex -std mandoc

.Ss Input Formats

The

.Nm

Line 112 utility accepts

Line 104 utility accepts

and

.Xr man 7

input with

.Fl m Ns Ar doc

.Fl m Ns Cm doc

and

.Fl m Ns Ar an ,

.Fl m Ns Cm an ,

respectively. The

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 ,

.Fl m Ns Cm andoc ,

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

non-comment macro is

.Sq \&Dd

Line 136 the

Line 128 the

parser is used; otherwise, the

.Xr man 7

parser is used.

.Pp

If multiple

files are specified with

.Fl m Ns Ar andoc ,

.Fl m Ns Cm andoc ,

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

each has its file-type determined this way.

If multiple files are

specified and

.Fl m Ns Ar doc

.Fl m Ns Cm doc

.Fl m Ns Ar an

.Fl m Ns Cm an

is specified, then this format is used exclusively.

.Ss Output Formats

The

.Nm

Line 156 utility accepts the following

Line 146 utility accepts the following

.Fl T

arguments (see

.Sx OUTPUT ) :

.Bl -tag -width Ds

.It Fl T Ns Ar ascii

.It Fl T Ns Cm ascii

Produce 7-bit ASCII output, backspace-encoded for bold and underline

styles. This is the default. See

styles.

This is the default.

See

.Sx ASCII Output .

.It Fl T Ns Cm html

.It Fl T Ns Ar html

Produce strict HTML-4.01 output, with a sane default style.

Produce strict HTML-4.01 output, with a sane default style. See

See

.Sx HTML Output .

.It Fl T Ns Cm lint

.It Fl T Ns Ar xhtml

Produce strict XHTML-1.0 output, with a sane default style. See

.Sx XHTML Output .

.It Fl T Ns Ar tree

Produce an indented parse tree.

.It Fl T Ns Ar lint

Parse only: produce no output.

Implies

.Fl W Ns Cm all

and

.Fl f Ns Cm strict .

.It Fl T Ns Cm tree

Produce an indented parse tree.

.It Fl T Ns Cm xhtml

Produce strict XHTML-1.0 output, with a sane default style.

See

.Sx XHTML Output .

.El

.Pp

If multiple input files are specified, these will be processed by the

corresponding filter in-order.

.Ss Compiler Options

Default compiler behaviour may be overridden with the

.Fl f

flag.

.Bl -tag -width Ds

.It Fl f Ns Ar ign-scope

.It Fl f Ns Cm ign-errors

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

When parsing multiple files, don't halt when one errors out.

scope violations. This can seriously mangle the resulting tree.

Useful with

.Pq mdoc only

.Fl T Ns Cm lint

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

.It Fl f Ns Ar ign-escape

.It Fl f Ns Cm ign-escape

Ignore invalid escape sequences.

This is the default, but the option can be used to override an earlier

.Fl f Ns Ar strict .

.Fl f Ns Cm strict .

.It Fl f Ns Cm ign-scope

.It Fl f Ns Ar no-ign-escape

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

Don't ignore invalid escape sequences.

scope violations.

This can seriously mangle the resulting tree.

.It Fl f Ns Ar no-ign-macro

.Pq mdoc only

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

.It Fl f Ns Cm no-ign-chars

.It Fl f Ns Ar no-ign-chars

Do not ignore disallowed characters.

.It Fl f Ns Cm no-ign-escape

.It Fl f Ns Ar strict

Do not ignore invalid escape sequences.

.It Fl f Ns Cm no-ign-macro

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

.It Fl f Ns Cm strict

Implies

.Fl f Ns Ar no-ign-escape ,

.Fl f Ns Cm no-ign-escape ,

.Fl f Ns Ar no-ign-macro

.Fl f Ns Cm no-ign-macro ,

and

.Fl f Ns Ar no-ign-chars .

.Fl f Ns Cm 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

.Ss Output Options

For the time being, only

.Fl T Ns Ar html

accepts output options:

and

.Fl T Ns Ar xhtml

accept output options:

.Bl -tag -width Ds

.It Fl O Ns Ar style=style.css

.It Fl O Ns Cm includes Ns = Ns Ar fmt

The file

.Ar style.css

is used for an external style-sheet. This must be a valid absolute or

relative URI.

.It Fl O Ns Ar includes=fmt

The string

.Ar fmt ,

for example,

.Ar ../src/%I.html ,

is used as a template for linked header files (usually via the

.Sq \&In

macro). Instances of

macro).

Instances of

.Sq \&%I

are replaced with the include filename. The default is not to present a

are replaced with the include filename.

The default is not to present a

hyperlink.

.It Fl O Ns Ar man=fmt

.It Fl O Ns Cm man Ns = Ns Ar fmt

The string

.Ar fmt ,

for example,

.Ar ../html%S/%N.%S.html ,

is used as a template for linked manuals (usually via the

.Sq \&Xr

macro). Instances of

macro).

Instances of

.Sq \&%N

and

.Sq %S

are replaced with the linked manual's name and section, respectively.

If no section is included, section 1 is assumed. The default is not to

If no section is included, section 1 is assumed.

The default is not to

present a hyperlink.

.It Fl O Ns Cm style Ns = Ns Ar style.css

The file

.Ar style.css

is used for an external style-sheet.

This must be a valid absolute or

relative URI.

.El

.Sh OUTPUT

This section documents output details of

.Nm .

Line 269 a body composed of sections and sub-sections, and a fo

Line 257 a body composed of sections and sub-sections, and a fo

The text style of output characters (non-macro characters, punctuation,

and white-space) is dictated by context.

.Pp

White-space is generally stripped from input. This can be changed with

White-space is generally stripped from input.

This can be changed with

character escapes (specified in

.Xr mandoc_char 7 )

or literal modes (specified in

Line 303 and

Line 292 and

.Sq \&}

.Pc

is not preceded by white-space.

.Pp

If the input is

.Xr mdoc 7 ,

however, these rules are also applied to macro arguments when appropriate.

.Ss ASCII Output

Output produced by

.Fl T Ns Ar ascii ,

.Fl T Ns Cm ascii ,

which is the default, is rendered in standard 7-bit ASCII documented in

.Xr ascii 7 .

.Pp

Line 323 is rendered as

Line 309 is rendered as

.Sq _ Ns \e[bs] Ns c ,

where

.Sq \e[bs]

is the back-space character number 8. Emboldened characters are rendered as

is the back-space character number 8.

Emboldened characters are rendered as

.Sq c Ns \e[bs] Ns c .

.Pp

The special characters documented in

Line 332 are rendered best-effort in an ASCII equivalent.

Line 319 are rendered best-effort in an ASCII equivalent.

.Pp

Output width is limited to 78 visible columns unless literal input lines

exceed this limit.

.Ss HTML Output

Output produced by

.Fl T Ns Ar html

.Fl T Ns Cm html

conforms to HTML-4.01 strict.

.Pp

Font styles and page structure are applied using CSS2. By default, no

Font styles and page structure are applied using CSS2.

font style is applied to any text, although CSS2 is hard-coded to format

By default, no font style is applied to any text,

although CSS2 is hard-coded to format

the basic structure of output.

.Pp

The

.Pa example.style.css

file documents the range of styles applied to output and, if used, will

cause rendered documents to appear as they do in

.Fl T Ns Ar ascii .

.Fl T Ns Cm ascii .

.Pp

Special characters are rendered in decimal-encoded UTF-8.

.Ss XHTML Output

Output produced by

.Fl T Ns Ar xhtml

.Fl T Ns Cm xhtml

conforms to XHTML-1.0 strict.

.Pp

See

.Sx HTML Output

for details; beyond generating XHTML tags instead of HTML tags, these

output modes are identical.

.Sh EXAMPLES

To page manuals to the terminal:

.Pp

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

.D1 $ mandoc \-Wall,error \-fstrict mandoc.1 2\*(Gt&1 | less

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

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

.Pp

To produce HTML manuals with

.Ar style.css

as the style-sheet:

.Pp

.D1 % mandoc \-Thtml -Ostyle=style.css mdoc.7 > mdoc.7.html

.D1 $ mandoc \-Thtml -Ostyle=style.css mdoc.7 \*(Gt mdoc.7.html

.Pp

To check over a large set of manuals:

.Pp

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

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

.Sh COMPATIBILITY

This section summarises

.Nm

compatibility with

.Xr groff 1 .

Each input and output format is separately noted.

.Ss ASCII Compatibility

.Bl -bullet -compact

.It

The

.Sq \e~

special character doesn't produce expected behaviour in

.Fl T Ns Ar ascii .

.Fl T Ns Cm ascii .

.It

The

.Sq \&Bd \-literal

Line 407 and

Line 381 and

macros of

.Xr mdoc 7

.Fl T Ns Ar ascii

.Fl T Ns Cm ascii

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

.It

.Xr groff 1 ,

Line 418 the

Line 391 the

.Xr mdoc 7

macro does not underline when scoped under an

.Sq \&It

in the FILES section. This behaves correctly in

in the FILES section.

This behaves correctly in

.Nm .

.It

A list or display following

A list or display following the

.Sq \&Ss

.Xr mdoc 7

macro in

.Fl T Ns Ar ascii

.Fl T Ns Cm ascii

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

.Sq \&Sh .

.It

The

.Sq \&na

.Xr man 7

macro in

.Fl T Ns Ar ascii

.Fl T Ns Cm ascii

has no effect.

.It

Words aren't hyphenated.

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

.Xr groff 1

retains spaces.

.It

Sentences are unilaterally monospaced.

.El

.Ss HTML/XHTML Compatibility

.Bl -bullet -compact

.It

Line 460 The

Line 427 The

escape will revert the font to the previous

.Sq \ef

escape, not to the last rendered decoration, which is now dictated by

CSS instead of hard-coded. It also will not span past the current

CSS instead of hard-coded.

scope, for the same reason. Note that in

It also will not span past the current scope,

for the same reason.

Note that in

.Sx ASCII Output

mode, this will work fine.

.It

Line 472 and

Line 441 and

.Sq \&Bl \-tag

list types render similarly (no break following overreached left-hand

side) due to the expressive constraints of HTML.

.It

The

.Xr man 7

Line 481 and

Line 449 and

.Sq TP

lists render similarly.

.El

.Sh SEE ALSO

.Xr man 7 ,

.Xr mandoc_char 7 ,

.Xr mdoc 7 ,

.Xr mdoc 7

.Xr man 7

.Sh AUTHORS

The

.Nm

utility was written by

.An Kristaps Dzonsons Aq kristaps@kth.se .

.An Kristaps Dzonsons Aq kristaps@bsd.lv .

.Sh CAVEATS

The

.Fl T Ns Ar html

.Fl T Ns Cm html

and

.Fl T Ns Ar xhtml

.Fl T Ns Cm xhtml

CSS2 styling used for

.Fl m Ns Ar doc

.Fl m Ns Cm doc

input lists does not render properly in older browsers, such as Internet

Explorer 6 and earlier.

.Pp

.Fl T Ns Ar html

.Fl T Ns Cm html

and

.Fl T Ns Ar xhtml ,

.Fl T Ns Cm xhtml ,

the maximum size of an element attribute is determined by

.Dv BUFSIZ ,

which is usually 1024 bytes. Be aware of this when setting long link

which is usually 1024 bytes.

formats, e.g.,

Be aware of this when setting long link

.Fl O Ns Ar style=really/long/link .

formats such as

.Fl O Ns Cm style Ns = Ns Ar really/long/link .

.Pp

The

.Fl T Ns Ar html

.Fl T Ns Cm html

and

.Fl T Ns Ar xhtml

.Fl T Ns Cm xhtml

output modes don't render the

.Sq \es

font size escape documented in

Line 527 and

Line 491 and

.Xr man 7 .

.Pp

Nesting elements within next-line element scopes of

.Fl m Ar Ns an ,

.Fl m Ns Cm an ,

such as

.Sq br

within an empty

.Sq B ,

will confuse

.Fl T Ns Ar html

.Fl T Ns Cm html

and

.Fl T Ns Ar xhtml

.Fl T Ns Cm xhtml

and cause it to forget the formatting.

and cause them to forget the formatting of the prior next-line scope.

.Pp

The

.Sq i

macro in

.Fl m Ns Cm an

should italicise all subsequent text if a line argument is not provided.

This behaviour is not implemented.

The

.Sq \(aq

control character is an alias for the standard macro control character

and does not emit a line-break as stipulated in GNU troff.

CVSweb