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

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

version 1.223, 2018/04/13 19:55:30

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 118 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 238 See

.It Fl T Cm lint

Parse only: produce no output.

Implies

.Fl W Cm all .

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

Line 297 The special characters documented in

Line 299 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 312 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 719 so using GNU troff instead of

Line 739 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 759 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 878 A single manual page contains two copies of the RCS id

Line 879 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 956 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