mandoc/mandoc.1 - diff

Return to mandoc.1 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mandoc.1 between version 1.219 and 1.224

version 1.219, 2017/09/07 14:55:12

version 1.224, 2018/04/29 14:29:53

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

and redirects parser messages, which usually appear

on standard error output, to standard output.

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

Line 331 output formats in the same way as the

Line 292 output formats in the same way as the

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 352 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 decimal numeric Unicode character references.

.Pp

The following

.Fl O

Line 402 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 422 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 438 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 513 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 588 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 875 A single manual page contains two copies of the RCS id

Line 865 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 952 An

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

CVSweb