mandoc/mandoc.1 - diff

Return to mandoc.1 CVS log

Up to [cvsweb.bsd.lv] / mandoc

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

version 1.58, 2010/04/12 19:27:22

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 V

Line 33

Line 29

.Op Fl T Ns Ar output

.Op Fl W Ns Ar err

.Op Ar file...

.Sh DESCRIPTION

The

.Nm

Line 42 utility formats

Line 36 utility formats

.Ux

manual pages for display.

The arguments are as follows:

.Bl -tag -width Ds

.It Fl f Ns Ar option

Comma-separated compiler options.

See

.Sx Compiler Options

for details.

.It Fl m Ns Ar format

Input format.

See

Line 57 See

Line 49 See

for available formats.

Defaults to

.Fl m Ns Cm andoc .

.It Fl O Ns Ar option

Comma-separated output options.

See

.Sx Output Options

for details.

.It Fl T Ns Ar output

Output format.

See

Line 71 See

Line 61 See

for available formats.

Defaults to

.Fl T Ns Cm ascii .

.It Fl V

Print version and exit.

.It Fl W Ns Ar err

Comma-separated warning options.

Use

Line 87 Multiple

Line 75 Multiple

.Fl W

arguments may be comma-separated, such as

.Fl W Ns Cm error , Ns Cm all .

.It Ar file

Read input from zero or more files.

If unspecified, reads from stdin.

Line 95 If multiple files are specified,

Line 82 If multiple files are specified,

.Nm

will halt with the first failed parse.

.El

.Pp

By default,

.Nm

Line 108 text from stdin, implying

Line 94 text from stdin, implying

and produces

.Fl T Ns Cm ascii

output.

.Pp

.Ex -std mandoc

.Ss Input Formats

The

.Nm

Line 132 format is

Line 115 format is

recommended;

.Xr man 7

should only be used for legacy manuals.

.Pp

A third option,

.Fl m Ns Cm andoc ,

Line 146 the

Line 128 the

parser is used; otherwise, the

.Xr man 7

parser is used.

.Pp

If multiple

files are specified with

Line 158 specified and

Line 139 specified and

.Fl m Ns Cm an

is specified, then this format is used exclusively.

.Ss Output Formats

The

.Nm

Line 167 utility accepts the following

Line 146 utility accepts the following

.Fl T

arguments (see

.Sx OUTPUT ) :

.Bl -tag -width Ds

.It Fl T Ns Cm ascii

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

Line 175 styles.

Line 153 styles.

This is the default.

See

.Sx ASCII Output .

.It Fl T Ns Cm html

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

See

.Sx HTML Output .

.It Fl T Ns Cm 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 Cm ign-errors

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

Useful with

.Fl T Ns Cm lint

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

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

.It Fl f Ns Cm ign-scope

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 Cm no-ign-chars

Do not ignore disallowed characters.

.It Fl f Ns Cm no-ign-escape

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 Cm no-ign-escape ,

Line 241 Implies

Line 205 Implies

and

.Fl f Ns Cm no-ign-chars .

.El

.Ss Output Options

For the time being, only

.Fl T Ns Ar html

Line 286 is used for an external style-sheet.

Line 248 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 332 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 Cm ascii ,

Line 362 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 Cm html

Line 381 cause rendered documents to appear as they do in

Line 336 cause rendered documents to appear as they do in

.Fl T Ns Cm ascii .

.Pp

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

.Ss XHTML Output

Output produced by

.Fl T Ns Cm xhtml

Line 392 See

Line 345 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\*(Gt&1 | less

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

.Pp

To produce HTML manuals with

.Ar style.css

Line 409 as the style-sheet:

Line 358 as the style-sheet:

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

.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

Line 429 The

Line 373 The

.Sq \e~

special character doesn't produce expected behaviour in

.Fl T Ns Cm ascii .

.It

The

.Sq \&Bd \-literal

Line 440 macros of

Line 383 macros of

.Fl T Ns Cm ascii

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

.It

.Xr groff 1 ,

Line 452 macro does not underline when scoped under an

Line 394 macro does not underline when scoped under an

in the FILES section.

This behaves correctly in

.Nm .

.It

A list or display following the

.Sq \&Ss

Line 461 macro in

Line 402 macro in

.Fl T Ns Cm ascii

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

.Sq \&Sh .

.It

The

.Sq \&na

Line 469 The

Line 409 The

macro in

.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 506 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 515 and

Line 449 and

.Sq TP

lists render similarly.

.El

.Sh SEE ALSO

.Xr man 7 ,

.Xr mandoc_char 7 ,

.Xr mdoc 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 Cm html

Line 538 CSS2 styling used for

Line 467 CSS2 styling used for

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

Line 550 which is usually 1024 bytes.

Line 478 which is usually 1024 bytes.

Be aware of this when setting long link

formats such as

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

.Pp

The

.Fl T Ns Cm html

Line 562 font size escape documented in

Line 489 font size escape documented in

.Xr mdoc 7

and

.Xr man 7 .

.Pp

Nesting elements within next-line element scopes of

.Fl m Ns Cm an ,

Line 575 will confuse

Line 501 will confuse

and

.Fl T Ns Cm xhtml

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

.Pp

The

.Sq i

Line 583 macro in

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

CVSweb