mandoc/mandoc.1 - diff

Return to mandoc.1 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mandoc.1 between version 1.260 and 1.267

version 1.260, 2022/06/07 09:54:40

version 1.267, 2023/11/13 19:13:01

Line 1

.\" $Id$

.\"

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

Line 287 arguments are accepted:

.It Cm indent Ns = Ns Ar indent

The left margin for normal text is set to

.Ar indent

blank characters instead of the default of five for

blank characters instead of the default of five.

.Xr mdoc 7

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

Line 302 input files in

Line 299 input files in

.Xr mdoc 7

output style.

This prints the operating system name rather than the page title

on the right side of the footer line, and it implies

on the right side of the footer line.

.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

Line 342 and may exceed the output width.

Line 338 and may exceed the output width.

Output produced by

.Fl T Cm html

conforms to HTML5 using optional self-closing tags.

Default styles use only CSS1.

Equations rendered from

.Xr eqn 7

blocks use MathML.

.Pp

The file

.Pa /usr/share/misc/mandoc.css

documents style-sheet classes available for customising output.

If a style-sheet is not specified with

.Fl O Cm style ,

.Fl T Cm html

defaults to simple output (via an embedded style-sheet)

readable in any graphical or text-based web

browser.

.Pp

Non-ASCII characters are rendered

as hexadecimal Unicode character references.

.Pp

Line 407 otherwise, the second format is used.

Line 391 otherwise, the second format is used.

.It Cm style Ns = Ns Ar style.css

The file

.Ar style.css

is used for an external style-sheet.

is used as an external stylesheet.

This must be a valid absolute or

relative URI.

.Pp

Using the file

.Pa mandoc.css

that is distributed with

.Nm

is recommended.

It provides an appearance similar to terminal output with some additional

features specific to

.Nm

HTML output, in particular making anchor locations that support

deep linking stand out visually by putting a dotted line under them,

providing tooltips showing the semantic function of elements (macro

names), providing some simple aspects of responsive web design, and

providing simple support for users who prefer a dark color scheme.

.Pp

Using a custom CSS file is possible, but writing it requires

proficiency in all of the languages HTML 5, CSS 4, and

.Xr mdoc 7

and familiarity with the

.Nm Ns -specific

classes used in

.Pa mandoc.css .

Besides, while the file

.Pa mandoc.css

is always adapted to the HTML output generated by the

.Nm

version it is distributed with, maintaining a custom CSS file usually

requires adaptations each time

.Nm

is upgraded to a new version.

.Pp

If a stylesheet is not specified with

.Fl O Cm style ,

.Fl T Cm html

embeds a minimal stylesheet into the HTML output, mostly to select

adequate font-style and font-weight attributes for various macros.

The result is readable in any graphical or text-based web browser,

but does not aim for looking similar to terminal output.

Instead, formatting is mostly left to browser defaults

and to user settings in the browser configuration.

.It Cm tag Ns Op = Ns Ar term

Same syntax and semantics as for

.Sx ASCII Output .

Line 739 To page manuals to the terminal:

Line 763 To page manuals to the terminal:

.Pp

To produce HTML manuals with

.Pa /usr/share/misc/mandoc.css

as the style-sheet:

as the stylesheet:

.Pp

.Dl $ mandoc \-T html -O style=/usr/share/misc/mandoc.css mdoc.7 > mdoc.7.html

.Pp

Line 766 Messages displayed by

Line 790 Messages displayed by

follow this format:

.Bd -ragged -offset indent

.Nm :

.Ar file : Ns Ar line : Ns Ar column : level : message : macro arguments

.Ar file : Ns Ar line : Ns Ar column : level : message : macro argument ...

.Pq Ar os

.Ed

.Pp

Line 786 and

Line 810 and

strings are explained below.

The name of the

.Ar macro

triggering the message and its

triggering the message and its arguments are omitted where meaningless.

.Ar arguments

are omitted where meaningless.

The

.Ar os

operating system specifier is omitted for messages that are relevant

Line 1269 The same standard section title occurs more than once.

Line 1291 The same standard section title occurs more than once.

A standard section header occurs in a section of the manual

where it normally isn't useful.

.It Sy "cross reference to self"

.Pq mdoc

.Pq mdoc , man

.Ic \&Xr

.Ic \&MR

macro refers to a name and section matching the section of the present

manual page and a name mentioned in an

.Ic \&Nm

Line 1474 A

Line 1498 A

.Ic \&Bl ,

.Ic \&D1 ,

.Ic \&Dl ,

.Ic \&MT ,

.Ic \&RS ,

.Ic \&UR

.Ic \&RS

block contains nothing in its body and will produce no output.

.It Sy "empty argument, using 0n"

.Pq mdoc

Line 1592 macro is immediately followed by an

Line 1614 macro is immediately followed by an

macro on the next input line.

Such an empty block does not produce any output.

.It Sy "missing section argument"

.Pq mdoc

.Pq mdoc , man

.Ic \&Xr

.Ic \&MR

macro lacks its second, section number argument.

The first argument, i.e. the name, is printed, but without subsequent

The first argument, i.e. the name, is printed, but without a section number.

parentheses.

In the case of

.Ic \&Xr ,

the parentheses are also omitted.

.It Sy "missing -std argument, adding it"

.Pq mdoc

Line 2128 request is neither a single ASCII character

Line 2154 request is neither a single ASCII character

nor a single character escape sequence.

All arguments are ignored and printing of a margin character is disabled.

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

.Pq mdoc

.Pq mdoc , man

The first call to

.Ic \&Nm ,

or any call in the NAME section, lacks the required argument.

or any call in the NAME section, lacks the required argument, or

.Ic \&MR

is called without any argument.

.It Sy "uname(3) system call failed, using UNKNOWN"

.Pq mdoc

The

Line 2259 or a request of the

Line 2287 or a request of the

family with more than two arguments

.It

.Ic \&Dt

.Ic \&MR

with more than three arguments

.It

.Ic \&TH

Line 2321 attempts to employ one of the characters

Line 2351 attempts to employ one of the characters

as an argument delimiter.

The escape sequence is ignored including the invalid opening delimiter

and the rest of the argument may appear as output text.

While various charcters can be used as argument delimiters,

While various characters can be used as argument delimiters,

using the apostrophe-quote character

.Pq Sq \(aq

is recommended for readability and robustness.

CVSweb