mandoc/mdoc.7 - diff

Return to mdoc.7 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mdoc.7 between version 1.278 and 1.286

version 1.278, 2019/04/24 13:15:00

version 1.286, 2021/07/29 16:25:20

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 297 utility does this, that, and the other.

It usually follows with a breakdown of the options (if documenting a

command), such as:

.Bd -literal -offset indent

The arguments are as follows:

The options are as follows:

\&.Bl \-tag \-width Ds

\&.It Fl v

Print verbose information.

Line 449 in the alphabetical

.It Ic \&Ss Ta subsection header (one line)

.It Ic \&Sx Ta internal cross reference to a section or subsection

.It Ic \&Xr Ta cross reference to another manual page: Ar name section

.It Ic \&Tg Ta tag the definition of a Ar term Pq <= 1 arguments

.It Ic \&Pp Ta start a text paragraph (no arguments)

.El

.Ss Displays and lists

Line 1202 Close a

Line 1203 Close a

block.

Does not have any tail arguments.

.It Ic \&Dd Cm $\&Mdocdate$ | Ar month day , year

Document date for display in the page footer.

Document date for display in the page footer,

by convention the date of the last change.

This is the mandatory first macro of any

.Nm

manual.

Line 1566 and

Line 1568 and

.It Ic \&Fl Op Ar word ...

Command-line flag or option.

Used when listing arguments to command-line utilities.

Prints a fixed-width hyphen

For each argument, prints an ASCII hyphen-minus character

.Sq \-

.Sq \- ,

directly followed by each argument.

immediately followed by the argument.

If no arguments are provided, a hyphen is printed followed by a space.

If no arguments are provided, a hyphen-minus is printed followed by a space.

If the argument is a macro, a hyphen is prefixed to the subsequent macro

If the argument is a macro, a hyphen-minus is prefixed

output.

to the subsequent macro output.

.Pp

Examples:

.Dl ".Fl R Op Fl H | L | P"

.Dl ".Nm du Op Fl H | L | P"

.Dl ".Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux"

.Dl ".Nm ls Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux"

.Dl ".Fl type Cm d Fl name Pa CVS"

.Dl ".Nm route Cm add Fl inet Ar destination gateway"

.Dl ".Fl Ar signal_number"

.Dl ".Nm locate.updatedb Op Fl \e-fcodes Ns = Ns Ar dbfile"

.Dl ".Fl o Fl"

.Dl ".Nm aucat Fl o Fl"

.Dl ".Nm kill Fl Ar signal_number"

.Pp

For GNU-sytle long options, escaping the additional hyphen-minus is not

strictly required, but may be safer with future versions of GNU troff; see

.Xr mandoc_char 7

for details.

.Pp

See also

.Ic \&Mt .

Line 2548 Table cell separator in

Line 2556 Table cell separator in

.Ic \&Bl Fl column

lists; can only be used below

.Ic \&It .

.It Ic \&Tg Op Ar term

Announce that the next input line starts a definition of the

.Ar term .

This macro must appear alone on its own input line.

The argument defaults to the first argument of the first macro

on the next line.

The argument may not contain whitespace characters, not even when it is quoted.

This macro is a

.Xr mandoc 1

extension and is typically ignored by other formatters.

.Pp

When viewing terminal output with

.Xr less 1 ,

the interactive

.Ic :t

command can be used to go to the definition of the

.Ar term

as described for the

.Ev MANPAGER

variable in

.Xr man 1 ;

when producing HTML output, a fragment identifier

.Pq Ic id No attribute

is generated, to be used for deep linking to this place of the document.

.Pp

In most cases, adding a

.Ic \&Tg

macro would be redundant because

.Xr mandoc 1

is able to automatically tag most definitions.

This macro is intended for cases where automatic tagging of a

.Ar term

is unsatisfactory, for example if a definition is not tagged

automatically (false negative) or if places are tagged that do

not define the

.Ar term

(false positives).

When there is at least one

.Ic \&Tg

macro for a

.Ar term ,

no other places are automatically marked as definitions of that

.Ar term .

.It Ic \&Tn Ar word ...

Supported only for compatibility, do not use this in new manuals.

Even though the macro name

Line 2681 column, if applicable, describes closure rules.

Line 2732 column, if applicable, describes closure rules.

.Ss Block full-explicit

Multi-line scope closed by an explicit closing macro.

All macros contains bodies; only

.Ic \s&Bf

.Ic \&Bf

and

.Pq optionally

.Ic \&Bl

Line 2912 then the macro accepts an arbitrary number of argument

Line 2963 then the macro accepts an arbitrary number of argument

.It Ic \&St Ta \&No Ta Yes Ta 1

.It Ic \&Sx Ta Yes Ta Yes Ta >0

.It Ic \&Sy Ta Yes Ta Yes Ta >0

.It Ic \&Tg Ta \&No Ta \&No Ta <2

.It Ic \&Tn Ta Yes Ta Yes Ta >0

.It Ic \&Ud Ta \&No Ta \&No Ta 0

.It Ic \&Ux Ta Yes Ta Yes Ta n

Line 3005 in the same way as a plain

Line 3057 in the same way as a plain

.Sq \&|

character.

Using this predefined string is not recommended in new manuals.

.Pp

Appending a zero-width space

.Pq Sq \e&

to the end of an input line is also useful to prevent the interpretation

of a trailing period, exclamation or question mark as the end of a

sentence, for example when an abbreviation happens to occur

at the end of a text or macro input line.

.Ss Font handling

.Nm

Line 3032 The following problematic behaviour is found in groff:

Line 3091 The following problematic behaviour is found in groff:

.Pp

.Bl -dash -compact

.It

.Ic \&Dd

with non-standard arguments behaves very strangely.

When there are three arguments, they are printed verbatim.

Any other number of arguments is replaced by the current date,

but without any arguments the string

.Dq Epoch

is printed.

.It

.Ic \&Lk

only accepts a single link-name argument; the remainder is misformatted.

.It

.Ic \&Pa

does not format its arguments when used in the FILES section under

certain list types.

Line 3050 certain list types.

Line 3098 certain list types.

.Ic \&Ta

can only be called by other macros, but not at the beginning of a line.

.It

.Ic \&%C

is not implemented (up to and including groff-1.22.2).

.It

.Sq \ef

.Pq font face

and

Line 3102 but produces large indentations.

Line 3147 but produces large indentations.

.Xr tbl 7

.Pp

The web page

.Lk http://mandoc.bsd.lv/mdoc/ "extended documentation for the mdoc language"

.Lk https://mandoc.bsd.lv/mdoc/ "extended documentation for the mdoc language"

provides a few tutorial-style pages for beginners, an extensive style

guide for advanced authors, and an alphabetic index helping to choose

the best macros for various kinds of content.

.Pp

The manual page

.Lk https://man.voidlinux.org/groff_mdoc "groff_mdoc(7)"

contained in the

.Dq groff

package documents exactly the same language in a somewhat different style.

.Sh HISTORY

The

.Nm

CVSweb