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

Diff for /mandoc/roff.7 between version 1.45 and 1.48

version 1.45, 2013/12/15 21:23:52 version 1.48, 2014/03/08 04:43:54
Line 1 
Line 1 
 .\"     $Id$  .\"     $Id$
 .\"  .\"
 .\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>  .\" Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010, 2011 Ingo Schwarze <schwarze@openbsd.org>  .\" Copyright (c) 2010, 2011, 2013, 2014 Ingo Schwarze <schwarze@openbsd.org>
 .\"  .\"
 .\" Permission to use, copy, modify, and distribute this software for any  .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above  .\" purpose with or without fee is hereby granted, provided that the above
Line 32  and
Line 32  and
 manual formatting languages are based on it,  manual formatting languages are based on it,
 many real-world manuals use small numbers of  many real-world manuals use small numbers of
 .Nm  .Nm
 requests intermixed with their  requests and escape sequences intermixed with their
 .Xr mdoc 7  .Xr mdoc 7
 or  or
 .Xr man 7  .Xr man 7
Line 41  To properly format such manuals, the
Line 41  To properly format such manuals, the
 .Xr mandoc 1  .Xr mandoc 1
 utility supports a tiny subset of  utility supports a tiny subset of
 .Nm  .Nm
 requests.  requests and escapes.
 Only these requests supported by  Only these requests and escapes supported by
 .Xr mandoc 1  .Xr mandoc 1
 are documented in the present manual,  are documented in the present manual,
 together with the basic language syntax shared by  together with the basic language syntax shared by
Line 85  documents may contain only graphable 7-bit ASCII chara
Line 85  documents may contain only graphable 7-bit ASCII chara
 character, and, in certain circumstances, the tab character.  character, and, in certain circumstances, the tab character.
 The backslash character  The backslash character
 .Sq \e  .Sq \e
 indicates the start of an escape sequence for  indicates the start of an escape sequence, used for example for
 .Sx Comments ,  .Sx Comments ,
 .Sx Special Characters ,  .Sx Special Characters ,
 .Sx Predefined Strings ,  .Sx Predefined Strings ,
Line 93  and
Line 93  and
 user-defined strings defined using the  user-defined strings defined using the
 .Sx ds  .Sx ds
 request.  request.
   For a listing of escape sequences, consult the
   .Sx ESCAPE SEQUENCE REFERENCE
   below.
 .Ss Comments  .Ss Comments
 Text following an escaped double-quote  Text following an escaped double-quote
 .Sq \e\(dq ,  .Sq \e\(dq ,
Line 424  The syntax of this request is the same as that of
Line 427  The syntax of this request is the same as that of
 It is currently ignored by  It is currently ignored by
 .Xr mandoc 1 ,  .Xr mandoc 1 ,
 as are its children.  as are its children.
   .Ss \&as
   Append to a user-defined string.
   The syntax of this request is the same as that of
   .Sx \&ds .
   If a user-defined string with the specified name does not yet exist,
   it is set to the empty string before appending.
 .Ss \&cc  .Ss \&cc
 Changes the control character.  Changes the control character.
 Its syntax is as follows:  Its syntax is as follows:
Line 436  If
Line 445  If
 is not specified, the control character is reset to  is not specified, the control character is reset to
 .Sq \&. .  .Sq \&. .
 Trailing characters are ignored.  Trailing characters are ignored.
   .Ss \&ce
   Center some lines.
   This line-scoped request is intended to take one integer argument,
   specifying how many lines to center.
   Currently, it is ignored including its arguments, and the number
   of arguments is not checked.
 .Ss \&de  .Ss \&de
 Define a  Define a
 .Nm  .Nm
Line 662  Its syntax is equivalent to
Line 677  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 ,
   or
   .Sq t
   .Pq troff mode ,
   COND evaluates to false.
   .It
   If COND starts with a digit, optionally prefixed by a minus sign,
   it is evaluated as a numerical expression of the form
   .Ar number operator number ,
   where
   .Ar operator
   is one of
   .Sq < ,
   .Sq <= ,
   .Sq = ,
   .Sq >= ,
   or
   .Sq > .
   .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 683  will continue to syntactically interpret to the block 
Line 761  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 824  Its syntax is as follows:
Line 870  Its syntax is as follows:
 The  The
 .Ar value  .Ar value
 may, at the moment, only be an integer.  may, at the moment, only be an integer.
 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
 The following register  The following register
Line 926  Begin a table, which formats input in aligned rows and
Line 972  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.
   .Sh ESCAPE SEQUENCE REFERENCE
   The
   .Xr mandoc 1
   .Nm
   parser recognises the following escape sequences.
   Note that the
   .Nm
   language defines more escape sequences not implemented in
   .Xr mandoc 1 .
   In
   .Xr mdoc 7
   and
   .Xr man 7
   documents, using escape sequences is discouraged except for those
   described in the
   .Sx LANGUAGE SYNTAX
   section above.
   .Pp
   A backslash followed by any character not listed here
   simply prints that character itself.
   .Ss \e<newline>
   A backslash at the end of an input line can be used to continue the
   logical input line on the next physical input line, joining the text
   on both lines together as if it were on a single input line.
   .Ss \e<space>
   The escape sequence backslash-space
   .Pq Sq \e\ \&
   is an unpaddable space-sized non-breaking space character; see
   .Sx Whitespace .
   .Ss \e\(dq
   The rest of the input line is treated as
   .Sx Comments .
   .Ss \e%
   Hyphenation allowed at this point of the word; ignored by
   .Xr mandoc 1 .
   .Ss \e&
   Non-printing zero-width character; see
   .Sx Whitespace .
   .Ss \e\(aq
   Acute accent special character; use
   .Sq \e(aa
   instead.
   .Ss \e( Ns Ar cc
   .Sx Special Characters
   with two-letter names, see
   .Xr mandoc_char 7 .
   .Ss \e*[ Ns Ar name ]
   Interpolate the string with the
   .Ar name ;
   see
   .Sx Predefined Strings
   and
   .Sx ds .
   For short names, there are variants
   .No \e* Ns Ar c
   and
   .No \e*( Ns Ar cc .
   .Ss \e-
   Special character
   .Dq mathematical minus sign .
   .Ss \e[ Ns Ar name ]
   .Sx Special Characters
   with names of arbitrary length, see
   .Xr mandoc_char 7 .
   .Ss \e^
   One-twelfth em half-narrow space character, effectively zero-width in
   .Xr mandoc 1 .
   .Ss \e`
   Grave accent special character; use
   .Sq \e(ga
   instead.
   .Ss \e{
   Begin conditional input; see
   .Sx if .
   .Ss \e\(ba
   One-sixth em narrow space character, effectively zero-width in
   .Xr mandoc 1 .
   .Ss \e}
   End conditional input; see
   .Sx if .
   .Ss \e~
   Paddable non-breaking space character.
   .Ss \e0
   Digit width space character.
   .Ss \eA\(aq Ns Ar string Ns \(aq
   Anchor definition; ignored by
   .Xr mandoc 1 .
   .Ss \eB\(aq Ns Ar string Ns \(aq
   Test whether
   .Ar string
   is a numerical expession; ignored by
   .Xr mandoc 1 .
   .Ss \eb\(aq Ns Ar string Ns \(aq
   Bracket building function; ignored by
   .Xr mandoc 1 .
   .Ss \eC\(aq Ns Ar name Ns \(aq
   .Sx Special Characters
   with names of arbitrary length.
   .Ss \ec
   Interrupt text processing to insert requests or macros; ignored by
   .Xr mandoc 1 .
   .Ss \eD\(aq Ns Ar string Ns \(aq
   Draw graphics function; ignored by
   .Xr mandoc 1 .
   .Ss \ed
   Move down by half a line; ignored by
   .Xr mandoc 1 .
   .Ss \ee
   Backslash special character.
   .Ss \eF[ Ns Ar name ]
   Switch font family (groff extension); ignored by
   .Xr mandoc 1 .
   For short names, there are variants
   .No \eF Ns Ar c
   and
   .No \eF( Ns Ar cc .
   .Ss \ef[ Ns Ar name ]
   Switch to the font
   .Ar name ,
   see
   .Sx Text Decoration .
   For short names, there are variants
   .No \ef Ns Ar c
   and
   .No \ef( Ns Ar cc .
   .Ss \eg[ Ns Ar name ]
   Interpolate the format of a number register; ignored by
   .Xr mandoc 1 .
   For short names, there are variants
   .No \eg Ns Ar c
   and
   .No \eg( Ns Ar cc .
   .Ss \eH\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq
   Set the height of the current font; ignored by
   .Xr mandoc 1 .
   .Ss \eh\(aq Ns Ar number Ns \(aq
   Horizontal motion; ignored by
   .Xr mandoc 1 .
   .Ss \ek[ Ns Ar name ]
   Mark horizontal input place in register; ignored by
   .Xr mandoc 1 .
   For short names, there are variants
   .No \ek Ns Ar c
   and
   .No \ek( Ns Ar cc .
   .Ss \eL\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq
   Vertical line drawing function; ignored by
   .Xr mandoc 1 .
   .Ss \el\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq
   Horizontal line drawing function; ignored by
   .Xr mandoc 1 .
   .Ss \eM[ Ns Ar name ]
   Set fill (background) color (groff extension); ignored by
   .Xr mandoc 1 .
   For short names, there are variants
   .No \eM Ns Ar c
   and
   .No \eM( Ns Ar cc .
   .Ss \em[ Ns Ar name ]
   Set glyph drawing color (groff extension); ignored by
   .Xr mandoc 1 .
   For short names, there are variants
   .No \em Ns Ar c
   and
   .No \em( Ns Ar cc .
   .Ss \eN\(aq Ns Ar number Ns \(aq
   Character
   .Ar number
   on the current font.
   .Ss \en[ Ns Ar name ]
   Interpolate the number register
   .Ar name .
   For short names, there are variants
   .No \en Ns Ar c
   and
   .No \en( Ns Ar cc .
   .Ss \eo\(aq Ns Ar string Ns \(aq
   Overstrike
   .Ar string ;
   ignored by
   .Xr mandoc 1 .
   .Ss \eR\(aq Ns Ar name Oo +|- Oc Ns Ar number Ns \(aq
   Set number register; ignored by
   .Xr mandoc 1 .
   .Ss \eS\(aq Ns Ar number Ns \(aq
   Slant output; ignored by
   .Xr mandoc 1 .
   .Ss \es\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq
   Change point size; ignored by
   .Xr mandoc 1 .
   Alternative forms
   .No \es Ns Oo +|- Oc Ns Ar n ,
   .No \es Ns Oo +|- Oc Ns \(aq Ns Ar number Ns \(aq ,
   .No \es Ns [ Oo +|- Oc Ns Ar number ] ,
   and
   .No \es Ns Oo +|- Oc Ns [ Ar number Ns ]
   are also parsed and ignored.
   .Ss \et
   Horizontal tab; ignored by
   .Xr mandoc 1 .
   .Ss \eu
   Move up by half a line; ignored by
   .Xr mandoc 1 .
   .Ss \eV[ Ns Ar name ]
   Interpolate an environment variable; ignored by
   .Xr mandoc 1 .
   For short names, there are variants
   .No \eV Ns Ar c
   and
   .No \eV( Ns Ar cc .
   .Ss \ev\(aq Ns Ar number Ns \(aq
   Vertical motion; ignored by
   .Xr mandoc 1 .
   .Ss \ew\(aq Ns Ar string Ns \(aq
   Interpolate the width of the
   .Ar string ;
   ignored by
   .Xr mandoc 1 .
   .Ss \eX\(aq Ns Ar string Ns \(aq
   Output
   .Ar string
   as device control function; ignored in nroff mode and by
   .Xr mandoc 1 .
   .Ss \ex\(aq Ns Ar number Ns \(aq
   Extra line space function; ignored by
   .Xr mandoc 1 .
   .Ss \eY[ Ns Ar name ]
   Output a string as a device control function; ignored in nroff mode and by
   .Xr mandoc 1 .
   For short names, there are variants
   .No \eY Ns Ar c
   and
   .No \eY( Ns Ar cc .
   .Ss \eZ\(aq Ns Ar string Ns \(aq
   Print
   .Ar string
   with zero width and height; ignored by
   .Xr mandoc 1 .
   .Ss \ez
   Output the next character without advancing the cursor position;
   approximated in
   .Xr mandoc 1
   by simply skipping the next character.
 .Sh COMPATIBILITY  .Sh COMPATIBILITY
 This section documents compatibility between mandoc and other  This section documents compatibility between mandoc and other
 .Nm  .Nm
Legend:
Removed from v.1.45  
changed lines
  Added in v.1.48
CVSweb