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

  man pages->NetBSD man pages -> groff (7)              
Title
Content
Arch
Section
 

GROFF(7)

Contents


NAME    [Toc]    [Back]

       groff - a short reference for the GNU roff language

DESCRIPTION    [Toc]    [Back]

       groff  stands  for GNU roff and is the free implementation
       of the roff type-setting system.  See roff(7) for a survey
       and the background of the groff system.

       This  document gives only short descriptions of the predefined
 roff language elements as used in groff.   Both  the
       classical  features and the groff extensions are provided.

       Historically, the roff language was called  troff.   groff
       is  compatible  with  the  classical  system  and provides
       proper extensions.  So in GNU, the terms roff, troff,  and
       groff  language  could be used as synonyms.  However troff
       slightly tends to refer more  to  the  classical  aspects,
       whereas  groff  emphasizes the GNU extensions, and roff is
       the general term for the language.

       This file is only a short version of the complete documentation
 that is found in the groff info(1) file, which contains
 more detailed, actual, and concise information.

       The general syntax for writing groff  documents  is  relatively
  easy,  but writing extensions to the roff language
       can be a bit harder.

       The roff language is line-oriented.  There  are  only  two
       kinds of lines, control lines and text lines.  The control
       lines start with a control character, by default a  period
       "." or a single quote "'"; all other lines are text lines.

       Control lines represent commands,  optionally  with  arguments.
   They have the following syntax.  The leading control
 character can be followed by a  command  name;  arguments,
  if  any,  are separated by blanks from the command
       name and among themselves, for example,

              .command_name arg1 arg2

       For indentation, any number of space or tab characters can
       be  inserted between the leading control character and the
       command name, but the control character  must  be  on  the
       first position of the line.

       Text lines represent the parts that will be printed.  They
       can be modified by escape sequences, which are  recognized
       by  a leading backslash `\'. These are in-line or even inword
 formatting elements or functions.  Some of these take
       arguments separated by single quotes "'", others are regulated
 by a length encoding introduced by an open parenthesis
 `(' or enclosed in brackets `[' and `]'.

       The  roff language provides flexible instruments for writing
 language extension, such as macros.  When interpreting
       macro  definitions, the roff system enters a special operating
 mode, called the copy mode.

       The copy mode behavior can be quite tricky, but there  are
       some rules that ensure a safe usage.

       1.     Printable  backslashes must be denoted as \e. To be
              more precise,  \e  represents  the  current  escape
              character.  To get a backslash glyph, use \(rs.

       2.     Double all backslashes.

       3.     Begin  all  text lines with the special non-spacing
              character \&.

       This does not produce the  most  efficient  code,  but  it
       should  work  as  a first measure.  For better strategies,
       see the groff info file and groff_tmac(5).

       Reading roff source files is easier, just reduce all  double
  backslashes to a single one in all macro definitions.

GROFF ELEMENTS    [Toc]    [Back]

       The roff language elements add formatting information to a
       text  file.   The fundamental elements are predefined commands
 and variables that make roff a  full-blown  programming
 language.

       There  are two kinds of roff commands, possibly with arguments.
  Requests are written on a line of their own starting
  with a dot `.' or a "'", whereas Escape sequences are
       in-line functions and in-word formatting elements starting
       with a backslash `\'.

       The  user can define her own formatting commands using the
       .de request.  These commands are called macros,  but  they
       are  used  exactly like requests.  Macro packages are predefined
 sets of macros written in the groff  language.   A
       user's possibilities to create escape sequences herself is
       very limited, only special characters can be mapped.

       The groff language provides  several  kinds  of  variables
       with  different  interfaces.   There are pre-defined variables,
 but the user can define her own variables as  well.

       String  variables store character sequences.  They are set
       with the .ds  request  and  retrieved  by  the  \*  escape
       sequences.

       Register  variables  can  store  numerical values, numbers
       with a scale unit, and occasionally  string-like  objects.
       They  are set with the .nr request and retrieved by the \n
       escape sequences.

       Environments allow the user to  temporarily  store  global
       formatting  parameters  like  line length, font size, etc.
       for later reuse.  This is done by the .ev request.

       Fonts are identified either by a name or  by  an  internal
       number.   The current font is chosen by the .ft request or
       by the \f  escape  sequences.   Each  device  has  special
       fonts,  but  the  following  fonts  are  available for all
       devices.  R is the standard font Roman.   B  is  its  bold
       counterpart.   The  italic  font is called I is everywhere
       available, but on text devices,  it  is  displayed  as  an
       underlined  Roman font.  For the graphical output devices,
       there exist constant-width pendants of these font, CR, CI,
       and  CB.   On text devices, all characters have a constant
       width anyway.

       Moreover, there are some advanced roff elements.  A diver-
       sion  stores  information into a macro for later usage.  A
       trap is a positional condition like a  certain  number  of
       lines  from  page  top  or in a diversion or in the input.
       Some action can be prescribed to be run automatically when
       the condition is met.

       More  detailed  information can be found in the groff info
       file.

CONTROL CHARACTERS    [Toc]    [Back]

       There is a small set of characters  that  have  a  special
       controlling task in certain conditions.

       .      A dot is only special at the beginning of a line or
              after the condition in the requests .if, .ie,  .el,
              and  .while. There it is the control character that
              introduces  a  request  (or  macro).   The  special
              behavior can be delayed by using the \. escape.  By
              using the .cc request, the control character can be
              set  to a different character, making the dot `.' a
              non-special character.

              In all other positions, it just means a dot character.
   In  text  paragraphs,  it is advantageous to
              start each sentence at a line of its own.

       '      The single quote has two controlling tasks.  At the
              beginning of a line and in the conditional requests
              it is the  non-breaking  control  character.   That
              means  that  it  introduces a request like the dot,
              but with the additional property that this  request
              doesn't  cause  a  linebreak.   By  using  the  .c2
              request, the non-break control character can be set
              to a different character.

              As  a  second  task,  it  is the most commonly used
              argument  separator  in  some   functional   escape
              sequences  (but  any pair of characters not part of
              the argument will work).  In all  other  positions,
              it  denotes  the single quote or apostrophe character.
  Groff  provides  a  printable  representation
              with the \(cq escape sequence.

       "      The  double  quote  is used to enclose arguments in
              requests and macros.  The escaped double  quote  \"
              introduces  a  comment.   Otherwise, it is not special.
  Groff provides  a  printable  representation
              with the \(dq escape sequence.

       \      The backslash usually introduces an escape sequence
              (this can be  changed  with  the  ec  request).   A
              printed  version  of the escape character is the \e
              escape; a backslash glyph can be obtained by \(rs.

       (      The open parenthesis  is  only  special  in  escape
              sequences  when introducing an escape name or argument
 consisting  of  exactly  two  characters.   In
              groff, this behavior can be replaced by the [] construct.


       [      The opening bracket is only special in groff escape
              sequences;  there  it  is  used to introduce a long
              escape name or long escape argument.  Otherwise, it
              is non-special, e.g. in macro calls.

       ]      The closing bracket is only special in groff escape
              sequences; there it terminates a long  escape  name
              or long escape argument.  Otherwise, it is non-special.


       space  Space characters are  only  functional  characters.
              They  separate the arguments in requests or macros,
              and the words in text lines.  They are  subject  to
              groff's  horizontal spacing calculations.  To get a
              defined space width,  escape  sequences  like  `\ '
              (this is the escape character followed by a space),
              \|, \^, or \h should be used.

       newline
              In text paragraphs,  newlines  mostly  behave  like
              space characters.  Continuation lines can be specified
 by an escaped newline, i.e., by  specifying  a
              backslash `\' as the last character of a line.

       tab    If  a  tab  character occurs during text the interpreter
 makes a horizontal jump  to  the  next  predefined
  tab  position.   There  is a sophisticated
              interface for handling tab positions.

NUMERICAL EXPRESSIONS    [Toc]    [Back]

       A numerical value is a signed or unsigned integer or float
       with  or  without  an  appended  scale indicator.  A scale
       indicator is a one-character abbreviation for  a  unit  of
       measurement.   A number followed by a scale indicator signifies
 a size value.  By default, numerical values do  not
       have a scale indicator, i.e., they are normal numbers.

       The  roff language defines the following scale indicators.

              c   Centimeter
              i   Inch
              P   Pica = 1/6 inch
              p   Point = 1/72 inch
              m   Em = the font size in points (width of
                  letter `m')
              M   100th of an Em
              n   En = Em/2
              u   Basic unit for actual output device
              v   Vertical line space in basic units
              z   scaled point = 1/sizescale of a point
                  (defined in font DESC file)

       Numerical expressions are combinations  of  the  numerical
       values  defined above with the arithmetical operators `+',
       `-', `*', `/', `%'  (modulo),  the  comparative  operators
       `=='  (this is the same as `='), `<=', `>=', `<', `>', the
       logical operators `&' (and), `:' (or), `!' (not), and  the
       parentheses `(' and `)'.

       Moreover,  groff added the following operators for numerical
 expressions:

           e1>?e2   The maximum of e1 and e2.
           e1<?e2   The minimum of e1 and e2.
           (c;e)    Evaluate e using c as the default
                    scaling indicator.

       For details see the groff info file.

CONDITIONS    [Toc]    [Back]

       Conditions  occur in tests raised by the .if, .ie, and the
       .while requests.  The following  table  characterizes  the
       different types of conditions.

          N          A numerical expression N yields true if
                     its value is >0.
          !N         True if the value of N is <=0.
          's1's2'    True if string s1 is identical to
                     string s2.
          !'s1's2'   True if string s1 is not identical to
                     string s2.
          cch        True if there is a character ch
                     available.
          dname      True if there is a string, macro,
                     diversion, or request called name.
          e          Current page number is even.
          o          Current page number is odd.
          n          Formatter is nroff.
          rreg       True if there is a register named reg.
          t          Formatter is troff.

REQUESTS    [Toc]    [Back]

       This section provides a short reference for the predefined
       requests.   In groff, request and macro names can be arbitrarily
 long.  No bracketing or marking of long  names  is
       needed.

       Most  requests  take one or more arguments.  The arguments
       are separated by space characters (no tabs!); there is  no
       inherent  limit  for  their length or number.  An argument
       can be enclosed by a pair of double quotes: This  is  very
       handy  if  an  argument  contains  space characters, e.g.,
       "arg with space" denotes a single argument.

       Some requests have optional arguments with a different behaviour.
  Not all of these details are outlined here.  Refer
 to the groff info file for all details.

       In the following  request  specifications,  most  argument
       names  were  chosen to be descriptive.  Only the following
       denotations need clarification.

          c          denotes a single character.
          font       a font either specified as a font name
                     or a font number.
          anything   all characters up to the end of the line
                     or within \{ and \}.
          n          is a numerical expression that evaluates
                     to an integer value.
          N          is an arbitrary numerical expression,
                     signed or unsigned.
          +-N        has three meanings depending on its
                     sign, described below.

       If an expression defined as +-N starts with a `+' sign the
       resulting value of the expression will be added to an  already
 existing value inherent to the related request, e.g.
       adding to a number register.   If  the  expression  starts
       with  a `-' the value of the expression will be subtracted
       from the request value.

       Without a sign, N replaces the  existing  value  directly.
       To  assign  a  negative number either prepend 0 or enclose
       the negative number in parentheses.

   REQUEST SHORT REFERENCE    [Toc]    [Back]
       .         Empty line,  ignored.   Useful  for  structuring
                 documents.
       .\" anything
                 Complete line is a comment.
       .ab string
                 Print string on standard error, exit program.
       .ad       Begin  line  adjustment for output lines in current
 adjust mode.
       .ad c     Start line adjustment in mode c (c=l,r,b,n).
       .af register c
                 Assign format c to register (c=l,i,I,a,A).
       .aln alias register
                 Create alias name for register.
       .als alias object
                 Create alias name for request, string, macro, or
                 diversion object.
       .am macro Append to macro until .. is called.
       .am macro end
                 Append to macro until .end is called.
       .as stringvar anything
                 Append anything to stringvar.
       .asciify diversion
                 Unformat special ASCII characters in diversion.
       .backtrace
                 Print a backtrace of the input on stderr.
       .bd font N
                 Embolden font by N-1 units.
       .bd S font N
                 Embolden  Special  Font  S  when current font is
                 font.
       .bp       Eject current page and begin new page.
       .bp +-N   Eject current page; next page number +-N.
       .blm macro
                 Set the blank line macro to macro.
       .br       Line break.
       .break    Break out of a while loop.
       .c2       Reset no-break control character to "'".
       .c2 c     Set no-break control character to c.
       .cc       Reset control character to `.'.
       .cc c     Set control character to c.
       .ce       Center the next input line.
       .ce N     Center following N input lines.
       .cf filename
                 Copy contents of file  filename  unprocessed  to
                 stdout or to the diversion.
       .cflags mode c1 c2 ...
                 Treat  characters  c1, c2, ... according to mode
                 number.
       .ch trap N
                 Change trap location to N.
       .char c anything
                 Define character c to string anything.
       .chop object
                 Chop the last character off  macro,  string,  or
                 diversion object.
       .close stream
                 Close the stream.
       .continue
                 Finish the current iteration of a while loop.
       .cp       Enable compatibility mode.
       .cp N     If  N is zero disable compatibility mode, otherwise
 enable it.
       .cs font N M
                 Set constant character width mode  for  font  to
                 N/36 ems with em M.
       .cu N     Continuous  underline  in  nroff,  like  .ul  in
                 troff.
       .da macro Divert and append to macro.
       .de macro Define or redefine macro until .. is called.
       .de macro end
                 Define or redefine macro until .end is called.
       .di       End current diversion.
       .di macro Divert to macro.
       .do name  Interpret .name with compatibility mode enabled.
       .ds stringvar anything
                 Set stringvar to anything.
       .dt N trap
                 Set  diversion trap to position N (default scale
                 indicator v).
       .ec       Reset escape character to `\'.
       .ec c     Set escape character to c.
       .el anything
                 Else part for if-else (.ie) request.
       .em macro The macro will be run after the end of input.
       .eo       Turn off escape character mechanism.
       .ev       Switch to previous environment.
       .ev env   Push down environment number  or  name  env  and
                 switch to it.
       .evc env  Copy the contents of environment env to the current
 environment.  No pushing or popping.
       .ex       Exit from roff processing.
       .fam name Set the current font family to name.
       .fc       Disable field mechanism.
       .fc a     Set field delimiter to a and  pad  character  to
                 space.
       .fc a b   Set field delimiter to a and pad character to b.
       .fi       Fill output lines.
       .fl       Flush output buffer.
       .fp n font
                 Mount font on position n.
       .fp n internal external
                 Mount font with long external name to short  in-
                 ternal name on position n.
       .fspecial font s1 s2...
                 When  the  current  font is font, then the fonts
                 s1, s2, ... will be special.
       .ft       Return to previous font.  Same as \fP.
       .ft font  Change to font name  or  number  font;  same  as
                 \f[font] escape sequence.
       .ftr font1 font2
                 Translate font1 to font2.
       .hc       Remove  additional hyphenation indicator character.

       .hc c     Set up additional hyphenation indicator  character
 c.
       .hcode c1 code1 c2 code2 ...
                 Set  the  hyphenation  code  of  character c1 to
                 code1, that of c2 to code2, etc.
       .hla lang Set the current hyphenation language to lang.
       .hlm n    Set the maximum number of consecutive hyphenated
                 lines to n.
       .hpf file Read hyphenation patterns from file.
       .hw words List of words with exceptional hyphenation.
       .hy N     Switch to hyphenation mode N.
       .hym n    Set  the  hyphenation margin to n (default scale
                 indicator m).
       .hys n    Set the hyphenation space to n.
       .ie cond anything
                 If cond then anything else goto .el.
       .if cond anything
                 If cond then anything; otherwise do nothing.
       .ig       Ignore text until .. is called.
       .ig end   Ignore text until .end.
       .in       Change to previous indent value.
       .in +-N   Change indent according to  +-N  (default  scale
                 indicator m).
       .it N trap
                 Set an input-line count trap at position N.
       .kern     Enable pairwise kerning.
       .kern n   If  n  is zero, disable pairwise kerning, otherwise
 enable it.
       .lc       Remove leader repetition character.
       .lc c     Set leader repetition character to c.
       .length register anything
                 Write the length of the string anything in  reg-
                 ister.
       .lf N file
                 Set input line number to N and filename to file.
       .lg N     Ligature mode on if N>0.
       .ll       Change to previous line length.
       .ll +-N   Set line length according to +-N  (default  size
                 6.5i, default scale indicator m).
       .ls       Change  to  the previous value of additional intra-line
 skip.
       .ls N     Set additional intra-line skip value to N, i.e.,
                 N-1  blank  lines  are  inserted after each text
                 output line.
       .lt +-N   Length of title (default scale indicator m).
       .mc       Margin character off.
       .mc c     Print character c after each text line at actual
                 distance from right margin.
       .mc c N   Set margin character to c and distance to N from
                 right margin (default scale indicator m).
       .mk register
                 Mark current vertical position in register.
       .mso file The same as the .so request except that file  is
                 also searched in the tmac directories.
       .na       No output-line adjusting.
       .ne       Need a one-line vertical space.
       .ne N     Need  N  vertical  space  (default scale indicator
 v).
       .nf       No filling or adjusting of output-lines.
       .nh       No hyphenation.
       .nm       Number mode off.
       .nm +-N M S I
                 In line number mode, set number, multiple, spacing,
 and indent.
       .nn       Do not number next line.
       .nn N     Do not number next N lines.
       .nr register +-N M
                 Define  or  modify register using +-N with autoincrement
 M.
       .nroff    Make the built-in condition n true and t  false.
       .ns       Turn no-space mode on.
       .nx filename
                 Next file.
       .open stream filename
                 Open  filename  for  writing  and  associate the
                 stream named stream with it.
       .opena stream filename
                 Like .open but append to it.
       .os       Output vertical distance that was saved  by  the
                 .sv request.
       .pc       Reset page number character to `%'.
       .pc c     Page number character.
       .pi program
                 Pipe output to program (nroff only).
       .pl       Set page length to default 11i. The current page
                 length is stored in .p.
       .pl +-N   Change page length to +-N (default scale indicator
 v).
       .pm       Print macro names and sizes (number of blocks of
                 128 bytes).
       .pm t     Print only total of sizes of macros  (number  of
                 128 bytes blocks).
       .pn +-N   Next page number N.
       .pnr      Print  the  names  and contents of all currently
                 defined number registers on stderr.
       .po       Change to previous  page  offset.   The  current
                 page offset is available in .o.
       .po +-N   Page offset N.
       .ps       Return to previous point-size.
       .ps +-N   Point size; same as \s[+-N].
       .psbb filename
                 Get the bounding box of a PostScript image file-
                 name.
       .pso command
                 This behaves like the .so  request  except  that
                 input comes from the standard output of command.
       .ptr      Print the names and positions of all traps  (not
                 including  input line traps and diversion traps)
                 on stderr.
       .rchar c1 c2...
                 Remove the definitions of characters c1, c2, ...
       .rd prompt
                 Read insertion.
       .rj n     Right justify the next n input lines.
       .rm name  Remove request, macro, or string name.
       .rn old new
                 Rename request, macro, or string old to new.
       .rnn reg1 reg2
                 Rename register reg1 to reg2.
       .rr register
                 Remove register.
       .rs       Restore spacing; turn no-space mode off.
       .rt +-N   Return  (upward  only)  to marked vertical place
                 (default scale indicator v).
       .shc      Reset soft hyphen character to \(hy.
       .shc c    Set the soft hyphen character to c.
       .shift n  In a macro, shift the arguments by  n positions.
       .so filename
                 Include source file.
       .sp       Skip one line vertically.
       .sp N     Space  vertical  distance N up or down according
                 to sign of N (default scaling indicator v).
       .special s1 s2 ...
                 Fonts s1, s2,  etc.  are  special  and  will  be
                 searched for characters not in the current font.
       .ss N     Space-character  size  set  to   N/12   of   the
                 spacewidth in the current font.
       .ss N M   Space-character  size  set  to N/12 and sentence
                 space size set to M/12 of the spacewidth in  the
                 current font (=1/3 em).
       .sty n style
                 Associate style with font position n.
       .substring register n1 n2
                 Replace  the  string  in  register with the substring
 defined by the indices n1 and n2.
       .sv       Save 1v of vertical space.
       .sv N     Save the vertical distance N  for  later  output
                 with .os request.
       .sy command-line
                 Execute program command-line.
       .ta T N   Set tabs after every position that is a multiple
                 of N (default scaling indicator m).
       .ta n1 n2 ... nn T r1 r2 ... rn
                 Set tabs at positions n1, n2, ..., nn, then  set
                 tabs  at  nn+r1,  nn+r2,  ...,  nn+rn,  then  at
                 nn+rn+r1, nn+rn+r2, ..., nn+rn+rn, and so on.
       .tc       Remove tab repition character.
       .tc c     Set tab repetition character to c.
       .ti +-N   Temporary indent next line (default scaling  indicator
 m).
       .tkf font s1 n1 s2 n2
                 Enable track kerning for font.
       .tl 'left'center'right'
                 Three-part title.
       .trf filename
                 Transparently  output the contents of file file-
                 name.
       .tm anything
                 Print anything on terminal (UNIX  standard  message
 output).
       .tr abcd....
                 Translate a to b, c to d, etc. on output.
       .trnt abcd....
                 This  is the same as the .tr request except that
                 the translations do not apply to  text  that  is
                 transparently  throughput  into a diversion with
                 \!.
       .troff    Make the built-in condition t true and n  false.
       .uf font  Underline font set to font (to be switched to by
                 .ul).
       .ul N     Underline (italicize in troff) N input lines.
       .vpt n    Enable vertical position traps if n is non-zero,
                 disable them otherwise.
       .vs       Change to previous vertical base line spacing.
       .vs N     Set  vertical  base  line  spacing to N. Default
                 value is 12p.
       .warn n   Set warnings code to n.
       .wh N trap
                 Set location trap; negative means from page bottom.

       .while cond anything
                 While condition cond is true, accept anything as
                 input.
       .write stream anything
                 Write anything to the stream named stream.

       Besides these standard groff requests, there might be further
 macro calls.  They can originate from a macro package
       (see roff(7) for an overview) or from a preprocessor.

       Preprocessor macros are easy to be recognized.   They  enclose
 their code into a pair of characteristic macros.

               +-------------+-------------+------------+
               |preprocessor | start macro |  end macro |
               +-------------+-------------+------------+
               |    eqn      |     .PS     |    .PE     |
               |    grap     |     .G1     |    .G2     |
               |    grn      |     .GS     |    .GE     |
               |    pic      |     .PS     |    .PE     |
               |   refer     |     .R1     |    .R2     |
               |   soelim    |    none     |    none    |
               |    tbl      |     .TS     |    .TE     |
               +-------------+-------------+------------+

ESCAPE SEQUENCES    [Toc]    [Back]

       Escape sequences are in-line language elements usually introduced
 by a backslash `\' and followed by an escape name
       and sometimes by a required argument.  Input processing is
       continued directly after the escaped character or the  argument
  resp. without an intervening separation character.
       So there must be a way to determine the end of the  escape
       name and the end of the argument.

       This is done by enclosing names (escape name and arguments
       consisting of a variable  name)  by  a  pair  of  brackets
       \[name]  and  constant  arguments  (number expressions and
       characters) by apostrophes (ASCII 0x27) like 'constant'.

       There are abbreviations for short  names.   Two  character
       escape  names  can  be specified by an opening parenthesis
       like \(xy without a closing  counterpart.   And  all  onecharacter
  names different from the special characters `['
       and `(' can even be specified without a marker in the form
       \c.

       Constant  arguments  of length 1 can omit the marker apostrophes,
 too, but there is no two-character analogue.

       While 1-character escape sequences are mainly used for inline
  functions  and  system  related  tasks, the 2-letter
       names following the \(  construct  are  used  for  special
       characters predefined by the roff system.  Names with more
       than two characters \[name]  mostly  denote  user  defined
       named characters (see the .char request).

   SINGLE CHARACTER ESCAPES    [Toc]    [Back]
       \"     Beginning  of  a comment.  Everything up to the end
              of the line is ignored.
       \#     Everything up to and including the next newline  is
              ignored.   This  is interpreted in copy mode.  This
              is like \" except the ignoring of  the  terminating
              newline.
       \*s    The  string  stored  in  the  string  variable with
              1-character name s.
       \*(st  The string  stored  in  the  string  variable  with
              2-character name st.
       \*[stringvar]
              The string stored in the string variable with arbitrary
 length name stringvar.
       \$0    The name by which the current  macro  was  invoked.
              The  .als  request  can make a macro have more than
              one name.
       \$x    Macro argument with 1-place number x, where x is  a
              digit between 1 and 9.
       \$(xy  Macro argument with 2-digit number xy.
       \$[nexp]
              Macro  argument  with  number nexp, where nexp is a
              numerical expression evaluating to an integer  >=1.
       \$*    In  a macro, the concatenation of all the arguments
              separated by spaces.
       \$@    In a macro, the concatenation of all the  arguments
              with each surrounded by double quotes, and separated
 by spaces.
       \\     reduces to a single backslash; useful to delay  its
              interpretation  as  escape  character in copy mode.
              For a printable backslash, use \e.
       \'     The acute accent '; same as \(aa. Unescaped:  apostrophe,
  right  quotation mark, single quote (ASCII
              0x27).
       \`     The grave accent `; same as \(ga.  Unescaped:  left
              quote, backquote (ASCII 0x60).
       \-     The - sign in the current font.
       \.     An  uninterpreted  dot  (period),  even at start of
              line.
       \%     Default optional hyphenation character.
       \!     Transparent line indicator.
       \?anything?
              In a diversion, this will transparently embed  any-
              thing  in  the diversion.  anything is read in copy
              mode.  See also the escape sequences \! and \?.
       \space Unpaddable  space-size  space  character  (no  line
              break).
       \0     Digit width.
       \|     1/6 em narrow space character; zero width in nroff.
       \^     1/12 em half-narrow space character; zero width  in
              nroff.
       \&     Non-printable, zero width character.
       \)     Like \& except that it behaves like a character declared
 with the cflags request  to  be  transparent
              for the purposes of end of sentence recognition.
       \/     Increases  the  width of the preceding character so
              that the spacing between  that  character  and  the
              following  character will be correct if the following
 character is a roman character.
       \,     Modifies the spacing of the following character  so
              that  the  spacing  between  that character and the
              preceding character will correct if  the  preceding
              character is a roman character.
       \~     Unbreakable  space that stretches like a normal inter-word
 space when a line is adjusted.
       \newline
              Ignored newline, for continuation lines.
       \{     Begin conditional input.
       \}     End conditional input.
       \(st   The special character with 2-character name st, see
              section SPECIAL CHARACTERS.
       \[name]
              The  named  character  with  arbitrary  length name
              name.
       \a     Non-interpreted leader character.
       \A'anything'
              If anything acceptable as name of a string,  macro,
              diversion,  register,  environment  or font it is 1
              otherwise 0.
       \b'abc...'
              Bracket building function.
       \c     Interrupt text processing.
       \C'char'
              The character called char;  same  as  \[char],  but
              compatible to other roff versions.
       \d     Forward  (down)  1/2  em vertical unit (1/2 line in
              nroff).
       \D'charseq'
              Draw a graphical element defined by the  characters
              in charseq; see groff info file for details.
       \e     Printable  version of the current escape character.
       \E     Equivalent to an escape character, but is  not  interpreted
 in copy-mode.
       \fF    Change  to  font  with  1-character name or 1-digit
              number F.
       \f(fo  Change to font with 2-characer name or 2-digit number
 fo.
       \f[font]
              Change to font with arbitrary length name or number
              expression font.
       \g[reg]
              Return format of register with  name  reg  suitable
              for .af. Alternative forms \g(xy and \gx.
       \h'N'  Local horizontal motion; move right N (left if negative).

       \H'N'  Set height of current font to N.
       \k[reg]
              Mark horizontal input place in register with  arbitrary
  length name reg. Alternative forms \k(xy and
              \kx.
       \l'Nc' Horizontal line drawing function (optionally  using
              character c).
       \L'Nc' Vertical  line  drawing  function (optionally using
              character c).
       \nr    The numerical value stored in the register variable
              with the 1-character name r.
       \n(re  The numerical value stored in the register variable
              with the 2-character name re.
       \n[reg]
              The numerical value stored in the register variable
              with arbitrary lenght name reg.
       \N'n'  Typeset  the  character  with code n in the current
              font, no special fonts are  searched.   Useful  for
              adding  characters  to  a  font using the .char request.

       \o'abc...'
              Overstrike characters a, b, c, etc.
       \p     Break and spread output line.
       \r     Reverse  1 em  vertical  motion  (reverse  line  in
              nroff).
       \R'name +-n'
              The same as .nr name +-n.
       \s[+-N]
              Set  the  point  size to N scaled points.  Note the
              alternative  forms   \s+-[N],   \s'+-N',   \s+-'N',
              \s(+-xy, \s+-(xy, \s+-x. Same as .ps request.
       \S'N'  Slant output N degrees.
       \t     Non-interpreted horizontal tab.
       \u     Reverse  (up)  1/2  em vertical motion (1/2 line in
              nroff).
       \v'N'  Local vertical motion; move down  N  (up  if  negative).

       \V[env]
              The  contents  of the environment variable env. Alternative
 forms \V(xy and \Vx.
       \w'string'
              The width of the character sequence string.
       \x'N'  Extra line-space function (negative  before,  positive
 after).
       \X'string'
              Output string as device control function.
       \Y[name]
              Output  string variable or macro name uninterpreted
              as  device  control  function.   Alternative  forms
              \Y(xy and \Yx.
       \zc    Print c with zero width (without spacing).
       \Z'anything'
              Print  anything and then restore the horizontal and
              vertical position; anything may not contain tabs or
              leaders.

       The  escape  sequences \e, \., \", \$, \*, \a, \n, \t, \g,
       and \newline are interpreted in copy mode.

       Escape sequences starting with \( or \[ do  not  represent
       single  character  escape  sequences, but introduce escape
       names with two or more characters.

       If a backslash is followed by a character  that  does  not
       constitute  a  defined  escape  sequence  the backslash is
       silently ignored and the character maps to itself.

   SPECIAL CHARACTERS    [Toc]    [Back]
       Common special characters are  predefined  by  escape  sequences
  of the form \(xy with characters x and y. Some of
       these exist in the usual font while most of them are  only
       available in the special font.  Below you'll find a selection
 of the most important glyphs; a complete list can  be
       found in groff_char(7).

              \(bu   o      Bullet sign.
              \(co   (C)    Copyright.
              \(ct   c      Cent.
              \(dd   =      Double dagger.
              \(de   o      Degree.
              \(dg   -      Dagger.
              \(em   --     Em-dash.
              \(hy   -      Hyphen.
              \(rg   (R)    Registered sign.
              \(sc   S      Section sign.
              \(ul   _      Underline character.
              \(==   ==     Identical.
              \(>=   >=     Larger or equal.
              \(<=   <=     Less or equal.
              \(!=   !=     Not equal.
              \(->   ->     Right arrow.
              \(<-   <-     Left arrow.
              \(+-   +-     Plus-minus sign.

REGISTERS    [Toc]    [Back]

       Registers  are  variables  that  store a value.  In groff,
       most registers store numerical values (see section NUMERI-
       CAL  EXPRESSIONS  above),  but some can also hold a string
       value.

       Each register is given a name.  Arbitrary registers can be
       defined and set with the request .nr register.

       The value stored in a register can be retrieved by the escape
 sequences introduced by \n.

       Most useful are predefined registers.   In  the  following
       the  notation  name  is used to refer to a register called
       name to make clear that we speak about registers.   Please
       keep  in mind that the \en[] decoration is not part of the
       register name.

   READ-ONLY REGISTERS    [Toc]    [Back]
       The following registers have predefined values that should
       not  be  modified by the user (usually, registers starting
       with a dot a read-only).  Mostly, they provide information
       on  the  current  settings  or  store results from request
       calls.

       \n[.$]    Number of arguments in the current macro.
       \n[.A]    Set to 1 in troff if option -A is used; always 1
                 in nroff.
       \n[.H]    Available  horizontal resolution in basic units.
       \n[.T]    Set to 1 if option -T is used.
       \n[.V]    Available vertical resolution in basic units.
       \n[.a]    Post-line extra line-space  most  recently  utilized
 using \x'N'.
       \n[.C]    1  if  compatibility mode is in effect, 0 otherwise.

       \n[.c]    Current input line number.
       \n[.cdp]  The depth of the last  character  added  to  the
                 current  environment.   It  is  positive  if the
                 character extends below the baseline.
       \n[.ce]   The number of lines remaining to be centered, as
                 set by the .ce request.
       \n[.cht]  The  height  of  the last character added to the
                 current environment.   It  is  positive  if  the
                 character extends above the baseline.
       \n[.csk]  The skew of the last character added to the current
 environment.  The skew of  a  character  is
                 how  far to the right of the center of a character
 the center of an accent over that  character
                 should be placed.
       \n[.d]    Current  vertical  place  in  current diversion;
                 equal to register nl.
       \n[.ev]   The name or number of  the  current  environment
                 (string-valued).
       \n[.f]    Current font number.
       \n[.fam]  The current font family (string-valued).
       \n[.fp]   The number of the next free font position.
       \n[.g]    Always  1 in GNU troff.  Macros should use it to
                 test if running under groff.
       \n[.h]    Text base-line high-water mark on  current  page
                 or diversion.
       \n[.hla]  The  current  hyphenation language as set by the
                 .hla request.
       \n[.hlc]  The number of immediately preceding  consecutive
                 hyphenated lines.
       \n[.hlm]  The  maximum  allowed  number of consecutive hyphenated
 lines, as set by the .hlm request.
       \n[.hy]   The current hyphenation flags (as set by the .hy
                 request).
       \n[.hym]  The  current  hyphenation  margin (as set by the
                 .hym request).
       \n[.hys]  The current hyphenation space  (as  set  by  the
                 .hys request).
       \n[.i]    Current ident.
       \n[.in]   The  indent  that  applies to the current output
                 line.
       \n[.kern] 1 if pairwise kerning is enabled, 0 otherwise.
       \n[.l]    Current line length.
       \n[.lg]   The current ligature mode (as set by the .lg request).

       \n[.ll]   The line length that applies to the current output
 line.
       \n[.lt]   The title length (as set by the .lt request).
       \n[.n]    Length of text portion on previous output  line.
       \n[.ne]   The  amount of space that was needed in the last
                 .ne request that caused a  trap  to  be  sprung.
                 Useful in conjunction with .trunc.
       \n[.o]    Current page offset.
       \n[.p]    Current page length.
       \n[.pn]   The  number  of  the next page: either the value
                 set by a .pn request, or the number of the  current
 page plus 1.
       \n[.ps]   The current pointsize in scaled points.
       \n[.psr]  The last-requested pointsize in scaled points.
       \n[.rj]   The number of lines to be right-justified as set
                 by the rj request.
       \n[.s]    Current point size as a decimal fraction.
       \n[.sr]   The last requested pointsize in points as a decimal
 fraction (string-valued).
       \n[.t]    Distance to the next trap.
       \n[.tabs] A  string representation of the current tab settings
 suitable for use as an argument to the .ta
                 request.
       \n[.trunc]
                 The  amount  of  vertical space truncated by the
                 most recently sprung vertical position trap, or,
                 if  the  trap was sprung by a .ne request, minus
                 the amount of vertical motion produced  by  .ne.
                 request.  In other words, at the point a trap is
                 sprung, it represents the difference of what the
                 vertical  position  would  have been but for the
                 trap, and what the  vertical  position  actually
                 is.   Useful  in conjunction with the .ne register.

       \n[.ss]   The value of the parameters set by the first argument
 of the .ss request.
       \n[.sss]  The  value  of  the parameters set by the second
                 argument of the .ss request.
       \n[.u]    Equal to 1 bin fill mode and 0 in nofill mode.
       \n[.v]    Current vertical line spacing.
       \n[.vpt]  1 if vertical position traps are enabled, 0 otherwise.

       \n[.w]    Width of previous character.
       \n[.warn] The sum of the number codes of the currently enabled
 warnings.
       \n[.x]    The major version number.
       \n[.y]    The minor version number.
       \n[.Y]    The revision number of groff.
       \n[.z]    Name of current diversion.
       \n[llx]   Lower left x-coordinate (in PostScript units) of
                 a given PostScript image (set by .psbb).
       \n[lly]   Lower left y-coordinate (in PostScript units) of
                 a given PostScript image (set by .psbb).
       \n[rsb]   Like sb, but takes account of  the  heights  and
                 depths of characters.
       \n[rst]   Like  st,  but  takes account of the heights and
                 depths of characters.
       \n[sb]    Depth of string below base  line  (generated  by
                 width function \w).
       \n[skw]   Right  skip  width  from  the center of the last
                 character in the \w argument.
       \n[ssc]   The amount of horizontal space  (possibly  negative)
 that should be added to the last character
                 before a subscript (generated by width  function
                 \w).
       \n[st]    Height  of  string above base line (generated by
                 width function \w).
       \n[urx]   Upper right x-coordinate (in  PostScript  units)
                 of a given PostScript image (set by .psbb).
       \n[ury]   Upper  right  y-coordinate (in PostScript units)
                 of a given PostScript image (set by .psbb).

   WRITABLE REGISTERS    [Toc]    [Back]
       The following registers can be read and written by the user.
  They have predefined default values, but these can be
       modified for customizing a document.

       \n[%]     Current page number.
       \n[c.]    Current input line number.
       \n[ct]    Character type (set by width function \w).
       \n[dl]    Maximal width of last completed diversion.
       \n[dw]    Current day of week (1-7).
       \n[dy]    Current day of month (1-31).
       \n[hp]    Current horizontal position at input line.
       \n[ln]    Output line number.
       \n[mo]    Current month (1-12).
       \n[nl]    Vertical position of  last  printed  text  baseline.

       \n[slimit]
                 If greater than 0, the maximum number of objects
                 on the input stack.  If <=0 there is  no  limit,
                 i.e., recursion can continue until virtual memory
 is exhausted.
       \n[systat]
                 The return value of the system()  function  executed
 by the last .sy request.
       \n[year]  The current year (year 2000 compliant).
       \n[yr]    Current year minus 1900.  For Y2K compliance use
                 register year instead.

WARNINGS    [Toc]    [Back]

       Each warning generated by groff is identified  by  a  name
       and  a  code  number.   The codes are powers of 2 to allow
       bit-encoding with a single integer.  There are also  names
       that can be used to refer to groups of warnings.

       The  name  associated with a warning is used by the -w and
       -W options; the number code is used by the  .warn  request
       and by the \n[warn] register.

       all         group
                   All  warnings except di, mac and reg. Intended
                   to cover all warnings with  traditional  macro
                   packages.
       break       4
                   In  fill mode, lines which could not be broken
                   so that their length was less  than  the  line
                   length.  This is enabled by default.
       char        1
                   Non-existent  characters.   This is enabled by
                   default.
       delim       8
                   Missing or mismatched closing delimiters.
       di          256
                   Use of .di or .da  without  an  argument  when
                   there is no current diversion.
       el          16
                   Use  of  the  .el request with no matching .ie
                   request.
       escape      32768
                   Unrecognized escape sequence.  Then the escape
                   character is ignored.
       font        131072
                   Non-existent  fonts.   This  is enabled by default.

       ig          262144
                   Illegal escapes in text ignored with  the  .ig
                   request.  These are conditions that are errors
                   when they occur outside of ignored text.
       mac         512
                   Use of undefined strings, macros,  and  diversions.
   Automatically handled as empty.  Usually,
 only one warning per name.
       missing     8192
                   Request that  is  missing  non-optional  arguments.

       input       16384
                   Illegal input character.
       number      2
                   Invalid  numeric expressions.  This is enabled
                   by default.
       range       64
                   Out of range arguments.
       reg         1024
                   Use of undefined number  register.   Automatically
 defined as having value 0.  Usually, on
                   ly one warning per name.
       right-brace 4096
                   Use of \} where a number was expected.
       scale       32
                   Meaningless scaling indicators.
       space       65536
                   Missing space between a request or  macro  and
                   its  argument.  Then no macro is automatically
                   defined.  This is enabled  by  default.   This
                   warning  will  never  occur  in  compatibility
                   mode.
       syntax      128
                   Dubious syntax in numeric expressions.
       tab         2048
                   Inappropriate use of a tab  character  (either
                   in  an unquoted macro argument or where a number
 was expected).
       w           group
                   All warnings.

       +----------------+---------------------+------------------+
       Bit Code Warning Bit Code    Warning   Bit  Code  Warning |
       +----------------+---------------------+------------------+
       | 0    1  char   | 8   256     di      |16  65536  space  |
       | 1    2 number  | 9   512     mac     |17 131072  font   |
       | 2    4  break  |10  1024     reg     |18 262144   ig    |
       | 3    8  delim  |11  2048     tab     |                  |
       | 4   16   el    |12  4096 right-brace |                  |
       | 5   32  scale  |13  8192   missing   |                  |
       | 6   64  range  |14 16384    input    |                  |
       | 7  128 syntax  |15 32768   escape    |                  |
       +----------------+---------------------+------------------+

COMPATIBILITY    [

 Similar pages
Name OS Title
perlxs IRIX XS language reference manual
perlxs OpenBSD XS language reference manual
ditroff FreeBSD classical device independent roff
DtMmdbSectionGetShortTitle HP-UX obtains the short title for a section
roff NetBSD a survey of the roff typesetting system
zsoelim Linux satisfy .so requests in roff input
roff FreeBSD concepts and history of roff typesetting
perlreftut OpenBSD Mark's very short tutorial about references
DtMmdbBookGetShortTitle HP-UX obtains the short title of a book
ntohs Tru64 Convert an unsigned short (16-bit) integer from
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service