mdoc.samples (7)

Leading comments

 Copyright (c) 1990, 1993
	The Regents of the University of California.  All rights reserved.

 %%%LICENSE_START(BSD_4_CLAUSE_UCB)
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:
 1. Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.
 2. Redistributions in binary form must reproduce the above copyright
    notice, this ...

NAME

SYNOPSIS

DESCRIPTION

Throughout the UNIX manual pages, a manual entry is simply referred to as a man page, regardless of actual length and without sexist intention.

GETTING STARTED

1. TROFF IDIOSYNCRASIES

   "Macro Usage"

   "Passing Space Characters in an Argument"

   "Trailing Blank Space Characters (a warning)"

   "Escaping Special Characters"

2. THE ANATOMY OF A MAN PAGE

   "A manual page template"

3. TITLE MACROS
4. INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS

   "What's in a name..."

   "General Syntax"

5. MANUAL DOMAIN

   "Addresses"

   "Author name"

   "Arguments"

   "Configuration Declarations (section four only)"

   "Command Modifier"

   "Defined Variables"

   "Errno's (Section two only)"

   "Environment Variables"

   "Function Argument"

   "Function Declaration"

   "Flags"

   "Functions (library routines)"

   "Function Types"

   "Interactive Commands"

   "Names"

   "Options"

   "Pathnames"

   "Variables"

   "Cross References"

6. GENERAL TEXT DOMAIN

   "AT&T Macro"

   "BSD Macro"

   "FreeBSD Macro"

   "UNIX Macro"

   "Enclosure/Quoting Macros"

   "Angle Bracket Quote/Enclosure"

   "Bracket Quotes/Enclosure"

   "Double Quote macro/Enclosure"

   "Parenthesis Quote/Enclosure"

   "Single Quotes/Enclosure"

   "Prefix Macro"

   "No-[or Normal Text Macro]

   "Space Macro

   "Section Cross References"

   "References and Citations"

   "Return Values (sections two and three only)"

   "Trade Names (Acronyms and Type Names)"

   "Extended Arguments"

7. PAGE STRUCTURE DOMAIN

   "Section Headers"

   "Paragraphs and Line Spacing"

   "Keeps"

   "Displays"

   "Font Modes (Emphasis, Literal, and Symbolic)"

   "Lists and Columns"

8. PREDEFINED STRINGS
9. DIAGNOSTICS
10. FORMATTING WITH GROFF, TROFF AND NROFF
11. BUGS

TROFF IDIOSYNCRASIES

Macro Usage

In general, troff(1) macros accept up to nine arguments, any extra arguments are ignored. Most macros in -mdoc accept nine arguments and, in limited cases, arguments may be continued or extended on the next line (See Sx Extensions ) . A few macros handle quoted arguments (see Sx Passing Space Characters in an Argument below).

Most of the -mdoc general text domain and manual domain macros are special in that their argument lists are parsed for callable macro names. This means an argument on the argument list which matches a general text or manual domain macro name and is determined to be callable will be executed or called when it is processed. In this case, the argument, although the name of a macro, is not preceded by a `.' (dot). It is in this manner that many macros are nested; for example the option macro, `.[,] ' may call the flag and argument macros, `- ' and `file ... ' to specify an optional flag with an argument:

[-s bytes ]

is produced by .[-s bytes ]

To prevent a two character string from being interpreted as a macro name, precede the string with the escape sequence `\&' :

[-s bytes ]

is produced by .[\&-s \&bytes ]

Here the strings `- ' and `file ... ' are not interpreted as macros. Macros whose argument lists are parsed for callable arguments are referred to as parsed and macros which may be called from an argument list are referred to as callable throughout this document and in the companion quick reference manual mdoc(7). This is a technical faux pas as almost all of the macros in -mdoc are parsed, but as it was cumbersome to constantly refer to macros as being callable and being able to call other macros, the term parsed has been used.

Passing Space Characters in an Argument

There are two possible ways to pass an argument which contains an embedded space. Implementation note Unfortunately, the most convenient way of passing spaces in between quotes by reassigning individual arguments before parsing was fairly expensive speed wise and space wise to implement in all the macros for AT&T troff. It is not expensive for groff but for the sake of portability, has been limited to the following macros which need it the most:

Configuration declaration (section 4

Sx SYNOPSIS )

Begin list (for the width specifier).

Emphasized text.

Fn Functions (sections two and four).

List items.

Literal text.

Symbolic text.

%B

Book titles.

%J

Journal names.

%O

Optional notes for a reference.

%R

Report title (in a reference).

%T

Title of article in a book or journal.

One way of passing a string containing blank spaces is to use the hard or unpaddable space character `\
 ,' that is, a blank space preceded by the escape character `\' This method may be used with any macro but has the side effect of interfering with the adjustment of text over the length of a line. Troff sees the hard space as if it were any other printable character and cannot split the string into blank or newline separated pieces as one would expect. The method is useful for strings which are not expected to overlap a line boundary. For example:

Fn fetch char *str

is created by `.Fn fetch ' char\ *str

Fn fetch char *str

can also be created by `.Fn fetch ' \*qchar *str\*q

If the `\' or quotes were omitted, `.Fn would ' see three arguments and the result would be:

Fn fetch char *str

For an example of what happens when the parameter list overlaps a newline boundary, see the Sx BUGS section.

Trailing Blank Space Characters

Escaping Special Characters

THE ANATOMY OF A MAN PAGE

A manual page template

.\" The following requests are required for all man pages.
.Dd Month day, year
.Os OPERATING_SYSTEM [version/release]
.Dt DOCUMENT_TITLE [section number] [volume]
.Sh NAME
.Nm name
.Nd one line description of name
.Sh SYNOPSIS
.Sh DESCRIPTION
.\" The following requests should be uncommented and
.\" used where appropriate.  This next request is
.\" for sections 2 and 3 function return values only.
.\" .Sh RETURN VALUE
.\" This next request is for sections 1, 6, 7 & 8 only
.\" .Sh ENVIRONMENT
.\" .Sh FILES
.\" .Sh EXAMPLES
.\" This next request is for sections 1, 6, 7 & 8 only
.\"     (command return values (to shell) and
.\"       fprintf/stderr type diagnostics)
.\" .Sh DIAGNOSTICS
.\" The next request is for sections 2 and 3 error
.\" and signal handling only.
.\" .Sh ERRORS
.\" .Sh SEE ALSO
.\" .Sh CONFORMING TO
.\" .Sh HISTORY
.\" .Sh AUTHORS
.\" .Sh BUGS

The first items in the template are the macros (., ., . ) the document date, the operating system the man page or subject source is developed or modified for, and the man page title (in uppercase ) along with the section of the manual the page belongs in. These macros identify the page, and are discussed below in Sx TITLE MACROS .

The remaining items in the template are section headers (.

;

TITLE MACROS

.

The document title is the subject of the man page and must be in CAPITALS due to troff limitations. The section number may be 1, ..., 8, and if it is specified, the volume title may be omitted. A volume title may be arbitrary or one of the following:

AMD   UNIX Ancestral Manual Documents

SMM        UNIX System Manager's Manual

URM   UNIX Reference Manual

PRMUNIX Programmer's Manual

The default volume labeling is
URM for sections 1, 6, and 7; SMM for section 8; PRM for sections 2, 3, 4, and 5.

.operating_system release#

The name of the operating system should be the common acronym, for example, BSD or FreeBSD or ATT The release should be the standard release nomenclature for the system specified, for example, 4.3, 4.3+Tahoe, V.3, V.4. Unrecognized arguments are displayed as given in the page footer. For instance, a typical footer might be:

.4.3BSD

or

.FreeBSD 2.2

or for a locally produced set

.CS Department

The Berkeley default, `.without ' an argument, has been defined as BSD in the site-specific file /usr/share/tmac/mdoc/doc-common It really should default to LOCAL Note, if the `.macro ' is not present, the bottom left corner of the page will be ugly.

.month day, year

The date should be written formally:

January 25, 1989

INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS

What's in a name...

In the first case, troff(1) macros are themselves a type of command; the general syntax for a troff command is:

.Va argument1 argument2 ... argument9

The `.is ' a macro command or request, and anything following it is an argument to be processed. In the second case, the description of a UNIX command using the content macros is a bit more involved; a typical Sx SYNOPSIS command line might be displayed as:

filter [-flag ] infile outfile

Here, filter is the command name and the bracketed string -flag is a flag argument designated as optional by the option brackets. In -mdoc terms, infile and outfile are called arguments The macros which formatted the above example:

.Nm filter
.Op Fl flag
.Ar infile outfile

In the third case, discussion of commands and command syntax includes both examples above, but may add more detail. The arguments infile and outfile from the example above might be referred to as operands or file arguments Some command-line argument lists are quite long:

make

[-eiknqrstv ] [-D variable ] [-d flags ] [-f makefile ] -words [-I directory ] [-j max_jobs ] [variable=value ] -words [target ... ]

Here one might talk about the command make and qualify the argument makefile as an argument to the flag, -f or discuss the optional file operand target In the verbal context, such detail can prevent confusion, however the -mdoc package does not have a macro for an argument to a flag. Instead the `file ... ' argument macro is used for an operand or file argument like target as well as an argument to a flag like variable The make command line was produced from:

.Nm make
.Op Fl eiknqrstv
.Op Fl D Ar variable
.Op Fl d Ar flags
.Op Fl f Ar makefile
.Op Fl I Ar directory
.Op Fl j Ar max_jobs
.Op Ar variable=value
.Bk -words
.Op Ar target ...
.Ek

The `.and ' `.macros ' are explained in Sx Keeps .

General Syntax

.sptr, ptr),

The result is:

sptr, ptr),

The punctuation is not recognized and all is output in the literal font. If the punctuation is separated by a leading white space:

.sptr , ptr ) ,

The result is:

sptr , ptr

The punctuation is now recognized and is output in the default font distinguishing it from the strings in literal font.

To remove the special meaning from a punctuation character escape it with `\&' Troff is limited as a macro language, and has difficulty when presented with a string containing a member of the mathematical, logical or quotation set:

{+,-,/,*,%,<,>,<=,>=,=,==,&,`,',"}

The problem is that troff may assume it is supposed to actually perform the operation or evaluation suggested by the characters. To prevent the accidental evaluation of these characters, escape them with `\&' Typical syntax is shown in the first content macro displayed below, `. '

MANUAL DOMAIN

Address Macro

Usage: .address ... [ .,:;()[]?! ]

.addr1

addr1

.addr1

addr1

.addr1 , file2

addr1 , file2

.f1 , f2 , f3:

f1 , f2 , f3

.addr ) ),

addr ) )

It is an error to call `.without ' arguments. `.is ' callable by other macros and is parsed.

Author Name

Usage: .An author_name [ .,:;()[]?! ]

.An Joe Author

An Joe Author

.An Joe Author,

An Joe Author ,

.An Joe Author Aq nobody@FreeBSD.ORG

An Joe Author Aq nobody@FreeBSD.ORG

.An Joe Author ) ),

An Joe Author ) ) ,

The `.An macro ' is parsed and is callable. It is an error to call `.An without ' any arguments.

Argument Macro

Usage: .argument ... [ .,:;()[]?! ]

.file ...

file ...

.file1

file1

.file1

file1

.file1 file2

file1 file2

.f1 f2 f3:

f1 f2 f3

.file ) ),

file ) )

If `.file ... ' is called without arguments, `file ... ' is assumed. The `.file ... ' macro is parsed and is callable.

Configuration Declaration (section four only)

device le0 at scode?

produced by: `.device ' le0 at scode? .

Command Modifier

Defined Variables

Usage: .defined_variable ... [ .,:;()[]?! ]

.MAXHOSTNAMELEN

MAXHOSTNAMELEN

.TIOCGPGRP )

TIOCGPGRP

It is an error to call `.without ' arguments. `.is ' parsed and is callable.

Errno's (Section two only)

Usage: .Er ERRNOTYPE ... [ .,:;()[]?! ]

.Er ENOENT

Er ENOENT

.Er ENOENT );

Er ENOENT ) ;

.Bq Er ENOTDIR

Bq Er ENOTDIR

It is an error to call `.Er without ' arguments. The `.Er macro ' is parsed and is callable.

Environment Variables

Usage: .argument ... [ .,:;()[]?! ]

.DISPLAY

DISPLAY

.PATH

PATH

.PRINTER ) ),

PRINTER ) )

It is an error to call `.without ' arguments. The `.macro ' is parsed and is callable.

Function Argument

Usage: .Fa function_argument ... [ .,:;()[]?! ]

.Fa d_namlen ) ),

Fa d_namlen ) ) ,

.Fa iov_len

Fa iov_len

It is an error to call `.Fa without ' arguments. `.Fa is ' parsed and is callable.

Function Declaration

Usage: .Fd include_file (or defined variable)

In the Sx SYNOPSIS section a `.Fd request ' causes a line break if a function has already been presented and a break has not occurred. This leaves a nice vertical space in between the previous function call and the declaration for the next function.

Flags

Usage: .-argument ... [ .,:;()[]?! ]

.-

-

.-cfv

-cfv

.-cfv

-cfv

.-s v t

-s v t

.--,

--

.-xyz ),

-xyz )

The `.- ' macro without any arguments results in a dash representing stdin/stdout. Note that giving `.- ' a single dash, will result in two dashes. The `.- ' macro is parsed and is callable.

Functions (library routines)

Usage: .Fn [type] function [[type] parameters ... [ .,:;()[]?! ]]

.Fn getchar

Fn getchar

.Fn strlen ) ,

Fn strlen ) ,

.Fn \*qint align\*q \*qconst * char *sptrs\*q

Fn int align const * char *sptrs ,

It is an error to call `.Fn without ' any arguments. The `.Fn macro ' is parsed and is callable, note that any call to another macro signals the end of the `.Fn call ' (it will close-parenthesis at that point).

For functions that have more than eight parameters (and this is rare), the macros `.Fo (function ' open) and `.Fc (function ' close) may be used with `.Fa (function ' argument) to get around the limitation. For example:

.Fo "int res_mkquery"
.Fa "int op"
.Fa "char *dname"
.Fa "int class"
.Fa "int type"
.Fa "char *data"
.Fa "int datalen"
.Fa "struct rrec *newrr"
.Fa "char *buf"
.Fa "int buflen"
.Fc

Produces:

Fo int res_mkquery Fa int op Fa char *dname Fa int class Fa int type Fa char *data Fa int datalen Fa struct rrec *newrr Fa char *buf Fa int buflen Fc

The `.Fo and ' `.Fc macros ' are parsed and are callable. In the Sx SYNOPSIS section, the function will always begin at the beginning of line. If there is more than one function presented in the Sx SYNOPSIS section and a function type has not been given, a line break will occur, leaving a nice vertical space between the current function name and the one prior. At the moment, `.Fn does ' not check its word boundaries against troff line lengths and may split across a newline ungracefully. This will be fixed in the near future.

Function Type

Usage: .Ft type ... [ .,:;()[]?! ]

.Ft struct stat

Ft struct stat

The `.Ft request ' is not callable by other macros.

Interactive Commands

Usage: .argument ... [ .,:;()[]?! ]

.:wq

:wq

.do while {...}

do while {...}

.setenv , unsetenv

setenv , unsetenv

It is an error to call `.without ' arguments. The `.macro ' is parsed and is callable.

Name Macro

Usage: .argument ... [ .,:;()[]?! ]

.mdoc.sample

mdoc.sample

.\-mdoc

-mdoc

.foo ) ),

foo ) )

.groff Fl m Ns Cm doc Ar

groff Fl m Ns Cm doc Ar

The `.groff Fl m Ns Cm doc Ar ' macro is parsed and is callable.

Options

Usage: .[options ... [ .,:;()[]?! ]]

.[[

.[-k ]

] ]

[-k ]

.[-k ) . ]

[-k ]

.[-k kookfile ]

[-k kookfile ]

.[-k kookfile , ]

[-k kookfile ]

.[objfil [corfil ] ]

[objfil [corfil ] ]

.[-c objfil [corfil , ] ]

[-c objfil [corfil ] ]

.[word1 word2]

[word1 word2]

The `.] ' and `.[macros: '

.Oo
.Op Fl k Ar kilobytes
.Op Fl i Ar interval
.Op Fl c Ar count
.Oc

Produce: [[-k kilobytes ] [-i interval ] [-c count ] ]

The macros `.[,] ' `.] ' and `.[are ' parsed and are callable.

Pathnames

Usage: .pathname [ .,:;()[]?! ]

./usr/share

/usr/share

./tmp/fooXXXXX )

/tmp/fooXXXXX )

The `.macro ' is parsed and is callable.

Variables

Usage: .variable ... [ .,:;()[]?! ]

.count

count

.settimer

settimer

.int *prt ):

int *prt )

.char s ] ) ),

char s ] ) )

It is an error to call `.without ' any arguments. The `.macro ' is parsed and is callable.

Manual Page Cross References

Usage: .man_page[1,...,8][ .,:;()[]?! ]

.mdoc

mdoc

.mdoc

mdoc,

.mdoc(7)

mdoc(7)

.mdoc(7)))

mdoc(7))),

The `.macro ' is parsed and is callable. It is an error to call `.without ' any arguments.

GENERAL TEXT DOMAIN

AT&T Macro

Usage: .At [v6 | v7 | 32v | V.1 | V.4] ... [ .,:;()[]?! ]

.At

AT&T System

.AT&T System v6 .

AT&T System v6 .

The `.AT&T System ' macro is not parsed and not callable It accepts at most two arguments.

BSD Macro

Usage: .BSD [Version/release] ... [ .,:;()[]?! ]

.Bx

BSD

.BSD 4.3 .

BSD 4.3

The `.BSD macro ' is parsed and is callable.

FreeBSD Macro

Usage: .Fx Version.release ... [ .,:;()[]?! ]

.Fx 2.2 .

Fx 2.2 .

The `.Fx macro ' is not parsed and not callable It accepts at most two arguments.

UNIX Macro

Usage: .UNIX

.Ux

UNIX

The `.UNIX ' macro is parsed and is callable.

Enclosure and Quoting Macros

Quote         Close   Open   Function        Result .Aq    .Ac     .Ao     Angle Bracket Enclosure<string>
.Bq     .Bc     .Bo     Bracket Enclosure       [string]
.Dq     .Dc     .Do     Double Quote    ``string''
        .Ec     .Eo     Enclose String (in XX)  XXstringXX
.Pq     .Pc     .Po     Parenthesis Enclosure   (string)
.Ql                     Quoted Literal  `st' or string
.Qq     .Qc     .Qo     Straight Double Quote   "string"
.Sq     .Sc     .So     Single Quote    `string'

Except for the irregular macros noted below, all of the quoting macros are parsed and callable. All handle punctuation properly, as long as it is presented one character at a time and separated by spaces. The quoting macros examine opening and closing punctuation to determine whether it comes before or after the enclosing string This makes some nesting possible.

.Ec , .Eo These macros expect the first argument to be the

opening and closing strings respectively.

.`The'

quoted literal macro behaves differently for troff than nroff. If formatted with nroff, a quoted literal is always quoted. If formatted with troff, an item is quoted only if the width of the item is less than three constant width characters. This is to make short strings more visible where the font change to literal (constant width) is less noticeable.

.The prefix macro is not callable, but it is parsed:

.( Fa name2

becomes ( Fa name2

The `.(no ' space) macro performs the analogous suffix function.

Examples of quoting:

.Aq Aq

.Aq ctype.h ),

Aq Ar ctype.h ) ,

.Bq Bq

.Bq Greek , French .

Bq Em Greek , French .

.````

.``string abc .''

'' ''

``string abc''

.``'^[A-Z]'''

``'^[A-Z]'''

.`man'

mdoc `man' mdoc

.Qq Qq

.Qq string ) ,

Qq string ) ,

.Qq string ),

Qq string Ns ),

.``

.`string'

' '

`string'

For a good example of nested enclosure macros, see the `.[option] ' macro. It was created from the same underlying enclosure macros as those presented in the list above. The `. ' and `. ' extended argument list macros were also built from the same underlying routines and are a good example of -mdoc macro usage at its worst.

No-[or Normal Text Macro]

Space Macro

.[-I directory ]

produces [-I directory ]

Note: the `.macro ' always invokes the `.macro ' after eliminating the space unless another macro name follows it. The macro `.is ' parsed and is callable.

Section Cross References

.Sx FILES

Sx FILES

References and Citations

.Rs

Reference Start. Causes a line break and begins collection of reference information until the reference end macro is read.

.Re

Reference End. The reference is printed.

.%A

Reference author name, one name per invocation.

.%B

Book title.

.%C

City/place.

.%D

Date.

.%J

Journal name.

.%N

Issue number.

.%O

Optional information.

.%P

Page number.

.%R

Report name.

.%T

Title of article.

.%V

Volume(s).

The macros beginning with `%' are not callable, and are parsed only for the trade name macro which returns to its caller. (And not very predictably at the moment either.) The purpose is to allow trade names to be pretty printed in troffNs/NsXrditroff output.

Return Values

Usage: .Rv [-std function]

`.Rv -std ' atexit will generate the following text:

Rv -std atexit

The -std option is valid only for manual page sections 2 and 3.

Trade Names (or Acronyms and Type Names)

Usage: .symbol ... [ .,:;()[]?! ]

.DEC

DEC

.ASCII

ASCII

The `.macro ' is parsed and is callable by other macros.

Extended Arguments

Here is an example of `. ' using the space mode macro to turn spacing off:

.Sm off
.It Xo Sy I Ar operation
.No \en Ar count No \en
.Xc
.Sm on

Produces

I operation \n count \n

.Sh PAGE STRUCTURE DOMAIN