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

Diff for /mandoc/roff.7 between version 1.47 and 1.62

version 1.47, 2014/02/14 23:50:57 version 1.62, 2015/01/20 19:39:34
Line 239  pica (~1/6 inch)
Line 239  pica (~1/6 inch)
 .It p  .It p
 point (~1/72 inch)  point (~1/72 inch)
 .It f  .It f
 synonym for  scale
 .Sq u  .Sq u
   by 65536
 .It v  .It v
 default vertical span  default vertical span
 .It m  .It m
Line 254  width of rendered
Line 255  width of rendered
 .Pq en  .Pq en
 character  character
 .It u  .It u
 default horizontal span  default horizontal span for the terminal
 .It M  .It M
 mini-em (~1/100 em)  mini-em (~1/100 em)
 .El  .El
Line 262  mini-em (~1/100 em)
Line 263  mini-em (~1/100 em)
 Using anything other than  Using anything other than
 .Sq m ,  .Sq m ,
 .Sq n ,  .Sq n ,
 .Sq u ,  
 or  or
 .Sq v  .Sq v
 is necessarily non-portable across output media.  is necessarily non-portable across output media.
Line 402  language defines many more requests not implemented in
Line 402  language defines many more requests not implemented in
 .Ss \&ad  .Ss \&ad
 Set line adjustment mode.  Set line adjustment mode.
 This line-scoped request is intended to have one argument to select  This line-scoped request is intended to have one argument to select
 normal, left, right, or centre adjustment for subsequent text.  normal, left, right, or center adjustment for subsequent text.
 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.
 .Ss \&am  .Ss \&am
 Append to a macro definition.  Append to a macro definition.
 The syntax of this request is the same as that of  The syntax of this request is the same as that of
 .Sx \&de .  .Sx \&de .
 It is currently ignored by  
 .Xr mandoc 1 ,  
 as are its children.  
 .Ss \&ami  .Ss \&ami
 Append to a macro definition, specifying the macro name indirectly.  Append to a macro definition, specifying the macro name indirectly.
 The syntax of this request is the same as that of  The syntax of this request is the same as that of
 .Sx \&dei .  .Sx \&dei .
 It is currently ignored by  
 .Xr mandoc 1 ,  
 as are its children.  
 .Ss \&am1  .Ss \&am1
 Append to a macro definition, switching roff compatibility mode off  Append to a macro definition, switching roff compatibility mode off
 during macro execution.  during macro execution.
 The syntax of this request is the same as that of  The syntax of this request is the same as that of
 .Sx \&de1 .  .Sx \&de1 .
 It is currently ignored by  Since
 .Xr mandoc 1 ,  .Xr mandoc 1
 as are its children.  does not implement
   .Nm
   compatibility mode at all, it handles this request as an alias for
   .Sx \&am .
 .Ss \&as  .Ss \&as
 Append to a user-defined string.  Append to a user-defined string.
 The syntax of this request is the same as that of  The syntax of this request is the same as that of
Line 546  one explicit newline character.
Line 543  one explicit newline character.
 In order to prevent endless recursion, both groff and  In order to prevent endless recursion, both groff and
 .Xr mandoc 1  .Xr mandoc 1
 limit the stack depth for expanding macros and strings  limit the stack depth for expanding macros and strings
 to a large, but finite number.  to a large, but finite number, and
 Do not rely on the exact value of this limit.  .Xr mandoc 1
   also limits the length of the expanded input line.
   Do not rely on the exact values of these limits.
 .Ss \&dei  .Ss \&dei
 Define a  Define a
 .Nm  .Nm
 macro, specifying the macro name indirectly.  macro, specifying the macro name indirectly.
 The syntax of this request is the same as that of  The syntax of this request is the same as that of
 .Sx \&de .  .Sx \&de .
 It is currently ignored by  The request
 .Xr mandoc 1 ,  .Pp
 as are its children.  .D1 Pf . Cm \&dei Ar name Op Ar end
   .Pp
   has the same effect as:
   .Pp
   .D1 Pf . Cm \&de No \e* Ns Bo Ar name Bc Op \e* Ns Bq Ar end
 .Ss \&de1  .Ss \&de1
 Define a  Define a
 .Nm  .Nm
Line 659  This line-scoped request is intended to have one argum
Line 662  This line-scoped request is intended to have one argum
 the font family to be selected.  the font family to be selected.
 It is a groff extension, and currently, it is ignored including its  It is a groff extension, and currently, it is ignored including its
 arguments, and the number of arguments is not checked.  arguments, and the number of arguments is not checked.
   .Ss \&ft
   Change the font.
   Its syntax is as follows:
   .Pp
   .D1 Pf . Cm \&ft Op Ar font
   .Pp
   The following
   .Ar font
   arguments are supported:
   .Bl -tag -width 4n -offset indent
   .It Cm B , BI , 3 , 4
   switches to
   .Sy bold
   font
   .It Cm I , 2
   switches to
   .Em underlined
   font
   .It Cm R , CW , 1
   switches to normal font
   .It Cm P No "or no argument"
   switches back to the previous font
   .El
   .Pp
   This request takes effect only locally, may be overridden by macros
   and escape sequences, and is only supported in
   .Xr man 7
   for now.
 .Ss \&hw  .Ss \&hw
 Specify hyphenation points in words.  Specify hyphenation points in words.
 This line-scoped request is currently ignored.  This line-scoped request is currently ignored.
Line 677  Its syntax is equivalent to
Line 708  Its syntax is equivalent to
 .Sx \&if .  .Sx \&if .
 .Ss \&if  .Ss \&if
 Begins a conditional.  Begins a conditional.
 Right now, the conditional evaluates to true  This request has the following syntax:
 if and only if it starts with the letter  .Bd -literal -offset indent
 .Sy n ,  \&.if COND BODY
 indicating processing in nroff style as opposed to troff style.  .Ed
   .Bd -literal -offset indent
   \&.if COND \e{BODY
   BODY...\e}
   .Ed
   .Bd -literal -offset indent
   \&.if COND \e{\e
   BODY...
   \&.\e}
   .Ed
   .Pp
   COND is a conditional statement.
   Currently,
   .Xr mandoc 1
   supports the following subset of roff conditionals:
   .Bl -bullet
   .It
   If
   .Sq \&!
   is prefixed to COND, the condition is logically inverted.
   .It
   If the first character of COND is
   .Sq n
   .Pq nroff mode
   or
   .Sq o
   .Pq odd page ,
   COND evaluates to true.
   .It
   If the first character of COND is
   .Sq c
   .Pq character available ,
   .Sq d
   .Pq string defined ,
   .Sq e
   .Pq even page ,
   .Sq r
   .Pq register accessed ,
   .Sq t
   .Pq troff mode ,
   or
   .Sq v
   .Pq vroff mode ,
   COND evaluates to false.
   .It
   If COND starts with a parenthesis or with an optionally signed
   integer number, it is evaluated according to the rules of
   .Sx Numerical expressions
   explained below.
   It evaluates to true if the result is positive,
   or to false if the result is zero or negative.
   .It
   Otherwise, the first character of COND is regarded as a delimiter
   and COND evaluates to true if the string extending from its first
   to its second occurrence is equal to the string extending from its
   second to its third occurrence.
   .It
   If COND cannot be parsed, it evaluates to false.
   .El
   .Pp
 If a conditional is false, its children are not processed, but are  If a conditional is false, its children are not processed, but are
 syntactically interpreted to preserve the integrity of the input  syntactically interpreted to preserve the integrity of the input
 document.  document.
Line 698  will continue to syntactically interpret to the block 
Line 788  will continue to syntactically interpret to the block 
 conditional.  conditional.
 Sub-conditionals, in this case, obviously inherit the truth value of  Sub-conditionals, in this case, obviously inherit the truth value of
 the parent.  the parent.
 This request has the following syntax:  
 .Bd -literal -offset indent  
 \&.if COND \e{\e  
 BODY...  
 \&.\e}  
 .Ed  
 .Bd -literal -offset indent  
 \&.if COND \e{ BODY  
 BODY... \e}  
 .Ed  
 .Bd -literal -offset indent  
 \&.if COND \e{ BODY  
 BODY...  
 \&.\e}  
 .Ed  
 .Bd -literal -offset indent  
 \&.if COND \e  
 BODY  
 .Ed  
 .Pp  .Pp
 COND is a conditional statement.  
 roff allows for complicated conditionals; mandoc is much simpler.  
 At this time, mandoc supports only  
 .Sq n ,  
 evaluating to true;  
 and  
 .Sq t ,  
 .Sq e ,  
 and  
 .Sq o ,  
 evaluating to false.  
 All other invocations are read up to the next end of line or space and  
 evaluate as false.  
 .Pp  
 If the BODY section is begun by an escaped brace  If the BODY section is begun by an escaped brace
 .Sq \e{ ,  .Sq \e{ ,
 scope continues until a closing-brace escape sequence  scope continues until the end of the input line containing the
 .Sq \.\e} .  matching closing-brace escape sequence
   .Sq \e} .
 If the BODY is not enclosed in braces, scope continues until  If the BODY is not enclosed in braces, scope continues until
 the end of the line.  the end of the line.
 If the COND is followed by a BODY on the same line, whether after a  If the COND is followed by a BODY on the same line, whether after a
Line 815  Otherwise, it only terminates the
Line 873  Otherwise, it only terminates the
 and arguments following it or the  and arguments following it or the
 .Sq \&..  .Sq \&..
 request are discarded.  request are discarded.
   .Ss \&ll
   Change the output line length.
   Its syntax is as follows:
   .Pp
   .D1 Pf . Cm \&ll Op Oo +|- Oc Ns Ar width
   .Pp
   If the
   .Ar width
   argument is omitted, the line length is reset to its previous value.
   The default setting for terminal output is 78n.
   If a sign is given, the line length is added to or subtracted from;
   otherwise, it is set to the provided value.
   Using this request in new manuals is discouraged for several reasons,
   among others because it overrides the
   .Xr mandoc 1
   .Fl O Cm width
   command line option.
 .Ss \&ne  .Ss \&ne
 Declare the need for the specified minimum vertical space  Declare the need for the specified minimum vertical space
 before the next trap or the bottom of the page.  before the next trap or the bottom of the page.
Line 822  This line-scoped request is currently ignored.
Line 897  This line-scoped request is currently ignored.
 .Ss \&nh  .Ss \&nh
 Turn off automatic hyphenation mode.  Turn off automatic hyphenation mode.
 This line-scoped request is currently ignored.  This line-scoped request is currently ignored.
 .Ss \&rm  
 Remove a request, macro or string.  
 This request is intended to have one argument,  
 the name of the request, macro or string to be undefined.  
 Currently, it is ignored including its arguments,  
 and the number of arguments is not checked.  
 .Ss \&nr  .Ss \&nr
 Define or change a register.  Define or change a register.
 A register is an arbitrary string value that defines some sort of state,  A register is an arbitrary string value that defines some sort of state,
 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 \. Cm \&nr Ar name Oo +|- Oc Ns Ar value  .D1 Pf \. Cm \&nr Ar name Oo +|- Oc Ns Ar expression
 .Pp  .Pp
 The  For the syntax of
 .Ar value  .Ar expression ,
 may, at the moment, only be an integer.  see
   .Sx Numerical expressions
   below.
 If it is prefixed by a sign, the register will be  If it is prefixed by a sign, the register will be
 incremented or decremented instead of assigned to.  incremented or decremented instead of assigned to.
 .Pp  .Pp
Line 868  Turn on no-space mode.
Line 939  Turn on no-space mode.
 This line-scoped request is intended to take no arguments.  This line-scoped request is intended to take no arguments.
 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.
   .Ss \&pl
   Change page length.
   This line-scoped request is intended to take one height argument.
   Currently, it is ignored including its arguments,
   and the number of arguments is not checked.
 .Ss \&ps  .Ss \&ps
 Change point size.  Change point size.
 This line-scoped request is intended to take one numerical argument.  This line-scoped request is intended to take one numerical argument.
 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.
   .Ss \&rm
   Remove a request, macro or string.
   Its syntax is as follows:
   .Pp
   .D1 Pf \. Cm \&rm Ar name
   .Ss \&rr
   Remove a register.
   Its syntax is as follows:
   .Pp
   .D1 Pf \. Cm \&rr Ar name
 .Ss \&so  .Ss \&so
 Include a source file.  Include a source file.
 Its syntax is as follows:  Its syntax is as follows:
Line 941  Begin a table, which formats input in aligned rows and
Line 1027  Begin a table, which formats input in aligned rows and
 See  See
 .Xr tbl 7  .Xr tbl 7
 for a description of the tbl language.  for a description of the tbl language.
   .Ss Numerical expressions
   The
   .Sx \&nr ,
   .Sx \&if ,
   and
   .Sx \&ie
   requests accept integer numerical expressions as arguments.
   These are always evaluated using the C
   .Vt int
   type; integer overflow works the same way as in the C language.
   Numbers consist of an arbitrary number of digits
   .Sq 0
   to
   .Sq 9
   prefixed by an optional sign
   .Sq +
   or
   .Sq - .
   .Pp
   The following binary operators are implemented.
   Unless otherwise stated, they behave as in the C language:
   .Pp
   .Bl -tag -width 2n -compact
   .It Ic +
   addition
   .It Ic -
   subtraction
   .It Ic *
   multiplication
   .It Ic /
   division
   .It Ic %
   remainder of division
   .It Ic <
   less than
   .It Ic >
   greater than
   .It Ic ==
   equal to
   .It Ic =
   equal to, same effect as
   .Ic ==
   (this differs from C)
   .It Ic <=
   less than or equal to
   .It Ic >=
   greater than or equal to
   .It Ic <>
   not equal to (corresponds to C
   .Ic != ;
   this one is of limited portability, it is supported by Heirloom roff,
   but not by groff)
   .It Ic &
   logical and (corresponds to C
   .Ic && )
   .It Ic \&:
   logical or (corresponds to C
   .Ic \&|| )
   .It Ic <?
   minimum (not available in C)
   .It Ic >?
   maximum (not available in C)
   .El
   .Pp
   There is no concept of precendence; evaluation proceeds from left to right,
   except when subexpressions are enclosed in parantheses.
   Inside parentheses, whitespace is ignored.
 .Sh ESCAPE SEQUENCE REFERENCE  .Sh ESCAPE SEQUENCE REFERENCE
 The  The
 .Xr mandoc 1  .Xr mandoc 1
Line 1029  Digit width space character.
Line 1182  Digit width space character.
 Anchor definition; ignored by  Anchor definition; ignored by
 .Xr mandoc 1 .  .Xr mandoc 1 .
 .Ss \eB\(aq Ns Ar string Ns \(aq  .Ss \eB\(aq Ns Ar string Ns \(aq
 Test whether  Interpolate
   .Sq 1
   if
 .Ar string  .Ar string
 is a numerical expession; ignored by  conforms to the syntax of
 .Xr mandoc 1 .  .Sx Numerical expressions
   explained above and
   .Sq 0
   otherwise.
 .Ss \eb\(aq Ns Ar string Ns \(aq  .Ss \eb\(aq Ns Ar string Ns \(aq
 Bracket building function; ignored by  Bracket building function; ignored by
 .Xr mandoc 1 .  .Xr mandoc 1 .
Line 1040  Bracket building function; ignored by
Line 1198  Bracket building function; ignored by
 .Sx Special Characters  .Sx Special Characters
 with names of arbitrary length.  with names of arbitrary length.
 .Ss \ec  .Ss \ec
 Interrupt text processing to insert requests or macros; ignored by  When encountered at the end of an input text line,
 .Xr mandoc 1 .  the next input text line is considered to continue that line,
   even if there are request or macro lines in between.
   No whitespace is inserted.
 .Ss \eD\(aq Ns Ar string Ns \(aq  .Ss \eD\(aq Ns Ar string Ns \(aq
 Draw graphics function; ignored by  Draw graphics function; ignored by
 .Xr mandoc 1 .  .Xr mandoc 1 .
Line 1156  Vertical motion; ignored by
Line 1316  Vertical motion; ignored by
 .Xr mandoc 1 .  .Xr mandoc 1 .
 .Ss \ew\(aq Ns Ar string Ns \(aq  .Ss \ew\(aq Ns Ar string Ns \(aq
 Interpolate the width of the  Interpolate the width of the
 .Ar string ;  .Ar string .
 ignored by  The
 .Xr mandoc 1 .  .Xr mandoc 1
   implementation assumes that after expansion of user-defined strings, the
   .Ar string
   only contains normal characters, no escape sequences, and that each
   character has a width of 24 basic units.
 .Ss \eX\(aq Ns Ar string Ns \(aq  .Ss \eX\(aq Ns Ar string Ns \(aq
 Output  Output
 .Ar string  .Ar string
Line 1194  The term
Line 1358  The term
 refers to groff version 1.15.  refers to groff version 1.15.
 .Pp  .Pp
 .Bl -dash -compact  .Bl -dash -compact
   .It
   The
   .Sq u
   scaling unit is the default terminal unit.
   In traditional troff systems, this unit would change depending on the
   output media.
 .It  .It
 In mandoc, the  In mandoc, the
 .Sx \&EQ ,  .Sx \&EQ ,
Legend:
Removed from v.1.47  
changed lines
  Added in v.1.62
CVSweb