[BACK]Return to roff.7 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/roff.7 between version 1.14 and 1.15

version 1.14, 2010/07/27 13:16:00 version 1.15, 2010/12/06 16:37:32
Line 37  characters
Line 37  characters
 .Sq \.  .Sq \.
 or  or
 .Sq \(aq  .Sq \(aq
 are parsed for macros.  Other lines are interpreted within the scope of  are parsed for requests and macros.
   Other lines are interpreted within the scope of
 prior macros:  prior macros:
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.xx Macro lines change control state.  \&.xx Macro lines change control state.
Line 51  manuals must have
Line 52  manuals must have
 .Ux  .Ux
 line terminators.  line terminators.
 .Sh MACRO SYNTAX  .Sh MACRO SYNTAX
 Macros are arbitrary in length and begin with a control character ,  Requests and macros are arbitrary in length and begin with a control
   character,
 .Sq \.  .Sq \.
 or  or
 .Sq \(aq ,  .Sq \(aq ,
 at the beginning of the line.  at the beginning of the line.
 An arbitrary amount of whitespace may sit between the control character  An arbitrary amount of whitespace may sit between the control character
 and the macro name.  and the request or macro name.
 Thus, the following are equivalent:  Thus, the following are equivalent:
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.if  \&.if
 \&.\ \ \ \&if  \&.\ \ \ \&if
 .Ed  .Ed
 .Sh REFERENCE  .Sh REQUEST REFERENCE
 This section is a canonical reference of all macros, arranged  This section is a canonical reference of all requests recognized by the
 alphabetically.  .Xr mandoc 1
   .Nm
   parser.
   The
   .Nm
   language defines many more requests and macros not implemented in
   .Xr mandoc 1 .
   .Ss \&ad
   Set line adjustment mode.
   This line-scoped request is intended to have one argument to select
   normal, left, right, or center adjustment for subsequent text.
   Currently, it is ignored including its arguments,
   and the number of arguments is not checked.
 .Ss \&am  .Ss \&am
 The syntax of this macro is the same as that of  Append to a macro definition.
 .Sx \&ig ,  The syntax of this request is the same as that of
 except that a leading argument must be specified.  .Sx \&de .
 It is ignored, as are its children.  It is currently ignored by
   .Xr mandoc 1 ,
   as are its children.
 .Ss \&ami  .Ss \&ami
 The syntax of this macro is the same as that of  Append to a macro definition, specifying the macro name indirectly.
 .Sx \&ig ,  The syntax of this request is the same as that of
 except that a leading argument must be specified.  .Sx \&dei .
 It is ignored, as are its children.  It is currently ignored by
   .Xr mandoc 1 ,
   as are its children.
 .Ss \&am1  .Ss \&am1
 The syntax of this macro is the same as that of  Append to a macro definition, switching roff compatibility mode off
 .Sx \&ig ,  during macro execution.
 except that a leading argument must be specified.  The syntax of this request is the same as that of
 It is ignored, as are its children.  .Sx \&de1 .
   It is currently ignored by
   .Xr mandoc 1 ,
   as are its children.
 .Ss \&de  .Ss \&de
 The syntax of this macro is the same as that of  Define a user-defined
 .Sx \&ig ,  .Nm
 except that a leading argument must be specified.  macro.
 It is ignored, as are its children.  Its syntax can be either
   .Bd -literal -offset indent
   .Pf . Cm \&de Ar name
   .Ar macro definition
   \&..
   .Ed
   .Pp
   or
   .Bd -literal -offset indent
   .Pf . Cm \&de Ar name Ar end
   .Ar macro definition
   .Pf . Ar end
   .Ed
   .Pp
   Both forms define or redefine the macro
   .Ar name
   to represent the
   .Ar macro definition ,
   which may consist of one or more input lines, including the newline
   characters terminating each line, optionally containing calls to
   .Nm
   requests,
   .Nm
   macros or high-level macros like
   .Xr man 7
   or
   .Xr mdoc 7
   macros, whichever applies to the document in question.
   .Pp
   Specifying a custom
   .Ar end
   macro works in the same way as for
   .Sx \&ig ;
   namely, the call to
   .Sq Pf . Ar end
   first ends the
   .Ar macro definition ,
   and after that, it is also evaluated as a
   .Nm
   request or
   .Nm
   macro, but not as a high-level macro.
   .Pp
   A user-defined macro can be invoked later using the syntax
   .Pp
   .D1 Pf . Ar name Op Ar argument Op Ar argument ...
   .Pp
   Arguments are separated by blank characters and can be quoted
   using double-quotes
   .Pq Sq \(dq
   to allow inclusion of blank characters into arguments.
   To include the double-quote character into a quoted argument,
   escape it from ending the argument by doubling it.
   .Pp
   The line invoking the user-defined macro will be replaced
   in the input stream by the
   .Ar macro definition ,
   replacing all occurrences of
   .No \e\e$ Ns Ar N ,
   where
   .Ar N
   is a digit, by the
   .Ar N Ns th Ar argument .
   For example,
   .Bd -literal -offset indent
   \&.de ZN
   \efI\e^\e\e$1\e^\efP\e\e$2
   \&..
   \&.ZN XtFree .
   .Ed
   .Pp
   produces
   .Pp
   .D1 \efI\e^XtFree\e^\efP.
   .Pp
   in the input stream, and thus in the output: \fI\^XtFree\^\fP.
   .Pp
   Since user-defined macros and strings share a common string table,
   defining a macro
   .Ar name
   clobbers the user-defined string
   .Ar name ,
   and the
   .Ar macro definition
   can also be printed using the
   .Sq \e*
   string interpolation syntax described below
   .Sx ds ,
   but this is rarely useful because every macro definition contains at least
   one explicit newline character.
 .Ss \&dei  .Ss \&dei
   Define a user-defined
   .Nm
   macro, specifying the macro name indirectly.
 The syntax of this macro is the same as that of  The syntax of this macro is the same as that of
 .Sx \&ig ,  .Sx \&de .
 except that a leading argument must be specified.  It is currently ignored by
 It is ignored, as are its children.  .Xr mandoc 1 ,
   as are its children.
   .Ss \&de1
   Define a user-defined
   .Nm
   macro that will be executed with
   .Nm
   compatibility mode switched off during macro execution.
   This is a GNU extension not available in traditional
   .Nm
   implementations and not even in older versions of groff.
   Since
   .Xr mandoc 1
   does not implement
   .Nm
   compatibility mode at all, it handles this macro as an alias for
   .Sx \&de .
 .Ss \&ds  .Ss \&ds
 Define a reserved word.  Define a user-defined string.
 Its syntax is as follows:  Its syntax is as follows:
 .Pp  .Pp
 .D1 Pf \. Sx \&ds No Cm key val  .D1 Pf . Cm \&ds Ar name Oo \(dq Oc Ns Ar string
 .Pp  .Pp
 The  The
 .Cm key  .Ar name
 and  and
 .Cm val  .Ar string
 strings are space-separated.  arguments are space-separated.
   If the
   .Ar string
   begins with a double-quote character, that character will not be part
   of the string.
   All remaining characters on the input line form the
   .Ar string ,
   including whitespace and double-quote characters, even trailing ones.
   .Pp
 The  The
 .Cm key  .Ar string
 values may be invoked in subsequent text by using \e*(NN for two-letter  can be interpolated into subsequent text by using
 pairs, \e*N for one-letter, and \e*[NNN] for arbitrary-length values.  .No \e* Ns Bq Ar name
   for a
   .Ar name
   of arbitrary length, or \e*(NN or \e*N if the length of
   .Ar name
   is two or one characters, respectively.
 .Pp  .Pp
 If  Since user-defined strings and macros share a common string table,
 .Cm val  defining a string
 is begun with a double-quote mark, the mark is passed over.  .Ar name
 .Cm val  clobbers the user-defined macro
 consists of  .Ar name ,
 .Em all  and the
 text following this point, including whitespace and trailing  .Ar name
 double-quotes.  used for defining a string can also be invoked as a macro,
 .Ss \&de1  in which case the following input line will be appended to the
 The syntax of this macro is the same as that of  .Ar string ,
 .Sx \&ig ,  forming a new input line passed to the
 except that a leading argument must be specified.  .Nm
 It is ignored, as are its children.  parser.
   For example,
   .Bd -literal -offset indent
   \&.ds badidea .S
   \&.badidea
   H SYNOPSIS
   .Ed
   .Pp
   invokes the
   .Cm SH
   macro when used in a
   .Xr man 7
   document.
   Such abuse is of course strongly discouraged.
 .Ss \&el  .Ss \&el
 The  The
 .Qq else  .Qq else
Line 134  then false is assumed.
Line 289  then false is assumed.
 The syntax of this macro is similar to  The syntax of this macro is similar to
 .Sx \&if  .Sx \&if
 except that the conditional is missing.  except that the conditional is missing.
   .Ss \&hy
   Set automatic hyphenation mode.
   This line-scoped request is currently ignored.
 .Ss \&ie  .Ss \&ie
 The  The
 .Qq if  .Qq if
Line 242  scope of the prior macro, not only the text preceding 
Line 400  scope of the prior macro, not only the text preceding 
 collapsing into a zero-width space.  collapsing into a zero-width space.
 .Ss \&ig  .Ss \&ig
 Ignore input.  Ignore input.
 Accepts the following syntax:  Its syntax can be either
 .Pp  .Bd -literal -offset indent
 .Bd -literal -offset indent -compact  .Pf . Cm \&ig
 \&.ig  .Ar ignored text
 BODY...  
 \&..  \&..
 .Ed  .Ed
 .Bd -literal -offset indent -compact  .Pp
 \&.ig END  or
 BODY...  .Bd -literal -offset indent
 \&.END  .Pf . Cm \&ig Ar end
   .Ar ignored text
   .Pf . Ar end
 .Ed  .Ed
 .Pp  .Pp
 In the first case, input is ignored until a  In the first case, input is ignored until a
 .Sq \&..  .Sq \&..
 macro is encountered on its own line.  macro is encountered on its own line.
 In the second case, input is ignored until a  In the second case, input is ignored until the specified
 .Sq \&.END  .Sq Pf . Ar end
 is encountered.  macro is encountered.
 Text subsequent the  Do not use the escape character
 .Sq \&.END  
 or  
 .Sq \&..  
 is discarded.  
 .Pp  
 Do not use the escape  
 .Sq \e  .Sq \e
 anywhere in the definition of END.  anywhere in the definition of
 It causes very strange behaviour.  .Ar end ;
 Furthermore, if you redefine a  it would cause very strange behaviour.
 .Nm  
 macro, such as  
 .Pp  .Pp
   When the
   .Ar end
   macro is a roff request or a roff macro, like in
   .Pp
 .D1 \&.ig if  .D1 \&.ig if
 .Pp  .Pp
 the subsequent invocation of  the subsequent invocation of
 .Sx \&if  .Sx \&if
 will first signify the end of comment, then be invoked as a macro.  will first terminate the
 This behaviour really shouldn't be counted upon.  .Ar ignored text ,
   then be invoked as usual.
   Otherwise, it only terminates the
   .Ar ignored text ,
   and arguments following it or the
   .Sq \&..
   macro are discarded.
   .Ss \&ne
   Declare the need for the specified minimum vertical space
   before the next trap or the bottom of the page.
   This line-scoped request is currently ignored.
   .Ss \&nh
   Turn off automatic hyphenation mode.
   This line-scoped request is currently ignored.
 .Ss \&rm  .Ss \&rm
 Remove a request, macro or string.  Remove a request, macro or string.
 This macro is intended to have one argument,  This request is intended to have one argument,
 the name of the request, macro or string to be undefined.  the name of the request, macro or string to be undefined.
 Currently, it is ignored including its arguments,  Currently, it is ignored including its arguments,
 and the number of arguments is not checked.  and the number of arguments is not checked.
Line 293  A register is an arbitrary string value that defines s
Line 461  A register is an arbitrary string value that defines s
 which influences parsing and/or formatting.  which influences parsing and/or formatting.
 Its syntax is as follows:  Its syntax is as follows:
 .Pp  .Pp
 .D1 Pf \. Sx \&nr Cm name value  .D1 Pf \. Cm \&nr Ar name Ar value
 .Pp  .Pp
 The  The
 .Cm value  .Ar value
 may, at the moment, only be an integer.  may, at the moment, only be an integer.
 The  The
 .Cm name  .Ar name
 is defined up to the next whitespace.  is defined up to the next whitespace.
 The following register  So far, only the following register
 .Cm name  .Ar name
 requests are recognised:  is recognised:
 .Bl -tag -width Ds  .Bl -tag -width Ds
 .It Cm nS  .It Cm nS
 If set to a positive integer value, certain  If set to a positive integer value, certain
Line 318  Note that invoking a new
Line 486  Note that invoking a new
 .Xr mdoc 7  .Xr mdoc 7
 section will unset this value.  section will unset this value.
 .El  .El
   .Ss \&so
   Include a source file.
   Its syntax is as follows:
   .Pp
   .D1 Pf \. Cm \&so Ar file
   .Pp
   The
   .Ar file
   will be read and its contents processed as input in place of the
   .Sq \&.so
   request line.
   To avoid inadvertant inclusion of unrelated files,
   .Xr mandoc 1
   only accepts relative paths not containing the strings
   .Qq ../
   and
   .Qq /.. .
 .Ss \&tr  .Ss \&tr
 Output character translation.  Output character translation.
 This macro is intended to have one argument,  This macro is intended to have one argument,
Line 354  and family would print funny white-spaces with histori
Line 539  and family would print funny white-spaces with histori
 depending on next-line syntax.  depending on next-line syntax.
 .El  .El
 .Sh AUTHORS  .Sh AUTHORS
 The  .An -nosplit
   This partial
 .Nm  .Nm
 reference was written by  reference was written by
 .An Kristaps Dzonsons Aq kristaps@bsd.lv .  .An Kristaps Dzonsons Aq kristaps@bsd.lv
   and
   .An Ingo Schwarze Aq schwarze@openbsd.org .

Legend:
Removed from v.1.14  
changed lines
  Added in v.1.15

CVSweb