.’ (dot character) at the beginning of a line followed by the two character name for the macro. Arguments may follow the macro separated by spaces. It is the dot character at the beginning of the line which causes troff(1) to interpret the next two characters as a macro name. To place a ‘
.’ (dot character) at the beginning of a line in some context other than a macro invocation, precede the ‘
.’ (dot) with the ‘
\&’ escape sequence. The ‘
\&’ translates literally to a zero width space, and is never displayed in the output. 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 Extensions). A few macros handle quoted arguments (see 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, ‘
.Op’, may call the flag and argument macros, ‘
Fl’ and ‘
Ar’, to specify an optional flag with an argument:
.Op Fl s Ar bytes
.Op \&Fl s \&Ar bytes
Fl’ and ‘
Ar’ 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.
.Fn’ expects the first argument to be the name of a function and any remaining arguments to be function parameters. As ANSI C stipulates the declaration of function parameters in the parenthesized parameter list, each parameter is guaranteed to be at minimum a two word string. For example, int foo. 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:
\’, 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’
.Fn fetch \*qchar *str\*q’
\’ or quotes were omitted, ‘
.Fn’ would see three arguments and the result would be:
\&’ escape character. For example, ‘
\n’, are handled by replacing the ‘
\’ with ‘
\e’ (e.g. ‘
\en’) to preserve the backslash.
.\" 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 VALUES .\" 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
.Dt); the document date, the operating system the man page or subject source is developed or modified for, and the man page title (in upper case) along with the section of the manual the page belongs in. These macros identify the page, and are discussed below in TITLE MACROS. The remaining items in the template are section headers (
.Sh); of which mdoc.samples : tutorial sampler pro psaní BSD příruček s -mdoc , STRUČNĚ and POPIS / INSTRUKCE are mandatory. The headers are discussed in PAGE STRUCTURE DOMAIN, after presentation of MANUAL DOMAIN. Several content macros are used to demonstrate page layout macros; reading about content macros before page layout macros is recommended.
.Dt DOCUMENT_TITLE section# [volume]
||UNIX Ancestral Manual Documents|
||UNIX System Manager's Manual|
||UNIX Reference Manual|
||UNIX Programmer's Manual|
URMfor sections 1, 6, and 7;
SMMfor section 8;
PRMfor sections 2, 3, 4, and 5.
.Os operating_system release#
.Os BSD 4.3
.Os FreeBSD 2.2
.Os CS Department
.Os’ 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 ‘
.Os’ macro is not present, the bottom left corner of the page will be ugly.
.Dd month day, year
January 25, 1989
.Va’ 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 STRUČNĚ command line might be displayed as:
.Nm filter .Op Fl flag .Ar infile outfile
Ar’ 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
.Bk’ and ‘
.Ek’ macros are explained in Keeps.
.Nm’, and ‘
.Pa’ differ only when called without arguments; ‘
.Fn’ and ‘
.Xr’ impose an order on their argument lists and the ‘
.Op’ and ‘
.Fn’ macros have nesting limitations. All content macros are capable of recognizing and properly handling punctuation, provided each punctuation character is separated by a leading space. If an request is given:
.Li sptr, ptr),
.Li sptr , ptr ) ,
\&’. 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:
\&’. Typical syntax is shown in the first content macro displayed below, ‘
Usage: .Ad address ...
.Ad’ without arguments. ‘
.Ad’ is callable by other macros and is parsed.
.An’ macro is used to specify the name of the author of the item being documented, or the name of the author of the actual manual page. Any remaining arguments after the name information are assumed to be punctuation.
Usage: .An author_name
.An’ macro is parsed and is callable. It is an error to call ‘
.An’ without any arguments.
.Ar’ argument macro may be used whenever a command line argument is referenced.
Usage: .Ar argument ...
.Ar’ is called without arguments ‘
file ...’ is assumed. The ‘
.Ar’ macro is parsed and is callable.
.Cd’ macro is used to demonstrate a config(8) declaration for a device interface in a section four manual. This macro accepts quoted arguments (double quotes only).
.Cd device le0 at scode?’.
.Fl’ (flag) command with the exception the ‘
.Cm’ macro does not assert a dash in front of every argument. Traditionally flags are marked by the preceding dash, some commands or subsets of commands do not use them. Command modifiers may also be specified in conjunction with interactive commands such as editor commands. See Flags.
Usage: .Dv defined_variable ...
.Dv’ without arguments. ‘
.Dv’ is parsed and is callable.
.Er’ errno macro specifies the error return value for section two library routines. The second example below shows ‘
.Er’ used with the ‘
.Bq’ general text domain macro, as it would be used in a section two manual page.
Usage: .Er ERRNOTYPE ...
.Er’ without arguments. The ‘
.Er’ macro is parsed and is callable.
.Ev’ macro specifies an environment variable.
Usage: .Ev argument ...
.Ev’ without arguments. The ‘
.Ev’ macro is parsed and is callable.
.Fa’ macro is used to refer to function arguments (parameters) outside of the STRUČNĚ section of the manual or inside the STRUČNĚ section should a parameter list be too long for the ‘
.Fn’ macro and the enclosure macros ‘
.Fo’ and ‘
.Fc’ must be used. ‘
.Fa’ may also be used to refer to structure members.
Usage: .Fa function_argument ...
.Fa’ without arguments. ‘
.Fa’ is parsed and is callable.
.Fd’ macro is used in the STRUČNĚ section with section two or three functions. The ‘
.Fd’ macro does not call other macros and is not callable by other macros.
Usage: .Fd include_file (or defined variable)
.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.
.Fl’ macro handles command line flags. It prepends a dash, ‘
-’, to the flag. For interactive command flags, which are not prepended with a dash, the ‘
.Cm’ (command modifier) macro is identical, but without the dash.
Usage: .Fl argument ...
.Fl’ macro without any arguments results in a dash representing stdin/stdout. Note that giving ‘
.Fl’ a single dash, will result in two dashes. The ‘
.Fl’ macro is parsed and is callable.
Usage: .Fn [type] function [[type] parameters ... ]
.Fn strlen ) ,
.Fn \*qint align\*q \*qconst * char *sptrs\*q,
.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
.Fo’ and ‘
.Fc’ macros are parsed and are callable. In the STRUČNĚ section, the function will always begin at the beginning of line. If there is more than one function presented in the STRUČNĚ 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. STRUČNĚ section. It may be used anywhere else in the man page without problems, but its main purpose is to present the function type in kernel normal form for the STRUČNĚ of sections two and three (it causes a line break allowing the function name to appear on the next line).
Usage: .Ft type ...
.Ft struct stat
.Ft’ request is not callable by other macros.
.Ic’ macro designates an interactive or internal command.
Usage: .Ic argument ...
.Ic’ without arguments. The ‘
.Ic’ macro is parsed and is callable.
.Nm’ macro is used for the document title or subject name. It has the peculiarity of remembering the first argument it was called with, which should always be the subject name of the page. When called without arguments, ‘
.Nm’ regurgitates this initial name for the sole purpose of making less work for the author. Note: a section two or three document function name is addressed with the ‘
.Nm’ in the mdoc.samples : tutorial sampler pro psaní BSD příruček s -mdoc section, and with ‘
.Fn’ in the STRUČNĚ and remaining sections. For interactive commands, such as the ‘
while’ command keyword in csh(1), the ‘
.Ic’ macro should be used. While the ‘
.Ic’ is nearly identical to ‘
.Nm’, it can not recall the first argument it was invoked with.
Usage: .Nm argument ...
.Nm’ macro is parsed and is callable.
.Op’ macro places option brackets around the any remaining arguments on the command line, and places any trailing punctuation outside the brackets. The macros ‘
.Oc’ and ‘
.Oo’ may be used across one or more lines.
Usage: .Op options ...