.\" Copyright (c) 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" 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 list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. [Deleted.  See
.\"     ftp://ftp.cs.berkeley.edu/pub/4bsd/README.Impt.License.Change]
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)doc	8.1 (Berkeley) 06/08/93
.\"
.\" Modified by jjc@jclark.com as follows: the doc-* files are assumed to be
.\" installed as mdoc/doc-* rather than tmac.doc-* (the filename
.\" `tmac.doc-common' would be too long); when using groff, the doc-* files
.\" are loaded using the `mso' request.
.\"
.\" Modified by
.\"
.\"   Werner LEMBERG <wl@gnu.org>      and
.\"   Ruslan Ermilov <ru@freebsd.org>
.\"
.\" to make it more readable: using long names and many groff features,
.\" updating and extending documentation, etc.
.\"
.\" %beginstrip%
.
.
.if !\n(.g \
.  ab This version of mdoc can be run with GNU troff only!
.
.
.do if d Dd .nx
.
.
.cp 0
.
.
.if (\n[.x]\n[.y] < 118) \
.  ab You need GNU troff version 1.18 or higher to run this version of mdoc!
.
.
.\" Load start-up files
.ie t \
.  mso mdoc/doc-ditroff
.el \
.  mso mdoc/doc-nroff
.
.mso mdoc/doc-common
.mso mdoc/doc-syms
.
.
.eo
.
.
.\" NS doc-macro-name global string
.\" NS   name of calling request (set in each user-requestable macro)
.
.ds doc-macro-name
.als doc-arg0 doc-macro-name
.
.
.\" NS doc-arg-limit global register
.\" NS   total number of arguments
.
.nr doc-arg-limit 0
.
.
.\" NS doc-num-args global register
.\" NS   number of arguments to handle (must be set to \n[.$] prior to
.\" NS   `doc-parse-arg-vector' request)
.
.nr doc-num-args 0
.
.
.\" NS doc-arg-ptr global register
.\" NS   argument pointer
.
.nr doc-arg-ptr 0
.
.
.\" NS doc-argXXX global string
.\" NS   argument vector
.\" NS
.\" NS limit:
.\" NS   doc-arg-limit
.
.ds doc-arg1
.
.
.\" NS doc-typeXXX global register
.\" NS   argument type vector (macro=1, string=2, punctuation suffix=3,
.\" NS   punctuation prefix=4)
.\" NS
.\" NS limit:
.\" NS   doc-arg-limit
.
.nr doc-type1 0
.
.
.\" NS doc-spaceXXX global string
.\" NS   space vector
.\" NS
.\" NS limit:
.\" NS   doc-arg-limit
.
.ds doc-space1
.
.
.\" NS doc-parse-args macro
.\" NS   parse arguments (recursively) (`.doc-parse-args arg ...')
.\" NS
.\" NS modifies:
.\" NS   doc-arg-limit
.\" NS   doc-arg-ptr
.\" NS   doc-argXXX
.\" NS   doc-spaceXXX
.\" NS   doc-typeXXX
.\" NS   doc-arg-ptr
.\" NS   doc-have-space
.\" NS
.\" NS local variables:
.\" NS   doc-reg-dpa
.\" NS   doc-reg-dpa1
.\" NS   doc-str-dpa
.
.de doc-parse-args
.  if !\n[doc-arg-limit] \
.    doc-set-spacing-1
.
.  nr doc-have-space 0
.
.  if !\n[.$] \
.    return
.
.  nr doc-arg-limit +1
.
.  \" handle `|' and `...' specially
.  ie        "\$1"|" \
.    ds doc-arg\n[doc-arg-limit] \f[R]|\f[]
.  el \{ .ie "\$1"..." \
.    ds doc-arg\n[doc-arg-limit] \|.\|.\|.
.  el \
.    ds doc-arg\n[doc-arg-limit] "\$1
.  \}
.
.  \" get argument type and set spacing
.  doc-get-arg-type* \n[doc-arg-limit]
.  nr doc-type\n[doc-arg-limit] \n[doc-arg-type]
.  doc-set-spacing-\n[doc-arg-type]
.
.  \" check whether we have processed the last parameter
.  ie (\n[.$] == 1) \
.    nr doc-arg-ptr 0
.  el \{\
.    shift
.    doc-parse-args \$@
.  \}
.
.  nh
..
.
.
.\" NS doc-parse-arg-vector macro
.\" NS   parse argument vector (recursive)
.\" NS
.\" NS   cf. comments in doc-parse-args
.\" NS
.\" NS modifies:
.\" NS   doc-arg-limit
.\" NS   doc-arg-ptr
.\" NS   doc-argXXX
.\" NS   doc-num-args
.\" NS   doc-spaceXXX
.\" NS   doc-typeXXX
.\" NS
.\" NS local variables:
.\" NS   doc-reg-dpav
.\" NS   doc-reg-dpav1
.\" NS   doc-str-dpav
.
.de doc-parse-arg-vector
.  if !\n[doc-arg-limit] \
.    doc-set-spacing-1
.
.  nr doc-arg-limit +1
.
.  ie        "\*[doc-arg\n[doc-arg-limit]]"|" \
.    ds doc-arg\n[doc-arg-limit] \f[R]|\f[]
.  el \{ .if "\*[doc-arg\n[doc-arg-limit]]"..." \
.    ds doc-arg\n[doc-arg-limit] \|.\|.\|.
.  \}
.
.  doc-get-arg-type* \n[doc-arg-limit]
.  nr doc-type\n[doc-arg-limit] \n[doc-arg-type]
.  doc-set-spacing-\n[doc-arg-type]
.
.  ie (\n[doc-num-args] == 1) \{\
.    nr doc-arg-ptr 0
.    nr doc-num-args 0
.  \}
.  el \{\
.    nr doc-num-args -1
.    doc-parse-arg-vector
.  \}
.
.  nh
..
.
.
.\" NS doc-parse-space-vector macro
.\" NS   parse space vector (recursive)
.\" NS
.\" NS modifies:
.\" NS   doc-arg-limit
.\" NS   doc-num-args
.\" NS   doc-spaceXXX
.
.de doc-parse-space-vector
.  nr doc-arg-limit +1
.
.  doc-set-spacing-\n[doc-type\n[doc-arg-limit]]
.
.  ie (\n[doc-num-args] == 1) \
.    nr doc-num-args 0
.  el \{\
.    nr doc-num-args -1
.    doc-parse-space-vector
.  \}
..
.
.
.\" NS doc-remaining-args macro
.\" NS   output remaining arguments as-is, separated by spaces (until
.\" NS   `doc-num-args' is exhausted)
.\" NS
.\" NS modifies:
.\" NS   doc-arg-ptr
.\" NS   doc-num-args
.
.de doc-remaining-args
.  nr doc-arg-ptr +1
.  nop \)\*[doc-arg\n[doc-arg-ptr]]\c
.
.  ie (\n[doc-num-args] == 1) \{\
.    nr doc-arg-ptr 0
.    nr doc-num-args 0
.  \}
.  el \{\
.    nop \)\*[doc-space]\c
.    nr doc-num-args -1
.    doc-remaining-args
.  \}
..
.
.
.\" NS doc-append-arg macro
.\" NS   append one argument to argument vector:
.\" NS   `.doc-append-arg [arg] [type]'
.\" NS
.\" NS modifies:
.\" NS   doc-arg-limit
.\" NS   doc-argXXX
.\" NS   doc-typeXXX
.
.de doc-append-arg
.  nr doc-arg-limit +1
.  ds doc-arg\n[doc-arg-limit] "\$1
.  nr doc-type\n[doc-arg-limit] \$2
.  doc-set-spacing-\$2
..
.
.
.\" NS doc-print-and-reset macro
.\" NS   finish input line and clean up argument vectors
.
.de doc-print-and-reset
.  if \n[doc-space-mode] \
.    nop \)
.  doc-reset-args
..
.
.
.\" NS doc-reset-args macro
.\" NS   reset argument counters
.\" NS
.\" NS modifies:
.\" NS   doc-arg-limit
.\" NS   doc-arg-ptr
.\" NS   doc-have-slot
.
.de doc-reset-args
.  nr doc-arg-limit 0
.  nr doc-arg-ptr 0
.  nr doc-have-slot 0
.
.  hy \n[doc-hyphen-flags]
..
.
.
.ec
.
.\" NS doc-curr-font global register
.\" NS   saved current font
.
.nr doc-curr-font \n[.f]
.
.
.\" NS doc-curr-size global register
.\" NS   saved current font size
.
.nr doc-curr-size \n[.ps]
.
.eo
.
.
.\" NS Fl user macro
.\" NS   handle flags (appends `-' and prints flags): `.Fl [arg ...]'
.\" NS
.\" NS modifies:
.\" NS   doc-arg-ptr
.\" NS   doc-curr-font
.\" NS   doc-curr-size
.\" NS   doc-macro-name
.\" NS
.\" NS local variables:
.\" NS   doc-reg-Fl (for communication with doc-flag-recursion)
.\" NS
.\" NS width register `Fl' set in doc-common
.
.de Fl
.  nr doc-curr-font \n[.f]
.  nr doc-curr-size \n[.ps]
.  nop \*[doc-Fl-font]\c
.
.  if !\n[doc-arg-limit] \{\
.    ds doc-macro-name Fl
.    doc-parse-args \$@
.
.    \" no arguments
.    if !\n[.$] \
.      nop \|\-\|\f[]\s[0]
.  \}
.
.  if !\n[doc-arg-limit] \
.    return
.
.  nr doc-arg-ptr +1
.  ie (\n[doc-arg-limit] < \n[doc-arg-ptr]) \{\
.    \" last argument
.    nop \|\-\f[]\s[0]\c
.    doc-print-and-reset
.  \}
.  el \{\
.    ie (\n[doc-type\n[doc-arg-ptr]] == 1) \{\
.      nop \|\-\f[]\s[0]\c
.      \*[doc-arg\n[doc-arg-ptr]]
.    \}
.    el \{\
.      if (\n[doc-type\n[doc-arg-ptr]] == 3) \
.        nop \|\-\|\c
.
.      nr doc-reg-Fl 1
.      doc-flag-recursion
.  \}\}
..
.
.
.\" NS doc-flag-recursion macro
.\" NS   `Fl' flag recursion routine (special handling)
.\" NS
.\" NS modifies:
.\" NS   doc-arg-ptr
.\" NS
.\" NS local variables:
.\" NS   doc-reg-dfr
.\" NS   doc-reg-dfr1
.\" NS   doc-str-dfr
.
.de doc-flag-recursion
.  nr doc-reg-dfr1 \n[doc-type\n[doc-arg-ptr]]
.  ds doc-str-dfr "\*[doc-arg\n[doc-arg-ptr]]
.
.  ie (\n[doc-reg-dfr1] == 1) \{\
.    nop \f[]\s[0]\c
.    \*[doc-str-dfr]
.  \}
.  el \{\
.    nr doc-reg-dfr \n[doc-arg-ptr]
.
.    ie (\n[doc-reg-dfr1] == 2) \{\
.      \" handle vertical bar -- doc-reg-Fl is set for the first call of
.      \" doc-flag-recursion only; we need this to make `.Fl | ...' work
.      \" correctly
.      ie "\*[doc-str-dfr]"\*[Ba]" \{\
.        if \n[doc-reg-Fl] \
.          nop \|\-\*[doc-space]\c
.        nop \)\*[Ba]\c
.      \}
.      el \{\
.        ie "\*[doc-str-dfr]"\f[R]|\f[]" \{\
.          if \n[doc-reg-Fl] \
.            nop \|\-\*[doc-space]\c
.          nop \f[R]|\f[]\c
.        \}
.        el \{\
.          \" two consecutive hyphen characters?
.          ie "\*[doc-str-dfr]"-" \
.            nop \|\-\^\-\|\c
.          el \
.            nop \|\%\-\*[doc-str-dfr]\&\c
.    \}\}\}
.    el \{\
.      nop \f[\n[doc-curr-font]]\s[\n[doc-curr-size]u]\c
.      nop \)\*[doc-str-dfr]\f[]\s[0]\c
.    \}
.
.    ie (\n[doc-arg-limit] == \n[doc-arg-ptr]) \{\
.      \" last argument
.      if (\n[doc-reg-dfr1] == 4) \
.        nop \|\-\c
.      nop \f[\n[doc-curr-font]]\s[\n[doc-curr-size]u]\c
.      doc-print-and-reset
.    \}
.    el \{\
.      nr doc-arg-ptr +1
.      ie (\n[doc-type\n[doc-arg-ptr]] == 3) \{\
.        ie (\n[doc-type\n[doc-reg-dfr]] == 4) \
.          nop \|\-\c
.        el \
.          nop \)\*[doc-space\n[doc-reg-dfr]]\c
.      \}
.      el \
.        nop \)\*[doc-space\n[doc-reg-dfr]]\c
.
.      shift
.      nr doc-reg-Fl 0
.      doc-flag-recursion \$@
.  \}\}
..
.
.
.\" NS doc-print-recursive macro
.\" NS   general name recursion routine (print remaining arguments)
.\" NS
.\" NS modifies:
.\" NS   doc-arg-ptr
.\" NS
.\" NS local variables:
.\" NS   doc-reg-dpr
.\" NS   doc-reg-dpr1
.\" NS   doc-str-dpr
.
.de doc-print-recursive
.  nr doc-reg-dpr1 \n[doc-type\n[doc-arg-ptr]]
.  ds doc-str-dpr "\*[doc-arg\n[doc-arg-ptr]]
.
.  ie (\n[doc-reg-dpr1] == 1) \{\
.    nop \f[\n[doc-curr-font]]\s[\n[doc-curr-size]u]\c
.    \*[doc-str-dpr]
.  \}
.  el \{\
.    nr doc-reg-dpr \n[doc-arg-ptr]
.
.    \" the `\%' prevents hyphenation on a dash (`-')
.    ie (\n[doc-reg-dpr1] == 2) \
.      nop \%\*[doc-str-dpr]\&\c
.    el \{\
.      \" punctuation character
.      nop \f[\n[doc-curr-font]]\s[\n[doc-curr-size]u]\c
.      nop \)\*[doc-str-dpr]\f[]\s[0]\c
.    \}
.
.    nr doc-arg-ptr +1
.    ie (\n[doc-arg-limit] < \n[doc-arg-ptr]) \{\
.      \" last argument
.      nop \f[\n[doc-curr-font]]\s[\n[doc-curr-size]u]\c
.      doc-print-and-reset
.    \}
.    el \{\
.      nop \)\*[doc-space\n[doc-reg-dpr]]\c
.      doc-print-recursive
.  \}\}
..
.
.
.\" NS doc-print-prefixes macro
.\" NS   print leading prefixes
.\" NS
.\" NS modifies:
.\" NS   doc-arg-ptr
.
.de doc-print-prefixes
.  while (\n[doc-arg-limit] >= \n[doc-arg-ptr]) \{\
.    if !(\n[doc-type\n[doc-arg-ptr]] == 4) \
.      break
.    nop \f[\n[doc-curr-font]]\s[\n[doc-curr-size]u]\c
.    nop \)\*[doc-arg\n[doc-arg-ptr]]\f[]\s[0]\c
.    nr doc-arg-ptr +1
.  \}
..
.
.
.\" NS doc-generic-macro macro
.\" NS   this is the skeleton for most simple macros
.\" NS
.\" NS modifies:
.\" NS   doc-arg-ptr
.\" NS   doc-curr-font
.\" NS   doc-curr-size
.\" NS   doc-macro-name
.
.de doc-generic-macro
.  if !\n[doc-arg-limit] \{\
.    ie \n[.$] \{\
.      ds doc-macro-name \$0
.      doc-parse-args \$@
.    \}
.    el \
.      tm Usage: .\$0 \*[doc-\$0-usage] ... (#\n[.c])
.  \}
.
.  if !\n[doc-arg-limit] \
.    return
.
.  nr doc-arg-ptr +1
.  ie (\n[doc-arg-limit] >= \n[doc-arg-ptr]) \{\
.    if (\n[doc-type\n[doc-arg-ptr]] == 1) \{\
.      tmc mdoc warning: Using a macro as first argument
.      tm1 " cancels effect of .\$0 (#\n[.c])
.
.      \" the right action here would be to reset the argument counters
.      \" and bail out -- unfortunately, a small number of manual pages
.      \" (less than 2% for FreeBSD which has been used for testing)
.      \" relied on the old behaviour (silently ignore this error),
.      \" so it is commented out
.
.\"    doc-reset-args
.    \}
.\"  el \{\
.      nr doc-curr-font \n[.f]
.      nr doc-curr-size \n[.ps]
.      nop \*[doc-\$0-font]\c
.      doc-print-recursive
.\"  \}
.  \}
.  el \{\
.    tm Usage: .\$0 \*[doc-\$0-usage] ... (#\n[.c])
.    doc-reset-args
.  \}
..
.
.
.\" NS Ar user macro
.\" NS   command line `argument' macro: `.Ar [args ...]'
.\" NS
.\" NS modifies:
.\" NS   doc-arg-ptr
.\" NS   doc-curr-font
.\" NS   doc-curr-size
.\" NS   doc-macro-name
.\" NS
.\" NS local variable:
.\" NS   doc-str-Ar-default
.\" NS
.\" NS width register `Ar' set in doc-common
.
.ds doc-str-Ar-default "file\ .\|.\|.
.
.de Ar
.  nr doc-curr-font \n[.f]
.  nr doc-curr-size \n[.ps]
.  nop \*[doc-Ar-font]\c
.
.  if !\n[doc-arg-limit] \{\
.    ds doc-macro-name Ar
.    doc-parse-args \$@
.
.    \" no argument
.    if !\n[.$] \
.      nop \)\*[doc-str-Ar-default]\&\f[]\s[0]
.  \}
.
.  if !\n[doc-arg-limit] \
.    return
.
.  nr doc-arg-ptr +1
.  doc-print-prefixes
.  ie (\n[doc-arg-limit] < \n[doc-arg-ptr]) \{\
.    nop \)\*[doc-str-Ar-default]\&\f[]\s[0]\c
.    doc-print-and-reset
.  \}
.  el \{\
.    if !(\n[doc-type\n[doc-arg-ptr]] == 2) \{\
.      \" replace previous argument (Ar) with default value
.      nr doc-arg-ptr -1
.      ds doc-arg\n[doc-arg-ptr] "\*[doc-str-Ar-default]
.      nr doc-type\n[doc-arg-ptr] 2
.      ds doc-space\n[doc-arg-ptr] "\*[doc-space]
.
.      \" recompute space vector for remaining arguments
.      nr doc-num-args (\n[doc-arg-limit] - \n[doc-arg-ptr])
.      nr doc-arg-limit \n[doc-arg-ptr]
.      doc-parse-space-vector
.    \}
.    doc-print-recursive
.  \}
..
.
.
.\" NS Ad user macro
.\" NS   Addresses
.\" NS
.\" NS width register `Ad' set in doc-common
.
.als Ad doc-generic-macro
.ds doc-Ad-usage address
.
.
.\" NS doc-indent-synopsis global register
.\" NS   indentation in synopsis
.
.nr doc-indent-synopsis 0
.
.
.\" NS doc-indent-synopsis-active global register (bool)
.\" NS   indentation in synopsis active
.
.nr doc-indent-synopsis-active 0
.
.
.\" NS Cd user macro
.\" NS   config declaration (for section 4 SYNOPSIS)
.\" NS
.\" NS   this function causes a break; it uses the `Nm' font
.\" NS
.\" NS modifies:
.\" NS   doc-arg-ptr
.\" NS   doc-curr-font
.\" NS   doc-curr-size
.\" NS   doc-indent-synopsis
.\" NS   doc-macro-name
.\" NS
.\" NS width register `Cd' set in doc-common
.
.de Cd
.  if !\n[doc-arg-limit] \{\
.    ie \n[.$] \{\
.      ds doc-macro-name Cd
.      doc-parse-args \$@
.    \}
.    el \
.      tm Usage: .Cd configuration_file_declaration ... (#\n[.c])
.  \}
.
.  if !\n[doc-arg-limit] \
.    return
.
.  nr doc-arg-ptr +1
.  ie (\n[doc-arg-limit] >= \n[doc-arg-ptr]) \{\
.    nr doc-curr-font \n[.f]
.    nr doc-curr-size \n[.ps]
.
.    ie \n[doc-in-synopsis-section] \{\
.      ie "\*[doc-macro-name]"Cd" \{\
.        br
.        if !\n[doc-indent-synopsis] \
.          nr doc-indent-synopsis \n[doc-display-indent]u
.        if !\n[doc-indent-synopsis-active] \
.          in +\n[doc-indent-synopsis]u
.        ti -\n[doc-indent-synopsis]u
.        nop \*[doc-Nm-font]\c
.        doc-print-recursive
.        if !\n[doc-indent-synopsis-active] \
.          in -\n[doc-indent-synopsis]u
.      \}
.      el \{\
.        nop \*[doc-Nm-font]\c
.        doc-print-recursive
.    \}\}
.    el \{\
.      nop \*[doc-Nm-font]\c
.      doc-print-recursive
.  \}\}
.  el \{\
.    tm Usage: .Cd configuration_file_declaration ... (#\n[.c])
.    doc-reset-args
.  \}
..
.
.
.\" NS Cm user macro
.\" NS   interactive command modifier (flag)
.\" NS
.\" NS width register `Cm' set in doc-common
.
.als Cm doc-generic-macro
.ds doc-Cm-usage interactive_command_modifier
.
.
.\" NS Dv user macro
.\" NS   defined variable
.\" NS
.\" NS   this function uses the `Er' font
.\" NS
.\" NS width register `Dv' set in doc-common
.
.als Dv doc-generic-macro
.ds doc-Dv-usage defined_variable
.als doc-Dv-font doc-Er-font
.
.
.\" NS Em user macro
.\" NS   emphasis
.\" NS
.\" NS width register `Em' set in doc-common
.
.als Em doc-generic-macro
.ds doc-Em-usage text
.
.
.\" NS Er user macro
.\" NS   errno type
.\" NS
.\" NS width register `Er' set in doc-common
.
.als Er doc-generic-macro
.ds doc-Er-usage text
.
.
.\" NS Ev user macro
.\" NS   environment variable
.\" NS
.\" NS width register `Ev' set in doc-common
.
.als Ev doc-generic-macro
.ds doc-Ev-usage text
.
.
.\" NS doc-have-decl global register (bool)
.\" NS   subroutine test (in synopsis only)
.
.nr doc-have-decl 0
.
.
.\" NS doc-have-var global register (bool)
.\" NS   whether last type is a variable type
.
.nr doc-have-var 0
.
.
.\" NS doc-do-func-decl macro
.\" NS   do something special while in SYNOPSIS
.\" NS
.\" NS modifies:
.\" NS   doc-curr-font
.\" NS   doc-curr-size
.\" NS   doc-have-decl
.\" NS   doc-have-var
.
.de doc-do-func-decl
.  if \n[doc-in-synopsis-section] \{\
.    \" if a variable type was the last thing given, want vertical space
.    if \n[doc-have-var] \{\
.      doc-paragraph
.      nr doc-have-var 0
.    \}
.    \" if a subroutine was the last thing given, want vertical space
.    if \n[doc-have-func] \{\
.      ie \n[doc-have-decl] \
.        br
.      el \
.        doc-paragraph
.    \}
.    nr doc-have-decl 1
.  \}
.
.  nr doc-curr-font \n[.f]
.  nr doc-curr-size \n[.ps]
..
.
.
.\" NS Fd user macro
.\" NS   function declaration -- not callable
.\" NS
.\" NS   this function causes a break
.\" NS
.\" NS width register `Fd' set in doc-common
.
.de Fd
.  ie ((\n[.$] >= 1) & (\n[doc-arg-limit] == 0)) \{\
.    doc-do-func-decl
.    nop \*[doc-Fd-font]\$*
.    br
.    ft \n[doc-curr-font]
.    ps \n[doc-curr-size]u
.  \}
.  el \{\
.    tm Usage: .Fd function_declaration -- Fd is not callable (#\n[.c])
.    doc-reset-args
.  \}
..
.
.
.\" NS In user macro
.\" NS   #include statement in SYNOPSIS
.\" NS   <header.h> if not in SYNOPSIS
.\" NS
.\" NS   this function causes a break; it uses the `Fd' font
.\" NS
.\" NS modifies:
.\" NS   doc-arg-ptr
.\" NS   doc-curr-font
.\" NS   doc-curr-size
.\" NS   doc-indent-synopsis
.\" NS   doc-macro-name
.\" NS
.\" NS width register `In' set in doc-common
.
.de In
.  if !\n[doc-arg-limit] \{\
.    ie \n[.$] \{\
.      ds doc-macro-name In
.      doc-parse-args \$@
.    \}
.    el \
.      tm Usage: .In include_file ... (#\n[.c])
.  \}
.
.  if !\n[doc-arg-limit] \
.    return
.
.  nr doc-arg-ptr +1
.  doc-print-prefixes
.  ie ((\n[doc-arg-limit] >= \n[doc-arg-ptr]) & (\n[doc-type\n[doc-arg-ptr]] == 2)) \{\
.    nr doc-curr-font \n[.f]
.    nr doc-curr-size \n[.ps]
.
.    ie \n[doc-in-synopsis-section] \{\
.      ie "\*[doc-macro-name]"In" \{\
.        doc-do-func-decl
.        nop \*[doc-Fd-font]#include <\*[doc-arg\n[doc-arg-ptr]]>
.        ft \n[doc-curr-font]
.        ps \n[doc-curr-size]u
.        br
.        nr doc-arg-ptr +1
.        ie (\n[doc-arg-limit] >= \n[doc-arg-ptr]) \
.          doc-print-recursive
.        el \
.          doc-reset-args
.      \}
.      el \{\
.        ds doc-arg\n[doc-arg-ptr] "<\*[doc-Pa-font]\*[doc-arg\n[doc-arg-ptr]]
.        as doc-arg\n[doc-arg-ptr] \f[\n[doc-curr-font]]\s[\n[doc-curr-size]u]>
.        doc-print-recursive
.    \}\}
.    el \{\
.      ds doc-arg\n[doc-arg-ptr] "<\*[doc-Pa-font]\*[doc-arg\n[doc-arg-ptr]]
.      as doc-arg\n[doc-arg-ptr] \f[\n[doc-curr-font]]\s[\n[doc-curr-size]u]>
.      doc-print-recursive
.  \}\}
.  el \{\
.    tm Usage: .In include_file ... (#\n[.c])
.    doc-reset-args
.  \}
..
.
.
.\" NS Fr user macro
.\" NS   function return value
.\" NS
.\" NS   this function uses the `Ar' font
.\" NS
.\" NS width register `Fr' set in doc-common
.
.als Fr doc-generic-macro
.ds doc-Fr-usage function_return_value
.als doc-Fr-font doc-Ar-font
.
.
.\" NS Ic user macro
.\" NS   interactive command
.\" NS
.\" NS width register `Ic' set in doc-common
.
.als Ic doc-generic-macro
.ds doc-Ic-usage interactive_command
.
.
.\" NS Li user macro
.\" NS   literals
.\" NS
.\" NS width register `Li' set in doc-common
.
.als Li doc-generic-macro
.ds doc-Li-usage argument
.
.
.\" NS Ms user macro
.\" NS   math symbol
.\" NS
.\" NS   this function uses the `Sy' font
.\" NS
.\" NS width register `Ms' set in doc-common
.
.als Ms doc-generic-macro
.ds doc-Ms-usage math_symbol
.als doc-Ms-font doc-Sy-font
.
.
.\" NS doc-command-name global string
.\" NS   save first invocation of .Nm
.
.ds doc-command-name
.
.
.\" NS Nm user macro
.\" NS   name of command or page topic
.\" NS
.\" NS modifies:
.\" NS   doc-arg-ptr
.\" NS   doc-command-name
.\" NS   doc-curr-font
.\" NS   doc-curr-size
.\" NS   doc-indent-synopsis
.\" NS   doc-indent-synopsis-active
.\" NS   doc-macro-name
.\" NS
.\" NS width register `Nm' set in doc-common
.
.de Nm
.  if !\n[doc-arg-limit] \{\
.    ds doc-macro-name Nm
.    ie \n[.$] \
.      doc-parse-args \$@
.    el \{\
.      ie "\*[doc-command-name]"" \
.        tm Usage: .Nm name ... (#\n[.c])
.      el \
.        doc-parse-args \*[doc-command-name]
.  \}\}
.
.  if !\n[doc-arg-limit] \
.    return
.
.  nr doc-arg-ptr +1
.  doc-print-prefixes
.  ie (\n[doc-arg-limit] < \n[doc-arg-ptr]) \{\
.    \" last argument
.    ie "\*[doc-command-name]"" \{\
.      tm Usage: .Nm name ... (#\n[.c])
.      doc-reset-args
.    \}
.    el \{\
.      nop \*[doc-Nm-font]\*[doc-command-name]\f[]\s[0]\c
.      doc-print-and-reset
.  \}\}
.  el \{\
.    nr doc-curr-font \n[.f]
.    nr doc-curr-size \n[.ps]
.
.    ie !(\n[doc-type\n[doc-arg-ptr]] == 2) \{\
.      ie "\*[doc-command-name]"" \
.        tm Usage: .Nm name ... (#\n[.c])
.      el \{\
.        \" replace previous argument (Nm) with default value
.        nr doc-arg-ptr -1
.        ds doc-arg\n[doc-arg-ptr] "\*[doc-Nm-font]\*[doc-command-name]\f[]\s[0]
.        nr doc-type\n[doc-arg-ptr] 2
.        ds doc-space\n[doc-arg-ptr] "\*[doc-space]
.
.        \" recompute space vector for remaining arguments
.        nr doc-num-args (\n[doc-arg-limit] - \n[doc-arg-ptr])
.        nr doc-arg-limit \n[doc-arg-ptr]
.        doc-parse-space-vector
.    \}\}
.    el \{\
.      \" handle `.Nm ...' in SYNOPSIS
.      if \n[doc-in-synopsis-section] \{\
.        if "\*[doc-macro-name]"Nm" \{\
.          br
.          if !\n[doc-indent-synopsis] \{\
.            doc-get-width "\*[doc-arg\n[doc-arg-ptr]]"
.            nr doc-indent-synopsis ((\n[doc-width]u + 1u) * \n[doc-fixed-width]u)
.          \}
.          if !\n[doc-indent-synopsis-active] \{\
.            in +\n[doc-indent-synopsis]u
.            nr doc-indent-synopsis-active 1
.          \}
.          ti -\n[doc-indent-synopsis]u
.      \}\}
.      if "\*[doc-command-name]"" \
.        ds doc-command-name "\*[doc-arg\n[doc-arg-ptr]]
.
.      nop \*[doc-Nm-font]\c
.    \}
.    doc-print-recursive
.  \}
..
.
.
.\" NS Pa user macro
.\" NS   pathname: `.Pa [arg ...]'
.\" NS
.\" NS modifies:
.\" NS   doc-arg-ptr
.\" NS   doc-curr-font
.\" NS   doc-curr-size
.\" NS   doc-macro-name
.\" NS
.\" NS width register `Pa' set in doc-common
.
.de Pa
.  if !\n[doc-arg-limit] \{\
.    ds doc-macro-name Pa
.    doc-parse-args \$@
.
.    \" default value
.    if !\n[.$] \
.      nop \*[doc-Pa-font]~\f[]\s[0]
.  \}
.
.  if !\n[doc-arg-limit] \
.    return
.
.  nr doc-arg-ptr +1
.  doc-print-prefixes
.  ie (\n[doc-arg-limit] >= \n[doc-arg-ptr]) \{\
.    nr doc-curr-font \n[.f]
.    nr doc-curr-size \n[.ps]
.    nop \*[doc-Pa-font]\c
.    if !(\n[doc-type\n[doc-arg-ptr]] == 2) \{\
.      \" replace previous argument (Pa) with default value
.      nr doc-arg-ptr -1
.      ds doc-arg\n[doc-arg-ptr] ~
.      nr doc-type\n[doc-arg-ptr] 2
.      ds doc-space\n[doc-arg-ptr] "\*[doc-space]
.
.      \" recompute space vector for remaining arguments
.      nr doc-num-args (\n[doc-arg-limit] - \n[doc-arg-ptr])
.      nr doc-arg-limit \n[doc-arg-ptr]
.      doc-parse-space-vector
.    \}
.    doc-print-recursive
.  \}
.  el \{\
.    nop \*[doc-Pa-font]~\f[]\s[0]\c
.    doc-print-and-reset
.  \}
..
.
.
.\" NS Sy user macro
.\" NS   symbolics
.\" NS
.\" NS width register `Sy' set in doc-common
.
.als Sy doc-generic-macro
.ds doc-Sy-usage symbolic_text
.
.
.\" NS Me user macro
.\" NS   menu entries
.\" NS
.\" NS width register `Me' set in doc-common
.
.als Me doc-generic-macro
.ds doc-Me-usage menu_entry
.
.
.\" NS Tn user macro
.\" NS   trade name
.\" NS
.\" NS modifies:
.\" NS   doc-arg-ptr
.\" NS   doc-curr-font
.\" NS   doc-curr-size
.\" NS   doc-macro-name
.\" NS
.\" NS width register `Tn' set in doc-common
.
.de Tn
.  if !\n[doc-arg-limit] \{\
.    ie \n[.$] \{\
.      ds doc-macro-name Tn
.      doc-parse-args \$@
.    \}
.    el \
.      tm Usage: .Tn trade_name ... (#\n[.c])
.  \}
.
.  if !\n[doc-arg-limit] \
.    return
.
.  nr doc-arg-ptr +1
.  ie (\n[doc-arg-limit] >= \n[doc-arg-ptr]) \{\
.    nr doc-curr-font \n[.f]
.    nr doc-curr-size \n[.ps]
.    nop \)\*[doc-Tn-font-size]\c
.    ie !\n[doc-is-reference] \{\
.      nop \)\*[doc-Tn-font-shape]\c
.      doc-print-recursive
.    \}
.    el \
.      doc-do-references
.  \}
.  el \{\
.    tm Usage: .Tn trade_name ... (#\n[.c])
.    doc-reset-args
.  \}
..
.
.
.\" NS Va user macro
.\" NS   variable name
.\" NS
.\" NS width register `Va' set in doc-common
.
.als Va doc-generic-macro
.ds doc-Va-usage variable_name
.
.
.\" NS No user macro
.\" NS   normal text macro (default text style if mess up)
.\" NS
.\" NS width register `No' set in doc-common
.
.als No doc-generic-macro
.ds doc-No-usage normal_text
.
.
.\" NS doc-quote-left global string
.\" NS   left quotation character for `doc-enclose-string' and
.\" NS   `doc-enclose-open'
.
.ds doc-quote-left
.
.
.\" NS doc-quote-right global string
.\" NS   right quotation character for `doc-enclose-string' and
.\" NS   `doc-enclose-close'
.
.ds doc-quote-right
.
.
.\" NS Op user macro
.\" NS   option expression (i.e., enclose string in square brackets)
.\" NS
.\" NS modifies:
.\" NS   doc-macro-name
.\" NS   doc-quote-left
.\" NS   doc-quote-right
.\" NS
.\" NS width register `Op' set in doc-common
.
.de Op
.  if !\n[doc-arg-limit] \
.    ds doc-macro-name Op
.
.  ds doc-quote-left "\*[doc-left-bracket]
.  ds doc-quote-right "\*[doc-right-bracket]
.
.  doc-enclose-string \$@
..
.
.
.\" NS Aq user macro
.\" NS   enclose string in angle brackets
.\" NS
.\" NS modifies:
.\" NS   doc-macro-name
.\" NS   doc-quote-left
.\" NS   doc-quote-right
.\" NS
.\" NS width register `Aq' set in doc-common
.
.de Aq
.  if !\n[doc-arg-limit] \
.    ds doc-macro-name Aq
.
.  ie "\*[doc-macro-name]"An" \{\
.    ds doc-quote-left <
.    ds doc-quote-right >
.  \}
.  el \{\
.    ds doc-quote-left \[la]
.    ds doc-quote-right \[ra]
.  \}
.
.  doc-enclose-string \$@
..
.
.
.\" NS Bq user macro
.\" NS   enclose string in square brackets
.\" NS
.\" NS modifies:
.\" NS   doc-macro-name
.\" NS   doc-quote-left
.\" NS   doc-quote-right
.\" NS
.\" NS width register `Bq' set in doc-common
.
.de Bq
.  if !\n[doc-arg-limit] \
.    ds doc-macro-name Bq
.
.  ds doc-quote-left "\*[doc-left-bracket]
.  ds doc-quote-right "\*[doc-right-bracket]
.
.  doc-enclose-string \$@
..
.
.
.\" NS Brq user macro
.\" NS   enclose string in braces
.\" NS
.\" NS modifies:
.\" NS   doc-macro-name
.\" NS   doc-quote-left
.\" NS   doc-quote-right
.\" NS
.\" NS width register `Brq' set in doc-common
.
.de Brq
.  if !\n[doc-arg-limit] \
.    ds doc-macro-name Brq
.
.  ds doc-quote-left {
.  ds doc-quote-right }
.
.  doc-enclose-string \$@
..
.
.
.\" NS Dq user macro
.\" NS   enclose string in double quotes
.\" NS
.\" NS modifies:
.\" NS   doc-macro-name
.\" NS   doc-quote-left
.\" NS   doc-quote-right
.\" NS
.\" NS width register `Dq' set in doc-common
.
.de Dq
.  if !\n[doc-arg-limit] \
.    ds doc-macro-name Dq
.
.  ds doc-quote-left "\*[Lq]
.  ds doc-quote-right "\*[Rq]
.
.  doc-enclose-string \$@
..
.
.
.\" NS Eq user macro
.\" NS   enclose string in user-defined quotes (args 1 and 2)
.\" NS
.\" NS modifies:
.\" NS   doc-macro-name
.\" NS   doc-quote-left
.\" NS   doc-quote-right
.\" NS
.\" NS width register `Eq' set in doc-common
.
.de Eq
.  if !\n[doc-arg-limit] \
.    ds doc-macro-name Eq
.
.  ds doc-quote-left "\$1
.  ds doc-quote-right "\$2
.
.  shift 2
.  doc-enclose-string \$@
..
.
.
.\" NS Pq user macro
.\" NS   enclose string in parentheses
.\" NS
.\" NS modifies:
.\" NS   doc-macro-name
.\" NS   doc-quote-left
.\" NS   doc-quote-right
.\" NS
.\" NS width register `Pq' set in doc-common
.
.de Pq
.  if !\n[doc-arg-limit] \
.    ds doc-macro-name Pq
.
.  ds doc-quote-left "\*[doc-left-parenthesis]
.  ds doc-quote-right "\*[doc-right-parenthesis]
.
.  doc-enclose-string \$@
..
.
.
.\" NS Ql user macro
.\" NS   quoted literal
.\"
.\"   is in file doc-[dit|n]roff
.
.
.\" NS Qq user macro
.\" NS   enclose string in straight double quotes
.\" NS
.\" NS modifies:
.\" NS   doc-macro-name
.\" NS   doc-quote-left
.\" NS   doc-quote-right
.\" NS
.\" NS width register `Qq' set in doc-common
.
.de Qq
.  if !\n[doc-arg-limit] \
.    ds doc-macro-name Qq
.
.  ds doc-quote-left "\*[q]
.  ds doc-quote-right "\*[q]
.
.  doc-enclose-string \$@
..
.
.
.\" NS Sq user macro
.\" NS   enclose string in single quotes
.\" NS
.\" NS modifies:
.\" NS   doc-macro-name
.\" NS   doc-quote-left
.\" NS   doc-quote-right
.\" NS
.\" NS width register `Sq' set in doc-common
.
.de Sq
.  if !\n[doc-arg-limit] \
.    ds doc-macro-name Sq
.
.  ds doc-quote-left "\*[doc-left-singlequote]
.  ds doc-quote-right "\*[doc-right-singlequote]
.
.  doc-enclose-string \$@
..
.
.
.\" NS Es user macro
.\" NS   set up arguments (i.e., the left and right quotation character as
.\" NS   first and second argument) for .En call
.\" NS
.\" NS modifies:
.\" NS   doc-arg-ptr
.\" NS   doc-macro-name
.\" NS   doc-quote-left
.\" NS   doc-quote-right
.
.de Es
.  if !\n[doc-arg-limit] \{\
.    ie (\n[.$] > 2) \{\
.      ds doc-macro-name Es
.      doc-parse-args \$@
.    \}
.    el \{\
.      ds doc-quote-left "\$1
.      ds doc-quote-right "\$2
.  \}\}
.
.  if !\n[doc-arg-limit] \
.    return
.
.  nr doc-arg-ptr +1
.  ds doc-quote-left "\*[doc-arg\n[doc-arg-ptr]]
.  nr doc-arg-ptr +1
.  ds doc-quote-right "\*[doc-arg\n[doc-arg-ptr]]
.  nr doc-arg-ptr +1
.  ie (\n[doc-arg-limit] >= \n[doc-arg-ptr]) \
.    doc-do-\n[doc-type\n[doc-arg-ptr]]
.  el \
.    doc-print-and-reset
..
.
.
.\" NS doc-have-slot global register (bool)
.\" NS   set if `doc-enclose-string' has created a slot for closing
.\" NS   delimiter
.
.nr doc-have-slot 0
.
.
.\" NS doc-enclose-string macro
.\" NS   enclose string with given args (e.g. [ and ])
.\" NS
.\" NS modifies:
.\" NS   doc-arg-ptr
.\" NS   doc-argXXX
.\" NS   doc-have-slot
.\" NS
.\" NS local variables:
.\" NS   doc-reg-des
.\" NS   doc-reg-des1
.\" NS   doc-reg-des2
.\" NS
.\" NS requires:
.\" NS   doc-quote-left
.\" NS   doc-quote-right
.
.de doc-enclose-string
.  if \n[doc-in-synopsis-section] \
.    doc-set-hard-space
.
.  if !\n[doc-arg-limit] \{\
.    ie \n[.$] \
.      doc-parse-args \$@
.    el \{\
.      nop \)\*[doc-quote-left]\*[doc-quote-right]
.  \}\}
.
.  if !\n[doc-arg-limit] \
.    return
.
.  nr doc-curr-font \n[.f]
.  nr doc-curr-size \n[.ps]
.
.  nr doc-arg-ptr +1
.  doc-print-prefixes
.  \" the final `\)' prevents hyphenation in case the next character is `\%'
.  nop \)\*[doc-quote-left]\)\c
.  ie (\n[doc-arg-limit] < \n[doc-arg-ptr]) \{\
.    \" last argument
.    nop \)\*[doc-quote-right]\)\c
.    doc-print-and-reset
.  \}
.  el \{\
.    \" test whether last arguments are of type closing punctuation
.    \" resp. suffix
.    ie (\n[doc-type\n[doc-arg-limit]] == 3) \{\
.      nr doc-reg-des (\n[doc-arg-limit] - 1)
.      while (\n[doc-type\n[doc-reg-des]] == 3) \
.        nr doc-reg-des -1
.
.      \" prepend closing delimiter
.      nr doc-reg-des +1
.      ds doc-arg\n[doc-reg-des] "\*[doc-quote-right]\)\*[doc-arg\n[doc-reg-des]]
.    \}
.    el \{\
.      \" test whether last arguments are macros which continue the line
.      \" logically
.      nr doc-reg-des \n[doc-arg-limit]
.      while (\n[doc-reg-des] >= \n[doc-arg-ptr]) \{\
.        if !\A\*[doc-arg\n[doc-reg-des]] \
.          break
.        if !d doc-after-\*[doc-arg\n[doc-reg-des]] \
.          break
.        nr doc-reg-des -1
.      \}
.
.      \" if there are no trailing macros to be skipped, append argument
.      ie (\n[doc-reg-des] == \n[doc-arg-limit]) \
.        doc-append-arg "\)\*[doc-quote-right]\)" 3
.      el \{\
.        \" if a previous call to `doc-enclose-string' has already created
.        \" a slot, prepend argument
.        ie \n[doc-have-slot] \
.          ds doc-arg\n[doc-reg-des] "\*[doc-quote-right]\)\*[doc-arg\n[doc-reg-des]]
.        el \{\
.          \" we have to shift all arguments to the right
.          nr doc-reg-des +1
.          nr doc-reg-des1 \n[doc-arg-limit]
.          nr doc-reg-des2 (\n[doc-arg-limit] + 1)
.          while (\n[doc-reg-des1] >= \n[doc-reg-des]) \{\
.            rn doc-arg\n[doc-reg-des1] doc-arg\n[doc-reg-des2]
.            rnn doc-type\n[doc-reg-des1] doc-type\n[doc-reg-des2]
.            rn doc-space\n[doc-reg-des1] doc-space\n[doc-reg-des2]
.            nr doc-reg-des1 -1
.            nr doc-reg-des2 -1
.          \}
.          nr doc-arg-limit +1
.
.          \" finally, insert closing delimiter into the freed slot and
.          \" recompute spacing vector
.          ds doc-arg\n[doc-reg-des] "\)\*[doc-quote-right]\)
.          nr doc-type\n[doc-reg-des] 3
.          nr doc-num-args (\n[doc-arg-limit] - \n[doc-reg-des] + 1)
.          nr doc-arg-limit (\n[doc-reg-des] - 1)
.          doc-parse-space-vector
.          nr doc-have-slot 1
.    \}\}\}
.
.    doc-do-\n[doc-type\n[doc-arg-ptr]]
.  \}
.
.  if \n[doc-in-synopsis-section] \
.    doc-set-soft-space
..
.
.
.\" NS En user macro
.\" NS   enclose arguments with quotation characters set up with `.Es'
.
.als En doc-enclose-string
.
.
.\" NS Ao user macro
.\" NS   angle open
.\" NS
.\" NS modifies:
.\" NS   doc-macro-name
.\" NS   doc-quote-left
.\" NS
.\" NS width register `Ao' set in doc-common
.
.de Ao
.  if !\n[doc-arg-limit] \
.    ds doc-macro-name Ao
.
.  ie "\*[doc-macro-name]"An" \
.    ds doc-quote-left <
.  el \
.    ds doc-quote-left \[la]
.
.  doc-enclose-open \$@
..
.
.
.\" NS Ac user macro
.\" NS   angle close
.\" NS
.\" NS modifies:
.\" NS   doc-macro-name
.\" NS   doc-quote-right
.\" NS
.\" NS width register `Ac' set in doc-common
.
.de Ac
.  if !\n[doc-arg-limit] \
.    ds doc-macro-name Ac
.
.  ie "\*[doc-macro-name]"An" \
.    ds doc-quote-right >
.  el \
.    ds doc-quote-right \[ra]
.
.  doc-enclose-close \$@
..
.
.
.\" NS Bo user macro
.\" NS   bracket open
.\" NS
.\" NS modifies:
.\" NS   doc-macro-name
.\" NS   doc-quote-left
.\" NS
.\" NS width register `Bo' set in doc-common
.
.de Bo
.  if !\n[doc-arg-limit] \
.    ds doc-macro-name Bo
.
.  ds doc-quote-left "\*[doc-left-bracket]
.
.  doc-enclose-open \$@
..
.
.
.\" NS Bc user macro
.\" NS   bracket close
.\" NS
.\" NS modifies:
.\" NS   doc-macro-name
.\" NS   doc-quote-right
.\" NS
.\" NS width register `Bc' set in doc-common
.
.de Bc
.  if !\n[doc-arg-limit] \
.    ds doc-macro-name Bc
.
.  ds doc-quote-right "\*[doc-right-bracket]
.
.  doc-enclose-close \$@
..
.
.
.\" NS Bro user macro
.\" NS   brace open
.\" NS
.\" NS modifies:
.\" NS   doc-macro-name
.\" NS   doc-quote-left
.\" NS
.\" NS width register `Bro' set in doc-common
.
.de Bro
.  if !\n[doc-arg-limit] \
.    ds doc-macro-name Bo
.
.  ds doc-quote-left {
.
.  doc-enclose-open \$@
..
.
.
.\" NS Brc user macro
.\" NS   brace close
.\" NS
.\" NS modifies:
.\" NS   doc-macro-name
.\" NS   doc-quote-right
.\" NS
.\" NS width register `Brc' set in doc-common
.
.de Brc
.  if !\n[doc-arg-limit] \
.    ds doc-macro-name Bc
.
.  ds doc-quote-right }
.
.  doc-enclose-close \$@
..
.
.
.\" NS Do user macro
.\" NS   double quote open
.\" NS
.\" NS modifies:
.\" NS   doc-macro-name
.\" NS   doc-quote-left
.\" NS
.\" NS width register `Do' set in doc-common
.
.de Do
.  if !\n[doc-arg-limit] \
.    ds doc-macro-name Do
.
.  ds doc-quote-left "\*[Lq]
.
.  doc-enclose-open \$@
..
.
.
.\" NS Dc user macro
.\" NS   double quote close
.\" NS
.\" NS modifies:
.\" NS   doc-macro-name
.\" NS   doc-quote-right
.\" NS
.\" NS width register `Dc' set in doc-common
.
.de Dc
.  if !\n[doc-arg-limit] \
.    ds doc-macro-name Dc
.
.  ds doc-quote-right "\*[Rq]
.
.  doc-enclose-close \$@
..
.
.
.\" NS Eo user macro
.\" NS   enclose open (using first argument as beginning of enclosure)
.\" NS
.\" NS modifies:
.\" NS   doc-macro-name
.\" NS   doc-quote-left
.\" NS
.\" NS width register `Eo' set in doc-common
.
.de Eo
.  if !\n[doc-arg-limit] \
.    ds doc-macro-name Eo
.
.  ds doc-quote-left "\$1
.
.  shift
.  doc-enclose-open \$@
..
.
.
.\" NS Ec user macro
.\" NS   enclose close (using first argument as end of enclosure)
.\" NS
.\" NS modifies:
.\" NS   doc-macro-name
.\" NS   doc-quote-right
.\" NS
.\" NS width register `Ec' set in doc-common
.
.de Ec
.  if !\n[doc-arg-limit] \
.    ds doc-macro-name Ec
.
.  ds doc-quote-right "\$1
.
.  shift
.  doc-enclose-close \$@
..
.
.
.\" NS Oo user macro
.\" NS   option open
.\" NS
.\" NS modifies:
.\" NS   doc-macro-name
.\" NS   doc-quote-left
.\" NS
.\" NS width register `Oo' set in doc-common
.
.de Oo
.  if !\n[doc-arg-limit] \
.    ds doc-macro-name Oo
.
.  ds doc-quote-left [
.
.  doc-enclose-open \$@
..
.
.
.\" NS Oc user macro
.\" NS   option close
.\" NS
.\" NS modifies:
.\" NS   doc-macro-name
.\" NS   doc-quote-right
.\" NS
.\" NS width register `Oc' set in doc-common
.
.de Oc
.  if !\n[doc-arg-limit] \
.    ds doc-macro-name Oc
.
.  ds doc-quote-right ]
.
.  doc-enclose-close \$@
..
.
.
.\" NS Po user macro
.\" NS   parenthesis open
.\" NS
.\" NS modifies:
.\" NS   doc-macro-name
.\" NS   doc-quote-left
.\" NS
.\" NS width register `Po' set in doc-common
.
.de Po
.  if !\n[doc-arg-limit] \
.    ds doc-macro-name Po
.
.  ds doc-quote-left "\*[doc-left-parenthesis]
.
.  doc-enclose-open \$@
..
.
.
.\" NS Pc user macro
.\" NS   parenthesis close
.\" NS
.\" NS modifies:
.\" NS   doc-macro-name
.\" NS   doc-quote-right
.\" NS
.\" NS width register `Pc' set in doc-common
.
.de Pc
.  if !\n[doc-arg-limit] \
.    ds doc-macro-name Pc
.
.  ds doc-quote-right "\*[doc-right-parenthesis]
.
.  doc-enclose-close \$@
..
.
.
.\" NS Qo user macro
.\" NS   straight double quote open
.\" NS
.\" NS modifies:
.\" NS   doc-macro-name
.\" NS   doc-quote-left
.\" NS
.\" NS width register `Qo' set in doc-common
.
.de Qo
.  if !\n[doc-arg-limit] \
.    ds doc-macro-name Qo
.
.  ds doc-quote-left "\*[q]
.
.  doc-enclose-open \$@
..
.
.
.\" NS Qc user macro
.\" NS   straight double quote close
.\" NS
.\" NS modifies:
.\" NS   doc-macro-name
.\" NS   doc-quote-right
.\" NS
.\" NS width register `Qc' set in doc-common
.
.de Qc
.  if !\n[doc-arg-limit] \
.    ds doc-macro-name Qc
.
.  ds doc-quote-right "\*[q]
.
.  doc-enclose-close \$@
..
.
.
.\" NS So user macro
.\" NS   single quote open
.\" NS
.\" NS modifies:
.\" NS   doc-macro-name
.\" NS   doc-quote-left
.\" NS
.\" NS width register `So' set in doc-common
.
.de So
.  if !\n[doc-arg-limit] \
.    ds doc-macro-name So
.
.  ds doc-quote-left "\*[doc-left-singlequote]
.
.  doc-enclose-open \$@
..
.
.
.\" NS Sc user macro
.\" NS   single quote close
.\" NS
.\" NS modifies:
.\" NS   doc-macro-name
.\" NS   doc-quote-right
.\" NS
.\" NS width register `Sc' set in doc-common
.
.de Sc
.  if !\n[doc-arg-limit] \
.    ds doc-macro-name Sc
.
.  ds doc-quote-right "\*[doc-right-singlequote]
.
.  doc-enclose-close \$@
..
.
.
.\" NS Xo user macro
.\" NS   extend open
.\" NS
.\" NS modifies:
.\" NS   doc-macro-name
.\" NS   doc-quote-left
.\" NS
.\" NS width register `Xo' set in doc-common
.
.de Xo
.  if !\n[doc-arg-limit] \
.    ds doc-macro-name Xo
.
.  ds doc-quote-left
.
.  doc-enclose-open \$@
..
.
.
.\" NS Xc user macro
.\" NS   extend close
.\" NS
.\" NS modifies:
.\" NS   doc-macro-name
.\" NS   doc-quote-right
.\" NS
.\" NS width register `Xc' set in doc-common
.
.de Xc
.  if !\n[doc-arg-limit] \
.    ds doc-macro-name Xc
.
.  ds doc-quote-right
.
.  doc-enclose-close \$@
..
.
.
.\" NS doc-nesting-level global register
.\" NS   used by `doc-enclose-open' and `doc-enclose-close'
.
.nr doc-nesting-level 0
.
.
.\" NS doc-in-list global register (bool)
.\" NS   whether we are in (logical) .It
.
.nr doc-in-list 0
.
.
.\" NS doc-enclose-open macro
.\" NS   enclose string open
.\" NS
.\" NS modifies:
.\" NS   doc-arg-ptr
.\" NS   doc-nesting-level
.
.de doc-enclose-open
.  if !\n[doc-arg-limit] \
.    doc-parse-args \$@
.
.  nr doc-arg-ptr +1
.  doc-print-prefixes
.  nr doc-arg-ptr -1
.
.  nop \)\*[doc-quote-left]\)\c
.
.  \" start enclosure box
.  box doc-enclosure-box\n[doc-nesting-level]
.  ev doc-enclosure-env\n[doc-nesting-level]
.  evc 0
.  in 0
.  nf
.  \" we insert something to make .chop always work
.  nop \&\c
.
.  \" increase nesting level *after* parsing of arguments
.  nr doc-nesting-level +1
.
.  if \n[doc-arg-limit] \{\
.    nr doc-arg-ptr +1
.    ie (\n[doc-arg-limit] >= \n[doc-arg-ptr]) \
.      doc-print-recursive
.    el \
.      doc-reset-args
.  \}
..
.
.
.\" NS doc-enclose-close macro
.\" NS   enclose string close
.\" NS
.\" NS modifies:
.\" NS   doc-nesting-level
.
.de doc-enclose-close
.  nr doc-nesting-level -1
.
.  \" finish enclosure box
.  br
.  ev
.  box
.  chop doc-enclosure-box\n[doc-nesting-level]
.  unformat doc-enclosure-box\n[doc-nesting-level]
.
.  nh
.  nop \*[doc-enclosure-box\n[doc-nesting-level]]\c
.  nop \)\*[doc-quote-right]\)\c
.
.  if !\n[doc-arg-limit] \{\
.    doc-parse-args \$@
.
.    if !\n[.$] \
.      doc-print-and-reset
.  \}
.
.  if \n[doc-arg-limit] \{\
.    ie (\n[doc-arg-limit] > \n[doc-arg-ptr]) \{\
.      nop \)\*[doc-space\n[doc-arg-ptr]]\c
.      nr doc-arg-ptr +1
.      doc-print-recursive
.    \}
.    el \
.      doc-print-and-reset
.  \}
.
.  \" shall we finish .It macro?
.  if !"\*[doc-macro-name]"It" \
.    if \n[doc-in-list] \
.      if !\n[doc-nesting-level] \
.        doc-\*[doc-list-type-stack\n[doc-list-depth]]
..
.
.
.\" NS Pf user macro
.\" NS   prefix: `.Pf prefix arg ...'
.\" NS
.\" NS modifies:
.\" NS   doc-arg-ptr
.\" NS   doc-macro-name
.\" NS   doc-quote-left
.\" NS
.\" NS width register `Pf' set in doc-common
.
.de Pf
.  if !\n[doc-arg-limit] \
.    ds doc-macro-name Pf
.
.  ie \n[doc-arg-limit] \{\
.    ie ((\n[doc-arg-limit] - \n[doc-arg-ptr]) > 1) \{\
.      nr doc-arg-ptr +1
.      nop \)\*[doc-arg\n[doc-arg-ptr]]\c
.    \}
.    el \
.      tm mdoc warning: .Pf: trailing prefix (#\n[.c])
.  \}
.  el \{\
.    nop \)\$1\)\c
.    shift
.    ie \n[.$] \
.      doc-parse-args \$@
.    el \{\
.      tm mdoc warning: .Pf: missing arguments (#\n[.c])
.      nop \)
.  \}\}
.
.  if \n[doc-arg-limit] \{\
.    nr doc-arg-ptr +1
.    ie (\n[doc-arg-limit] < \n[doc-arg-ptr]) \
.      doc-print-and-reset
.    el \
.      doc-do-\n[doc-type\n[doc-arg-ptr]]
.  \}
..
.
.
.\" NS Ns user macro
.\" NS   remove space (space removal done by `doc-parse-args')
.\" NS
.\" NS modifies:
.\" NS   doc-argXXX
.\" NS   doc-macro-name
.\" NS
.\" NS width register `Ns' set in doc-common
.
.de Ns
.  if !\n[doc-arg-limit] \{\
.    ie \n[.$] \{\
.      ds doc-macro-name Ns
.      doc-parse-args \$@
.    \}
.    el \
.      tm Usage: .Ns must be called with arguments (#\n[.c])
.  \}
.
.  if \n[doc-arg-limit] \{\
.    nr doc-arg-ptr +1
.    ie (\n[doc-arg-limit] >= \n[doc-arg-ptr]) \
.      doc-print-recursive
.    el \
.      doc-reset-args
.  \}
..
.
.
.\" NS Ap user macro
.\" NS   append an apostrophe
.\" NS
.\" NS width register `Ap' set in doc-common
.
.de Ap
.  ie !\n[doc-arg-limit] \
.    tm Usage: `Ap' cannot be first macro on a line (no `.Ap') (#\n[.c])
.  el \{\
.    nop \)'\)\c
.    nr doc-arg-ptr +1
.    ie (\n[doc-arg-limit] >= \n[doc-arg-ptr]) \
.      doc-print-recursive
.    el \
.      doc-reset-args
.  \}
..
.
.
.\" NS doc-space global string
.\" NS   current inter-argument space
.
.ds doc-space "\*[doc-soft-space]
.
.
.\" NS doc-soft-space constant string
.\" NS   soft (stretchable) space (defined in doc-common)
.
.
.\" NS doc-hard-space constant string
.\" NS   hard (unpaddable) space (defined in doc-common)
.
.
.\" NS doc-set-hard-space macro
.\" NS   set current space string to hard (unpaddable) space.
.\" NS
.\" NS modifies:
.\" NS   doc-saved-space
.\" NS   doc-space
.
.de doc-set-hard-space
.  ie "\*[doc-space]"" \
.    ds doc-saved-space "\*[doc-hard-space]
.  el \
.    ds doc-space "\*[doc-hard-space]
..
.
.
.\" NS doc-set-soft-space macro
.\" NS   set current space string to soft space
.\" NS
.\" NS modifies:
.\" NS   doc-saved-space
.\" NS   doc-space
.
.de doc-set-soft-space
.  ie "\*[doc-space]"" \
.    ds doc-saved-space "\*[doc-soft-space]
.  el \
.    ds doc-space "\*[doc-soft-space]
..
.
.
.\" NS doc-space-mode global register (bool)
.\" NS   default is one (space mode on)
.
.nr doc-space-mode 1
.
.
.\" NS doc-saved-space global string
.\" NS   saved value of `doc-space'
.
.ds doc-saved-space "\*[doc-space]
.
.
.\" NS doc-have-space global register (bool)
.\" NS   set if last command was horizontal space
.
.nr doc-have-space 0
.
.
.\" NS Sm user macro
.\" NS   space mode (`.Sm'/`.Sm on'/`.Sm off')
.\" NS
.\" NS   without argument, toggle space mode
.\" NS
.\" NS modifies:
.\" NS   doc-arg-limit
.\" NS   doc-arg-ptr
.\" NS   doc-argXXX
.\" NS   doc-macro-name
.\" NS   doc-num-args
.\" NS   doc-saved-space
.\" NS   doc-space
.\" NS   doc-space-mode
.\" NS   doc-spaceXXX
.\" NS
.\" NS local variables:
.\" NS   doc-reg-Sm
.\" NS
.\" NS width register `Sm' set in doc-common
.
.de Sm
.  ie \n[doc-have-space] \
.    nr doc-reg-Sm 0
.  el \
.    nr doc-reg-Sm 1
.
.  if !\n[doc-arg-limit] \{\
.    ie \n[.$] \{\
.      ds doc-macro-name Sm
.      doc-parse-args \$@
.    \}
.    el \{\
.      ie \n[doc-space-mode] \{\
.        ds doc-saved-space "\*[doc-space]
.        ds doc-space
.        nr doc-space-mode 0
.      \}
.      el \{\
.        ds doc-space "\*[doc-saved-space]
.        nr doc-space-mode 1
.
.        \" finish line only if it is interrupted and `doc-have-space'
.        \" isn't set
.        if \n[doc-reg-Sm] \
.          if \n[.int] \
.            nop \)
.      \}
.  \}\}
.
.  if !\n[doc-arg-limit] \
.    return
.
.  nr doc-arg-ptr +1
.
.  \" avoid a warning message in case `Sm' is the last parameter
.  if !d doc-arg\n[doc-arg-ptr] \
.    ds doc-arg\n[doc-arg-ptr]
.
.  ie "\*[doc-arg\n[doc-arg-ptr]]"on" \{\
.    ds doc-space "\*[doc-saved-space]
.    nr doc-space-mode 1
.  \}
.  el \{\
.    ie "\*[doc-arg\n[doc-arg-ptr]]"off" \{\
.      ds doc-saved-space "\*[doc-space]
.      ds doc-space
.      nr doc-space-mode 0
.    \}
.    el \{\
.      \" no argument for Sm
.      nr doc-arg-ptr -1
.      ie \n[doc-space-mode] \{\
.        ds doc-saved-space "\*[doc-space]
.        ds doc-space
.        nr doc-space-mode 0
.      \}
.      el \{\
.        ds doc-space "\*[doc-saved-space]
.        nr doc-space-mode 1
.      \}
.  \}\}
.
.  ie \n[doc-space-mode] \{\
.    \" recompute space vector for remaining arguments
.    nr doc-num-args (\n[doc-arg-limit] - \n[doc-arg-ptr])
.    nr doc-arg-limit \n[doc-arg-ptr]
.    if \n[doc-num-args] \
.      doc-parse-space-vector
.
.    \" finish line only if it is interrupted and `doc-have-space'
.    \" isn't set
.    if \n[doc-reg-Sm] \
.      if \n[.int] \
.        nop \)
.  \}
.  el \{\
.    \" reset remaining space vector elements
.    nr doc-reg-Sm (\n[doc-arg-ptr] + 1)
.    while (\n[doc-reg-Sm] <= \n[doc-arg-limit]) \{\
.      ds doc-space\n[doc-reg-Sm]
.      nr doc-reg-Sm +1
.      \" the body of a `while' request must end with the fitting `\}'!
.    \}
.  \}
.
.  \" do we have parameters to print?
.  ie (\n[doc-arg-limit] > \n[doc-arg-ptr]) \{\
.    \" skip `Sm' argument
.    nr doc-arg-ptr +1
.    doc-print-recursive
.  \}
.  el \
.    doc-reset-args
..
.
.
.\" NS doc-arg-type immediate register
.\" NS   argument type (macro=1, string=2, punctuation suffix=3,
.\" NS   punctuation prefix=4)
.
.nr doc-arg-type 0
.
.
.\" NS doc-get-arg-type macro
.\" NS   get argument type
.\" NS
.\" NS   this macro expects the width of the argument in `doc-width'
.\" NS
.\" NS modifies:
.\" NS   doc-arg-type
.
.de doc-get-arg-type
.  nr doc-arg-type 2
.
.  if ((\n[doc-width] < 4) & \A\$1) \{\
.    ie (\n[doc-width] == 1) \{\
.      if r doc-punct\$1 \
.        nr doc-arg-type \n[doc-punct\$1]
.    \}
.    el \
.      if r \$1 \
.        if d \$1 \
.          nr doc-arg-type 1
.  \}
..
.
.
.\" NS doc-get-arg-type* macro
.\" NS   similar to as `doc-get-arg-type' but uses doc-argXXX strings
.\" NS
.\" NS   this macro sets the `doc-width' register using the `length' request
.\" NS   to get the number of characters in a string literally
.\" NS
.\" NS modifies:
.\" NS   doc-arg-type
.\" NS   doc-width
.
.de doc-get-arg-type*
.  nr doc-arg-type 2
.  length doc-width "\*[doc-arg\$1]
.
.  if ((\n[doc-width] < 4) & \A\*[doc-arg\$1]) \{\
.    ie (\n[doc-width] == 1) \{\
.      if r doc-punct\*[doc-arg\$1] \
.        nr doc-arg-type \n[doc-punct\*[doc-arg\$1]]
.    \}
.    el \
.      if r \*[doc-arg\$1] \
.        if d \*[doc-arg\$1] \
.          nr doc-arg-type 1
.  \}
..
.
.
.\" NS doc-set-spacing-1 macro
.\" NS   set spacing for macros
.\" NS
.\" NS…