*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->OpenBSD man pages -> mdoc.samples (7)              



NAME    [Toc]    [Back]

     mdoc.samples - tutorial sampler for writing OpenBSD  manuals
with -mdoc

SYNOPSIS    [Toc]    [Back]

     nroff -TNAME -mandoc file

DESCRIPTION    [Toc]    [Back]

     A tutorial sampler for writing OpenBSD manual pages with the
-mdoc macro
     package, a content-based and domain-based formatting package
     troff(1).   Its  predecessor,  the -man package (see man(7))
addressed page
     layout, leaving the manipulation of fonts and other typesetting details
     to the individual author.

     In  -mdoc,  page  layout  macros  make up the page structure
domain which consists
 of macros for titles, section  headers,  displays  and
lists.  Essentially
 items which affect the physical position of text on a
     page.  In addition to the page structure domain,  there  are
two more domains:
 the manual domain and the general text domain.

     The  general  text domain is defined as macros which perform
tasks such as
     quoting or emphasizing pieces of text.  The manual domain is
defined as
     macros that are a subset of the day to day informal language
used to describe
 commands, routines and related OpenBSD files.  Macros
in the manual
  domain  handle command names, command line arguments and
options, function
 names, function parameters, pathnames, variables, cross
     to  other  manual pages, and so on.  These domain items have
value for both
     the author and the future user of the manual  page.   It  is
hoped the consistency
  gained  across  the manual set will provide easier
translation to
     future documentation tools.

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

GETTING STARTED    [Toc]    [Back]

     Since a tutorial document is normally read when a person desires to use
     the  material immediately, the assumption has been made that
the user of
     this document may be impatient.  The material  presented  in
the remainder
     of this document is outlined as follows:

                      Macro Usage.
                      Passing Space Characters in an Argument.
                      Trailing  Blank  Space  Characters (a warning).
                      Escaping Special Characters.
                      Dashes and Hyphens.

           2.   THE ANATOMY OF A MAN PAGE
                      A manual page template.

           3.   TITLE MACROS

                      What's in a name....
                      General Syntax.

           5.   MANUAL DOMAIN
                      Command Modifier.
                      Configuration  Declarations  (section  four
                      Defined Variables.
                      Environment Variables.
                      Errno (section two only).
                      Exit Values.
                      Functions (library routines).
                      Function Argument.
                      Function Declaration.
                      Function Types.
                      Interactive Commands.
                      Return Values.
                      Cross References.

           6.   GENERAL TEXT DOMAIN
                      AT&T Macro.
                      BSD Macro.
                      BSDI Macro.
                      OpenBSD/FreeBSD/NetBSD Macros.
                      UNIX Macro.
                      Emphasis Macro.
                      Font mode.
                      Enclosure and Quoting Macros
                                  Angle  Bracket Quote/Enclosure.
                                  Bracket Quote/Enclosure.
                                  Double Quote macro/Enclosure.
                                  Enclose String macro.
                                  Parenthesis Quote/Enclosure.
                                  Quoted Literal macro/Enclosure.
                                  Straight Double Quote macro/Enclosure.
                                  Single Quote macro/Enclosure.
                      No-Op or Normal Text Macro.
                      No Space Macro.
                      Prefix Macro.
                      Section Cross References.
                      Space Mode Macro.
                      Symbolic Macro.
                      Mathematical Symbols.
                      References and Citations.
                      Trade Names (or Acronyms and Type Names).
                      Extended Arguments.
                      Miscellaneous Macros.

                      Section Headers.
                      Paragraphs and Line Spacing.
                      Lists and Columns.

           8.   PREDEFINED STRINGS

           9.   DIAGNOSTICS


           11.  FILES

           12.  SEE ALSO

           13.  BUGS


     The -mdoc package attempts to simplify the process of  writing a man page.
     Theoretically,  one  should  not have to learn the dirty details of troff(1)
     to use -mdoc; however, there are a few limitations which are
     and  best  gotten  out of the way.  And, too, be forewarned,
this package is
     not fast.

   Macro Usage    [Toc]    [Back]
     As in troff(1), a macro is called  by  placing  a  `.'  (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
     precede the `.' (dot) with the `' escape sequence.   The  `'
     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  Extended Arguments).  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:

           [-s bytes]         is produced by .Op Fl s Ar bytes

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

           [Fl s Ar bytes]    is produced by .Op Fl s Ar bytes

     Here  the  strings  `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.

   Passing Space Characters in an Argument    [Toc]    [Back]
     Sometimes it is desirable to give as one argument  a  string
containing one
     or  more  blank  space characters.  This may be necessary to
defeat the nine
     argument limit or to specify arguments to macros  which  expect particular
     arrangement of items in the argument list.  For example, the
     macro `.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
     list,  each  parameter is guaranteed to be at minimum a twoword 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(1).  It is not  expensive for
     groff(1)  but  for the sake of portability, has been limited
to the following
 macros which need it the most:

           Bl    Begin list (for the width specifier).
           Cd    Configuration declaration (section 4  SYNOPSIS).
           Em    Emphasized text.
           Fn    Functions (sections two and four).
           It    List items.
           Li    Literal text.
           Sy    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.

           fetch(char *str)  is created by `.Fn fetch char *str'

           fetch(char *str)  can also be created  by  `.Fn  fetch
"char *str"'

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

           fetch(char, *str)

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

   Trailing Blank Space Characters    [Toc]    [Back]
     Troff  can  be confused by blank space characters at the end
of a line.  It
     is a wise preventive measure to globally  remove  all  blank
spaces from
     <blank-space><end-of-line>  character sequences.  Should the
need arise to
     force a blank character at the end of  a  line,  it  may  be
forced with an
     unpaddable space and the `' escape character.  For example,
     `string '.

   Escaping Special Characters    [Toc]    [Back]
     Special  characters  like the newline character `0, are handled by replacing
 the `' with `\' (e.g., `\n') to preserve  the  backslash.

   Dashes and Hyphens    [Toc]    [Back]
     In  typography  there  are  three types of dashes of various
width: the hyphen
 (-), the en-dash (-), and the  em-dash  (--).   Hyphens
are used for
     adjectives; to separate the two parts of a compound word; or
to separate
     a word across two successive lines of text.  The hyphen does
not need to
     be escaped:


     The en-dash is used to separate the two elements of a range,
or can be
     used the same way as colons, semi-colons or parentheses.  It
is also used
     as the mathematical minus symbol.  It should be escaped with
the `'

           pp. 95-97.
           Go away - or else!

     Note: hyphens and en-dashes will look identical under normal
ASCII output.
   Other  formats,  such as PostScript, render them correctly, with differing

     The em-dash is used to mark a parenthesis -- like this -- or
an interruption.
  It should be written as


THE ANATOMY OF A MAN PAGE    [Toc]    [Back]

     The  body  of  a man page is easily constructed from a basic
template found
     in the file /usr/share/misc/mdoc.template.

           .Dd Month DD, YYYY
           .Dt NAME SECTION#
           .Sh NAME
           .Nm program
           .Nd one line about what it does
           .Sh SYNOPSIS
           .Nm program
           .Op Fl abc
           .Sh DESCRIPTION
           utility processes files ...

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

     The remaining items in  the  template  are  section  headers
(.Sh); of which
     NAME,  SYNOPSIS  and DESCRIPTION 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.

TITLE MACROS    [Toc]    [Back]

     The title macros are the first portion of the page structure
domain, but
     are  presented  first and separate for someone who wishes to
start writing
     a man page yesterday.  Three  header  macros  designate  the
document title
     or  manual page title, the operating system, and the date of
     These macros are called once at the very  beginning  of  the
document and
     are used to construct the headers and footers only.

     .Dd month day, year
             The date should be written formally:

                   January 25, 1989

     .Dt DOCUMENT_TITLE section# [volume]
             The  document  title  is the subject of the man page
and must be in
             CAPITALS due to troff limitations.  If omitted, `UNTITLED' is
             used.   The  section  number  may be a number in the
range 1-9, or
             `unass', `draft', or `paper'.  The following section
numbers are

                   1    General commands (tools and utilities)
                   2    System calls and error numbers
                   3    Libraries
                   3p   perl(1) programmer's reference guide
                   4    Device drivers
                   5    File formats
                   6    Games
                   7    Miscellaneous
                   8    System maintenance and operation commands
                   9    Kernel internals

             The volume  title  is  optional;  if  specified,  it
should be one of
             the following:

                   AMD      OpenBSD Ancestral Manual Documents
                   IND      OpenBSD Manual Master Index
                   KM       OpenBSD Kernel Manual
                   LOCAL    OpenBSD Local Manual
                   PRM      OpenBSD Programmer's Manual
                   PS1       OpenBSD  Programmer's  Supplementary
                   SMM      OpenBSD System Manager's Manual
                   URM      OpenBSD Reference Manual
                   USD      OpenBSD  User's  Supplementary  Documents

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

             If  the third argument to `.Dt' is instead a machine
             it will be  displayed,  surrounded  by  parentheses,
next to the volume
  title.   This is useful for pages specific only
to a particular
 architecture.  The architectures  currently  defined are:

                   alpha,  amd64, amiga, arc, arm32, atari, cats,
                   hppa, i386, luna88k, mac68k, macppc,  mvme68k,
                   mvmeppc,  pc532,  pegasos,  pmax,  sgi, sparc,
                   sun3, tahoe, vax, x68k

     .Os operating_system release#
             The name of the operating system should be a  common
             e.g.,  OpenBSD  or  ATT.   The release should be the
standard release
             nomenclature for the system  specified,  e.g.,  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:

                   .Os OpenBSD 3.4

             or for a locally produced set

                   .Os "CS Department"

             The OpenBSD default, `.Os' without an  argument,  is
defined as
             OpenBSD <latest release#> 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.


   What's in a name...
     The  manual  domain  macro names are derived from the day to
day informal
     language used to describe commands, subroutines and  related
     Slightly  different  variations of this language are used to
describe the
     three different aspects of writing a man page.  First, there
is the description
  of  -mdoc macro request usage.  Second is the description of a
     UNIX command with -mdoc macros and third, the description of
a command to
     a user in the verbal sense; that is, discussion of a command
in the text
     of a man page.

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

           .Va argument1 argument2 ... argument9

     The  `.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
     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
     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
                 [-I directory]  [-j  max_jobs]  [variable=value]
[target ...]

     Here  one  might talk about the command make and qualify the
     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  `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
           .Bk -words
           .Op Fl I Ar directory
           .Op Fl j Ar max_jobs
           .Op Ar variable=value
           .Op Ar target ...

     The `.Bk' and `.Ek' macros are explained in Keeps.

   General Syntax    [Toc]    [Back]
     The  manual  domain  and  general text domain macros share a
similar syntax
     with a few minor deviations: `.Ar', `.Fl', `.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
     All  content  macros are capable of recognizing and properly
handling punctuation,
 provided each punctuation character is separated by
a leading
     space.  If a request is given:

           .Ar sptr, ptr),

     The result is:

           sptr, ptr),

     The  punctuation  is not recognized and everything is output
in the font
     used by `.Ar'.  If the punctuation is separated by a leading

           .Ar sptr , ptr ) ,

     The result is:

           sptr, ptr),

     The  punctuation  is now recognized and is output in the default font distinguishing
 it from the argument  strings.   To  remove  the
special meaning
     from a punctuation character escape it with `'.  The following punctuation
 characters are recognised by -mdoc:

                 { . , ; : ? ! ( ) [ ]}

     Troff is limited as a macro  language,  and  has  difficulty
when presented
     with a string containing a member of the mathematical, logical or quotation

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

     The problem is that troff(1) 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

MANUAL DOMAIN    [Toc]    [Back]

   Address Macro
     The address macro identifies an  address  construct  of  the
form addr1[,addr2[,addr3]].

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

                   .Ad addr1           addr1
                   .Ad addr1 .         addr1.
                   .Ad addr1 , file2   addr1, file2
                   .Ad f1 , f2 , f3 :  f1, f2, f3:
                   .Ad addr ) ) ,      addr)),

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

   Argument Macro    [Toc]    [Back]
     The `.Ar' argument macro may be used whenever a command line
argument is

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

                    .Ar              file ...
                    .Ar file1        file1
                    .Ar file1 .      file1.
                    .Ar file1 file2  file1 file2
                    .Ar f1 f2 f3 :   f1 f2 f3:
                    .Ar file ) ) ,   file)),

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

   Author Name    [Toc]    [Back]
     The `.An' macro is used to specify the name of the author of
the utility,
     or the name of the author of the man page.

           Usage: .An author ... { . , ; : ? ! ( ) [ ]}

           .An John Smith        John Smith
           .An John Smith ,      John Smith,
           .An John Smith Aq john@email.address
                                 John Smith <john@email.address>

     The `.An' macro is parsed, but is not callable.

   Command Modifier    [Toc]    [Back]
     The  command  modifier is identical to the `.Fl' (flag) command with the
     exception that 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.

   Configuration Declaration (section four only)    [Toc]    [Back]
     The `.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).

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

   Defined Variables    [Toc]    [Back]
     A  variable which is defined in an include file is specified
by the macro

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

                   .Dv TIOCGPGRP )     TIOCGPGRP)

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

   Environment Variables    [Toc]    [Back]
     The `.Ev' macro specifies an environment variable.

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

                   .Ev DISPLAY        DISPLAY
                   .Ev PATH .         PATH.
                   .Ev PRINTER ) ) ,  PRINTER)),

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

   Errno (section two only)    [Toc]    [Back]
     The  `.Er'  errno macro specifies the error return value for
section two
     library routines.  The third 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 ENOENT      ENOENT
                   .Er ENOENT ) ;  ENOENT);
                   .Bq Er ENOTDIR  [ENOTDIR]

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

   Exit Values (sections one, six, and eight only)
     The  `.Ex' macro displays a standardised text concerning the
exit values
     of applications.  The `.Ex' macro does not call other macros
and is not
     callable  by  other  macros.   The `-std' flag is purely for
     purposes, and must be included.

           Usage: .Ex [-std] utility

     For example, `.Ex -std cat' produces:

     The cat utility exits 0 on success, and >0 if an  error  occurs.

   Flags    [Toc]    [Back]
     The  `.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

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

                   .Fl           -
                   .Fl cfv       -cfv
                   .Fl cfv .     -cfv.
                   .Fl s v t     -s -v -t
                   .Fl - ,       --,
                   .Fl xyz ) ,   -xyz),

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

   Functions (library routines)    [Toc]    [Back]
     The `.Fn' macro is modeled on ANSI C conventions.

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

     .Fn getchar                             getchar()
     .Fn strlen ) ,                          strlen()),
     .Fn  "int  align"  "const * char *sptrs",  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

     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:

           .Ft int
           .Fo 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"


           int res_mkquery(int op, char *dname,  int  class,  int
           char  *data,  int  datalen,  struct  rrec *newrr, char
*buf, int buflen)

     The `.Fo' and `.Fc' macros are parsed and are callable.   In
     section,  the function will always begin at the beginning of
line.  If
     there is more than one function presented  in  the  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
     line lengths and may split across  a  newline  ungracefully.
This will be
     fixed in the near future.

   Function Argument    [Toc]    [Back]
     The  `.Fa' macro is used to refer to function arguments (parameters) outside
 of the SYNOPSIS section of the  manual  or  inside  the
SYNOPSIS 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 d_namlen ) ) ,  d_namlen)),
                   .Fa iov_len         iov_len

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

   Function Declaration    [Toc]    [Back]
     The `.Fd' macro is used in the SYNOPSIS section with section
two, three,
     and nine functions.  The `.Fd' macro  does  not  call  other
macros and is
     not callable by other macros.

           Usage: .Fd include_file (or defined variable)

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

   Function Type    [Toc]    [Back]
     This macro is intended for the SYNOPSIS section.  It may  be
used anywhere
     else  in  the man page without problems, but in the SYNOPSIS
section it
     causes a line break after its use.  Its main purpose  is  to
present the
     function  type  in  kernel  normal  form of a section two or
three man page by
     forcing the function name to appear on the next line.

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

                   .Ft struct stat  struct stat

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

   Interactive Commands    [Toc]    [Back]
     The `.Ic' macro designates an interactive or  internal  command.

           Usage: .Ic command ... { . , ; : ? ! ( ) [ ]}

                   .Ic :wq                  :wq
                   .Ic do while {...}       do while {...}
                   .Ic setenv , unsetenv    setenv, unsetenv

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

   Includes    [Toc]    [Back]
     The `.In' macro is used in the SYNOPSIS section with section
two, three,
     and  nine header files.  The `.In' macro does not call other
macros and is
     not callable by other macros.

           Usage: .In include_file

                   .In stdio.h      #include <stdio.h>

     In the SYNOPSIS section a `.In' 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 include file.

   Literals    [Toc]    [Back]
     The  `.Li' literal macro may be used for special characters,
variable constants,
 anything which should be displayed as  it  would  be

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

                   .Li \n
                   .Li M1 M2 M3 ;   M1 M2 M3;
                   .Li cntrl-D ) ,  cntrl-D),
                   .Li 1024 ...     1024 ...

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

   Name Macro    [Toc]    [Back]
     The  `.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.  However, `.Nm' should
always be given
     an argument when used in the SYNOPSIS section.

     Note: a section two or three document function name  is  addressed with
     `.Nm'  in  the  NAME section, and with `.Fn' in the SYNOPSIS
and remaining
     sections.  For interactive commands,  such  as  the  `while'
command keyword
     in  csh(1),  the `.Ic' macro should be used.  While `.Ic' is
nearly identical
 to `.Nm', it can not recall the first  argument  it  was
invoked with.

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

                   .Nm mdoc.samples    mdoc.samples
                   .Nm                 mdoc.samples
                   .Nm .               mdoc.samples.
                   .Nm -mdoc          -mdoc
                   .Nm foo ) ) ,       foo)),

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

   Options    [Toc]    [Back]
     The  `.Op' macro places option brackets around 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 ... { . , ; : ? ! ( ) [ ]}

           .Op                                []
           .Op Fl k                           [-k]
           .Op Fl k ) .                       [-k]).
           .Op Fl k Ar kookfile               [-k kookfile]
           .Op Fl k Ar kookfile ,             [-k kookfile],
           .Op Ar objfil Op Ar corfil         [objfil [corfil]]
           .Op Fl  c  Ar  objfil  Op  Ar  corfil  ,   [-c  objfil
           .Op word1 word2                    [word1 word2]

     The `.Oc' and `.Oo' macros:

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

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

     The  macros  `.Op',  `.Oc'  and  `.Oo'  are  parsed  and are

   Pathnames    [Toc]    [Back]
     The `.Pa' macro formats path or file names.

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

                   .Pa /usr/share         /usr/share
                   .Pa /tmp/fooXXXXX ) .  /tmp/fooXXXXX).

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

   Return Values (sections two and three only)    [Toc]    [Back]
     The `.Rv' macro displays a standardised text concerning  the
return values
     of  functions.   The  `.Rv' macro does not call other macros
and is not
     callable by other macros.  The `-std'  flag  is  purely  for
     purposes, and must be included.

           Usage: .Rv [-std] function

     For example, `.Rv -std open' produces:

     The  open() function returns the value 0 if successful; otherwise the value
 -1 is returned and the global variable errno  is  set  to
indicate the

   Standards    [Toc]    [Back]
     The `.St' macro replaces standard abbreviature with its formal name.

           Usage: .St abbreviature

     Available pairs for ``Abbreviature/Formal Name'' are:

           -p1003.1-88     IEEE Std 1003.1-1988 (``POSIX'')
           -p1003.1-90     IEEE Std 1003.1-1990 (``POSIX'')
           -p1003.1-96     ISO/IEC 9945-1:1996 (``POSIX'')
           -p1003.1-2001   IEEE Std 1003.1-2001 (``POSIX'')
           -p1003.1-2003   IEEE Std 1003.1-2003 (``POSIX'')
           -p1003.1        IEEE Std 1003.1 (``POSIX'')
           -p1003.1b       IEEE Std 1003.1b (``POSIX'')
           -p1003.1b-93    IEEE Std 1003.1b-1993 (``POSIX'')
           -p1003.1c-95    IEEE Std 1003.1c-1995 (``POSIX'')
           -p1003.1g-2000  IEEE Std 1003.1g-2000 (``POSIX'')
           -p1003.2-92     IEEE Std 1003.2-1992 (``POSIX.2'')
           -p1387.2-95     IEEE Std 1387.2-1995 (``POSIX.7.2'')
           -p1003.2        IEEE Std 1003.2 (``POSIX.2'')
           -p1387.2        IEEE Std 1387.2 (``POSIX.7.2'')
           -isoC-90        ISO/IEC 9899:1990 (``ISO C90'')
           -isoC-amd1      ISO/IEC 9899/AMD1:1995 (``ISO C90'')
           -isoC-tcor1     ISO/IEC 9899/TCOR1:1994 (``ISO C90'')
           -isoC-tcor2     ISO/IEC 9899/TCOR2:1995 (``ISO C90'')
           -isoC-99        ISO/IEC 9899:1999 (``ISO C99'')
           -ansiC          ANSI X3.159-1989 (``ANSI C'')
           -ansiC-89       ANSI X3.159-1989 (``ANSI C'')
           -ansiC-99       ANSI/ISO/IEC 9899-1999 (``ANSI C99'')
           -ieee754        IEEE Std 754-1985
           -iso8802-3      ISO 8802-3: 1989
           -xpg3            X/Open  Portability  Guide  Issue   3
           -xpg4             X/Open  Portability  Guide  Issue  4
           -xpg4.2         X/Open  Portability  Guide  Issue  4.2
           -xpg4.3          X/Open  Portability  Guide  Issue 4.3
           -xbd5           X/Open  System  Interface  Definitions
Issue 5
           -xcu5            X/Open Commands and Utilities Issue 5
           -xsh5           X/Open System Interfaces  and  Headers
Issue 5
           -xns5            X/Open  Networking  Services  Issue 5
           -xns5.2d2.0     X/Open Networking Services  Issue  5.2
Draft 2.0
           -xcurses4.2       X/Open  Curses  Issue  4  Version  2
           -susv2          Version 2 of the Single UNIX  Specification
           -susv3           Version 3 of the Single UNIX Specification
           -svid4          System V Interface Definition,  Fourth

   Variable Types    [Toc]    [Back]
     The  `.Vt'  macro may be used whenever a type is referenced.
In the
     SYNOPSIS section, it causes a line break  (useful  for  oldstyle variable

           Usage: .Vt <type> ... { . , ; : ? ! ( ) [ ]}

                   .Vt extern char *optarg;  extern char *optarg;
                   .Vt FILE *                FILE *

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

   Variables    [Toc]    [Back]
     Generic variable reference:

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

                   .Va count           count
                   .Va settimer,       settimer,
                   .Va int *prt ) :    int *prt):
                   .Va char s ] ) ) ,  char s])),

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

   Manual Page Cross References    [Toc]    [Back]
     The `.Xr' macro expects the first argument to  be  a  manual
page name, and
     the  second  argument,  if it exists, to be either a section
number or punctuation.
  Any remaining arguments are assumed to be punctuation.

           Usage: .Xr man_page [1,...,9] { . , ; : ? ! ( ) [ ]}

                   .Xr mdoc          mdoc
                   .Xr mdoc ,        mdoc,
                   .Xr mdoc 7        mdoc(7)
                   .Xr mdoc 7 ) ) ,  mdoc(7))),

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

GENERAL TEXT DOMAIN    [Toc]    [Back]

   AT&T Macro
           Usage: .At [v6 | v7 | 32v | V.1 | V.4] ...

                   .At         AT&T UNIX
                   .At v6      Version 6 AT&T UNIX

     The `.At' macro is not parsed and not callable.  It  accepts
at most two
     arguments.  It cannot currently handle punctuation.

   BSD Macro    [Toc]    [Back]
           Usage:  .Bx  [Version/release] ... { . , ; : ? ! ( ) [

                   .Bx          BSD
                   .Bx 4.3 .    4.3BSD.

     The `.Bx' macro is parsed, but is not callable.

   BSDI Macro    [Toc]    [Back]
           Usage: .Bsx [Version/release] ... { . , ; : ? ! ( )  [

                   .Bsx          BSDI BSD/OS
                   .Bsx 3.0 .    BSDI BSD/OS 3.0.

     The `.Bsx' macro is parsed, but is not callable.

   OpenBSD/FreeBSD/NetBSD Macros
           Usage:  .Ox  [Version/release] ... { . , ; : ? ! ( ) [

                   .Ox          OpenBSD
                   .Ox 2.7 .    OpenBSD 2.7.

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

                   .Fx          FreeBSD
                   .Fx 4.0 .    FreeBSD 4.0.

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

                   .Nx          NetBSD
                   .Nx 1.5 .    NetBSD 1.5.

     The `.Ox', `.Fx', and `.Nx' macros are not  parsed  and  are
not callable.

   UNIX Macro    [Toc]    [Back]
           Usage: .Ux ... { . , ; : ? ! ( ) [ ]}

                   .Ux          UNIX

     The `.Ux' macro is parsed, but is not callable.

   Emphasis Macro    [Toc]    [Back]
     Text  may  be  stressed  or emphasized with the `.Em' macro.
The usual font
     for emphasis is italic.

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

                   .Em does not          does not
                   .Em exceed 1024 .     exceed 1024.
                   .Em vide infra ) ) ,  vide infra)),

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

   Font Mode    [Toc]    [Back]
     The  `.Bf'  font  mode  must end with the `.Ef' macro (which
takes no arguments).
  Font modes may be nested within other font modes.

           Usage: .Bf font mode

     Font mode must be one of the following:

           Em | -emphasis  Same as if the `.Em'  macro  was  used
for the entire
                           block of text.
           Li  |  -literal    Same as if the `.Li' macro was used
for the entire
                           block of text.
           Sy | -symbolic  Same as if the `.Sy'  macro  was  used
for the entire
                           block of text.

   Enclosure and Quoting Macros    [Toc]    [Back]
     The  concept of enclosure is similar to quoting.  The object
being to enclose
 one or more strings between a pair of characters  like
quotes or
     parentheses.   The  terms quoting and enclosure are used interchangeably
     throughout this document.  Most of the  one  line  enclosure
macros end in
     small  letter `q' to give a hint of quoting, but there are a
few irregularities.
  For each enclosure macro there is also a pair  of
open and
     close  macros which end in small letters `o' and `c' respectively.  These
     can be used across one or more lines of text and while  they
have nesting
     limitations, the one line quote macros can be used inside of

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

     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

     .Eo, .Ec  These macros expect the first argument to  be  the
opening and
               closing strings respectively.

     .Ql        The  quoted literal macro behaves differently for
troff(1) than
               nroff(1).  If formatted with  nroff(1),  a  quoted
literal is always
  quoted.  If formatted with troff(1), an item
is only quoted
 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.

     Examples of quoting:
           .Aq                         <>
           .Aq Ar ctype.h ) ,          <ctype.h>),
           .Bq                         []
           .Bq Em Greek , French .     [Greek, French].
           .Dq                         ``''
           .Dq string abc .            ``string abc''.
           .Dq '^[A-Z]'                ``'^[A-Z]'''
           .Ql man mdoc                `man mdoc'
           .Qq                         ""
           .Qq string ) ,              "string"),
           .Qq string Ns ),            "string),"
           .Sq                         `'
           .Sq string                  `string'

     For a good example of nested enclosure macros, see the `.Op'
     macro.  It was created from the  same  underlying  enclosure
macros as those
     presented  in  the list above.  The `.Xo' and `.Xc' 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-Op or Normal Text Macro    [Toc]    [Back]
     The  macro `.No' is a hack for words in a macro command line
which should
     not be formatted and follows  the  conventional  syntax  for
content macros.

   No Space Macro    [Toc]    [Back]
     The  `.Ns' macro eliminates unwanted spaces in between macro
requests.  It
     is useful for old style argument lists  where  there  is  no
space between
     the flag and argument:

           .Op Fl I Ns Ar directory    produces [-Idirectory]

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

   Prefix Macro    [Toc]    [Back]
     The `.Pf' macro eliminates unwanted spaces between its first
and second

           .Pf ( Fa name2              produces (name2

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

   Section Cross References    [Toc]    [Back]
     The `.Sx' macro designates a reference to a  section  header
within the
     same document.  It is parsed and is callable.

                   .Sx FILES     FILES

   Space Mode Macro    [Toc]    [Back]
     The  `.Sm'  macro turns spacing on or off.  It is especially
useful in situations
 where the `.Ns' macro may be too clumsy to use.   An
argument of
     either  -on or -off must be specified, to turn spacing on or
off, respectively.

           Usage: .Sm -on | -off

     See Extended Arguments (below) for example usage.

   Symbolic Macro    [Toc]    [Back]
     The symbolic emphasis macro is generally a boldface macro in
either the
     symbolic sense or the traditional English usage.

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

                   .Sy Important Notice   Important Notice

     The  `.Sy'  macro  is  parsed and is callable.  Arguments to
`.Sy' may be

   Mathematical Symbols    [Toc]    [Back]
     Use this macro for mathematical symbols.

           Usage: .Ms mathematical symbol ... { . , ; : ? ! ( ) [

                   .Ms sigma  sigma

     The `.Ms' macro is parsed, but is not callable.

   References and Citations    [Toc]    [Back]
     The  following macros make a modest attempt to handle references.  At
     best, the macros make it convenient to manually  drop  in  a
subset of
     refer(1) style references.

           .Rs      Reference Start.  Causes a line break and begins collection
                   of reference information until  the  reference
end macro is
           .Re     Reference End.  The reference is printed.
           .%A      Reference  author  name, one name per invocation.
           .%B     Book title.
           .%D     Date.
           .%I     Issuer/Publisher Name.
           .%J     Journal name.
           .%N     Issue number.
           .%O     Optional information.
           .%P     Page number.
           .%Q     Corporate or Foreign Author.
           .%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 troff(1)/ditroff output.


 Similar pages
Name OS Title
mdoc.samples Linux tutorial sampler for writing BSD manuals with -mdoc
mdoc.samples NetBSD tutorial sampler for writing BSD manuals with -mdoc
perlxstut OpenBSD Tutorial for writing XSUBs
sendbug OpenBSD report a bug in OpenBSD
release OpenBSD building an OpenBSD release
dhcp OpenBSD configuring OpenBSD for DHCP
man Linux an interface to the on-line reference manuals
compat_aout OpenBSD setup for running a.out OpenBSD binaries on ELF systems
perlxstut IRIX Tutorial for XSUBs
man IRIX print entries from the on-line reference manuals; find manual entries by keyword
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service