mandoc/mandoc.1 - diff

Return to mandoc.1 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mandoc.1 between version 1.215 and 1.228

version 1.215, 2017/07/06 22:59:48

version 1.228, 2018/08/25 16:53:38

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 34

.Sh DESCRIPTION

The

.Nm

utility formats

utility formats manual pages for display.

.Ux

manual pages for display.

.Pp

By default,

.Nm

Line 118 With

Line 116 With

all input files are interpreted as

.Xr man 7 .

By default, the input language is automatically detected for each file:

if the the first macro is

if the first macro is

.Ic \&Dd

.Ic \&Dt ,

Line 132 With other arguments,

Line 130 With other arguments,

is silently ignored.

.It Fl O Ar options

Comma-separated output options.

See the descriptions of the individual output formats for supported

.Ar options .

.It Fl T Ar output

Output format.

Select the output format.

See

Supported values for the

.Sx Output Formats

.Ar output

for available formats.

argument are

Defaults to

.Cm ascii ,

.Fl T Cm locale .

.Cm html ,

the default of

.Cm locale ,

.Cm man ,

.Cm markdown ,

.Cm pdf ,

.Cm ps ,

.Cm tree ,

and

.Cm utf8 .

.Pp

The special

.Fl T Cm lint

mode only parses the input and produces no output.

It implies

.Fl W Cm all

and redirects parser messages, which usually appear on standard

error output, to standard output.

.It Fl W Ar level

Specify the minimum message

.Ar level

Line 196 and

Line 213 and

are requested, they can be joined with a comma, for example

.Fl W Cm error , Ns Cm stop .

.It Ar file

Read input from zero or more files.

Read from the given input file.

If unspecified, reads from stdin.

If multiple files are specified, they are processed in the given order.

If multiple files are specified,

If unspecified,

.Nm

will halt with the first failed parse.

reads from standard input.

.El

.Pp

The options

Line 220 manual.

Line 237 manual.

The options

.Fl fkl

are mutually exclusive and override each other.

.Ss Output Formats

The

.Nm

utility accepts the following

.Fl T

arguments, which correspond to output modes:

.Bl -tag -width "-T markdown"

.It Fl T Cm ascii

Produce 7-bit ASCII output.

See

.Sx ASCII Output .

.It Fl T Cm html

Produce HTML5, CSS1, and MathML output.

See

.Sx HTML Output .

.It Fl T Cm lint

Parse only: produce no output.

Implies

.Fl W Cm all .

.It Fl T Cm locale

Encode output using the current locale.

This is the default.

See

.Sx Locale Output .

.It Fl T Cm man

Produce

.Xr man 7

format output.

See

.Sx Man Output .

.It Fl T Cm markdown

Produce output in

.Sy markdown

format.

See

.Sx Markdown Output .

.It Fl T Cm pdf

Produce PDF output.

See

.Sx PDF Output .

.It Fl T Cm ps

Produce PostScript output.

See

.Sx PostScript Output .

.It Fl T Cm tree

Produce an indented parse tree.

See

.Sx Syntax tree output .

.It Fl T Cm utf8

Encode output in the UTF\-8 multi-byte format.

See

.Sx UTF\-8 Output .

.El

.Pp

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

corresponding filter in-order.

.Ss ASCII Output

Output produced by

Use

.Fl T Cm ascii

is rendered in standard 7-bit ASCII documented in

to force text output in 7-bit ASCII character encoding documented in the

.Xr ascii 7 .

.Xr ascii 7

manual page, ignoring the

.Xr locale 1

set in the environment.

.Pp

Font styles are applied by using back-spaced encoding such that an

underlined character

Line 297 The special characters documented in

Line 261 The special characters documented in

.Xr mandoc_char 7

are rendered best-effort in an ASCII equivalent.

.Pp

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

exceed this limit.

.Pp

The following

.Fl O

arguments are accepted:

Line 313 and seven for

Line 274 and seven for

.Xr man 7 .

Increasing this is not recommended; it may result in degraded formatting,

for example overfull lines or ugly line breaks.

When output is to a pager on a terminal that is less than 66 columns

wide, the default is reduced to three columns.

.It Cm mdoc

Format

.Xr man 7

input files in

.Xr mdoc 7

output style.

Specifically, this suppresses the two additional blank lines near the

top and the bottom of each page, and it implies

.Fl O Cm indent Ns =5 .

One useful application is for checking that

.Fl T Cm man

output formats in the same way as the

.Xr mdoc 7

source it was generated from.

.It Cm width Ns = Ns Ar width

The output width is set to

.Ar width .

.Ar width

instead of the default of 78.

When output is to a pager on a terminal that is less than 79 columns

wide, the default is reduced to one less than the terminal width.

In any case, lines that are output in literal mode are never wrapped

and may exceed the output width.

.El

.Ss HTML Output

Output produced by

Line 336 defaults to simple output (via an embedded style-sheet

Line 318 defaults to simple output (via an embedded style-sheet

readable in any graphical or text-based web

browser.

.Pp

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

Non-ASCII characters are rendered

as hexadecimal Unicode character references.

.Pp

The following

.Fl O

Line 386 This must be a valid absolute or

Line 369 This must be a valid absolute or

relative URI.

.El

.Ss Locale Output

Locale-depending output encoding is triggered with

By default,

.Nm

automatically selects UTF-8 or ASCII output according to the current

.Xr locale 1 .

If any of the environment variables

.Ev LC_ALL ,

.Ev LC_CTYPE ,

.Ev LANG

are set and the first one that is set

selects the UTF-8 character encoding, it produces

.Sx UTF-8 Output ;

otherwise, it falls back to

.Sx ASCII Output .

This output mode can also be selected explicitly with

.Fl T Cm locale .

This is the default.

.Pp

This option is not available on all systems: systems without locale

support, or those whose internal representation is not natively UCS-4,

will fall back to

.Fl T Cm ascii .

See

.Sx ASCII Output

for font style specification and available command-line arguments.

.Ss Man Output

Translate input format into

Use

.Fl T Cm man

to translate

.Xr mdoc 7

input into

.Xr man 7

output format.

This is useful for distributing manual sources to legacy systems

Line 406 lacking

Line 398 lacking

.Xr mdoc 7

formatters.

.Pp

If the input format of a file is

.Xr mdoc 7

is passed as input, it is translated into

.Xr man 7 .

If the input format is

.Xr man 7 ,

the input is copied to the output, expanding any

.Xr roff 7

Line 422 level controls which

Line 410 level controls which

.Sx DIAGNOSTICS

are displayed before copying the input to the output.

.Ss Markdown Output

Translate

Use

.Fl T Cm markdown

to translate

.Xr mdoc 7

input to the

input to the markdown format conforming to

.Sy markdown

format conforming to

.Lk http://daringfireball.net/projects/markdown/syntax.text\

"John Gruber's 2004 specification" .

The output also almost conforms to the

Line 497 If an unknown value is encountered,

Line 485 If an unknown value is encountered,

.Ar letter

is used.

.El

.Ss UTF\-8 Output

.Ss UTF-8 Output

Use

.Fl T Cm utf8

to force a UTF\-8 locale.

to force text output in UTF-8 multi-byte character encoding,

ignoring the

.Xr locale 1

settings in the environment.

See

.Sx Locale Output

.Sx ASCII Output

for details and options.

regarding font styles and

.Fl O

arguments.

.Pp

On operating systems lacking locale or wide character support, and

on those where the internal character representation is not UCS-4,

.Nm

always falls back to

.Sx ASCII Output .

.Ss Syntax tree output

Use

.Fl T Cm tree

Line 572 Meta data is not available in this case.

Line 571 Meta data is not available in this case.

.El

.Sh ENVIRONMENT

.Bl -tag -width MANPAGER

.It Ev LC_CTYPE

The character encoding

.Xr locale 1 .

When

.Sx Locale Output

is selected, it decides whether to use ASCII or UTF-8 output format.

It never affects the interpretation of input files.

.It Ev MANPAGER

Any non-empty value of the environment variable

.Ev MANPAGER

Line 719 so using GNU troff instead of

Line 725 so using GNU troff instead of

.Nm

to process the file may be preferable.

.It Cm error

An input file contains invalid syntax that cannot be safely interpreted.

Indicates a risk of information loss or severe misformatting,

By discarding part of the input or inserting missing tokens,

in most cases caused by serious syntax errors.

the parser is able to continue, and the error does not prevent

generation of formatted output, but typically, preparing that

output involves information loss, broken document structure

or unintended formatting, no matter whether

.Nm

or GNU troff is used.

In many cases, the output of

.Nm

and GNU troff is identical, but in some,

.Nm

is more resilient than GNU troff with respect to malformed input.

.Pp

Non-existent or unreadable input files are also reported on the

.Cm error

level.

In that case, the parser cannot even be started and no output

is produced from those input files.

.It Cm warning

An input file uses obsolete, discouraged or non-portable syntax.

Indicates a risk that the information shown or its formatting

All the same, the meaning of the input is unambiguous and a correct

may mismatch the author's intent in minor ways.

rendering can be produced.

Additionally, syntax errors are classified at least as warnings,

Documents causing warnings may render poorly when using other

even if they do not usually cause misformatting.

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

Line 758 Please use your good judgement to decide whether any p

Line 745 Please use your good judgement to decide whether any p

.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

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

Line 866 Consider using the conventional

Line 853 Consider using the conventional

date format

.Dq "Month dd, yyyy"

instead.

.It Sy "normalizing date format to" : No ...

.Pq mdoc , man

The

.Ic \&Dd

.Ic \&TH

macro provides an abbreviated month name or a day number with a

leading zero.

In the formatted output, the month name is written out in full

and the leading zero is omitted.

.It Sy "lower case character in document title"

.Pq mdoc , man

The title is still used as given in the

Line 878 A single manual page contains two copies of the RCS id

Line 875 A single manual page contains two copies of the RCS id

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"

.It Sy "possible typo in section name"

.Pq mdoc

Fuzzy string matching revealed that the argument of an

.Ic \&Sh

Line 955 An

Line 952 An

request occurs even though the document already switched to no-fill mode

and did not switch back to fill mode yet.

It has no effect.

.It Sy "verbatim \(dq--\(dq, maybe consider using \e(em"

.Pq mdoc

Even though the ASCII output device renders an em-dash as

.Qq \-\- ,

that is not a good way to write it in an input file

because it renders poorly on all other output devices.

.It Sy "function name without markup"

.Pq mdoc

A word followed by an empty pair of parentheses occurs on a text line.

Line 1603 or

Line 1606 or

.Cm off .

The invalid argument is moved out of the macro, which leaves the macro

empty, causing it to toggle the spacing mode.

.It Sy "argument contains two font escapes"

.Pq roff

The second argument of a

.Ic char

request contains more than one font escape sequence.

A wrong font may remain active after using the character.

.It Sy "unknown font, skipping request"

.Pq man , tbl

Line 1804 or

Line 1813 or

macro.

It may be mistyped or unsupported.

The request or macro is discarded including its arguments.

.It Sy "skipping request outside macro"

.Pq roff

.Ic shift

.Ic return

request occurs outside any macro definition and has no effect.

.It Sy "skipping insecure request"

.Pq roff

An input file attempted to run a shell command

Line 1913 When parsing for a request or a user-defined macro nam

Line 1929 When parsing for a request or a user-defined macro nam

only the escape sequence is discarded.

The characters preceding it are used as the request or macro name,

the characters following it are used as the arguments to the request or macro.

.It Sy "using macro argument outside macro"

.Pq roff

The escape sequence \e$ occurs outside any macro definition

and expands to the empty string.

.It Sy "argument number is not numeric"

.Pq roff

The argument of the escape sequence \e$ is not a digit;

the escape sequence expands to the empty string.

.It Sy "NOT IMPLEMENTED: Bd -file"

.Pq mdoc

For security reasons, the

Line 1941 macro fails to specify the list type.

Line 1965 macro fails to specify the list type.

The argument of a

.Ic \&ce

request is not a number.

.It Sy "argument is not a character"

.Pq roff

The first argument of a

.Ic char

request is neither a single ASCII character

nor a single character escape sequence.

The request is ignored including all its arguments.

.It Sy "missing manual name, using \(dq\(dq"

.Pq mdoc

The first call to

Line 1975 or

Line 2006 or

.Ic \&gsize

statement has a non-numeric or negative argument or no argument at all.

The invalid request or statement is ignored.

.It Sy "excessive shift"

.Pq roff

The argument of a

.Ic shift

request is larger than the number of arguments of the macro that is

currently being executed.

All macro arguments are deleted and \en(.$ is set to zero.

.It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq"

.Pq roff

For security reasons,

CVSweb