groff - a short reference for the GNU roff language


DESCRIPTION

       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 prede­
       fined 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 documen­
       tation that is found in the groff info(1) file, which con­
       tains more detailed, actual, and concise information.

       The general syntax for writing groff  documents  is  rela­
       tively  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  argu­
       ments.   They have the following syntax.  The leading con­
       trol character can be followed by a  command  name;  argu­
       ments,  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 in-
       word formatting elements or functions.  Some of these take
       arguments separated by single quotes "'", others are regu­
       lated by a length encoding introduced by an open parenthe­
       sis `( or enclosed in brackets `[ and `].

       ing language extension, such as macros.  When interpreting
       macro  definitions, the roff system enters a special oper­
       ating 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  dou­
       ble  backslashes to a single one in all macro definitions.


GROFF ELEMENTS

       The roff language elements add formatting information to a
       text  file.   The fundamental elements are predefined com­
       mands and variables that make roff a  full-blown  program­
       ming language.

       There  are two kinds of roff commands, possibly with argu­
       ments.  Requests are written on a line of their own start­
       ing  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 pre-
       defined 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 vari­
       ables, 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


       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

       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 charac­
              ter.   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.

              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 charac­
              ter.  Groff  provides  a  printable  representation
              with the \(cq escape sequence.

              The  double  quote  is used to enclose arguments in
              requests and macros.  In the .ds and .as  requests,
              a  leading  double  quote  in  the argument will be
              stripped off, making everything else afterwards the
              string to be defined (enabling leading whitespace).
              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 argu­
              ment consisting  of  exactly  two  characters.   In
              groff, this behavior can be replaced by the [] con­
              struct.

       [      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-spe­
              cial.

       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 speci­
              fied 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

              pre-defined tab position.  There is a sophisticated
              interface for handling tab positions.


NUMERICAL EXPRESSIONS

       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 sig­
       nifies 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 numeri­
       cal 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

       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.

                     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

       This section provides a short reference for the predefined
       requests.   In groff, request and macro names can be arbi­
       trarily 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 be­
       haviour.  Not all of these details are outlined here.  Re­
       fer 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  al­
       ready 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.

       To  assign  a  negative number either prepend 0 or enclose
       the negative number in parentheses.

   REQUEST SHORT REFERENCE
       .         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 cur­
                 rent 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.
       .am1 macro
                 Same as .am but with compatibility mode switched
                 off during macro expansion.
       .am1 macro end
                 Same as .am but with compatibility mode switched
                 off during macro expansion.
       .as stringvar anything
                 Append anything to stringvar.
       .asciify diversion
                 Unformat  ASCII characters, spaces, and some es­
                 cape sequences 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.
       .blm      Unset the blank line macro.
       .blm macro
                 Set the blank line macro to macro.
       .box      End current diversion.
       .box macro
                 Divert  to  macro,  omitting  a partially filled
                 line.
       .boxa     End current diversion.
       .boxa macro
                 Divert and append to macro, omitting a partially
                 filled line.
       .bp       Eject current page and begin new page.

       .br       Line break.
       .brp      Break and spread output line.  Same as \p.
       .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,  other­
                 wise 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       End current diversion.
       .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.
       .de1 macro
                 Same as .de but with compatibility mode switched
                 off during macro expansion.
       .de1 macro end
                 Same as .de but with compatibility mode switched
                 off during macro expansion.
       .dei macro
                 Define  or  redefine  a macro whose name is con­
                 tained in the string register macro until ..  is
                 called.
       .dei macro end
                 Define  or  redefine  a macro indirectly.  macro
                 and end are string registers whose contents  are
                 interpolated  for  the  macro  name  and the end

       .di       End current diversion.
       .di macro Divert to macro.
       .do name  Interpret .name  with  compatibility  mode  dis­
                 abled.
       .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.
       .ecr      Restore escape character saved with .ecs.
       .ecs      Save current escape character.
       .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 cur­
                 rent environment.  No pushing or popping.
       .ex       Exit from roff processing.
       .fam      Return to previous font family.
       .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 charac­
                 ter.
       .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

       .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, other­
                 wise 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.
       .linetabs
                 Enable line-tabs mode (i.e., calculate tab posi­
                 tions relative to output line).
       .linetabs n
                 If n is zero, disable line-tabs mode,  otherwise
                 enable it.
       .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 in­
                 tra-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
                 searched in the tmac directories.
       .na       No output-line adjusting.

       .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, spac­
                 ing, and indent.
       .nn       Do not number next line.
       .nn N     Do not number next N lines.
       .nop anything
                 Always execute anything.
       .nr register ±N M
                 Define or modify register using ±N with auto-in­
                 crement 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

                 on stderr.
       .rchar c1 c2...
                 Remove the definitions of characters c1, c2, ...
       .rd prompt
                 Read insertion.
       .return   Return from a macro.
       .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 sub­
                 string 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).

                 Enable track kerning for font.
       .tl leftcenterright
                 Three-part title.
       .tm anything
                 Print  anything  on terminal (UNIX standard mes­
                 sage output).
       .tm1 anything
                 Print anything on terminal (UNIX  standard  mes­
                 sage  output),  allowing  leading  whitespace if
                 anything starts with  (which  will  be  stripped
                 off).
       .tmc anything
                 Similar  to  .tm1  without emitting a final new­
                 line.
       .tr abcd....
                 Translate a to b, c to d, etc. on output.
       .trf filename
                 Transparently output the contents of file  file­
                 name.
       .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.
       .unformat diversion
                 Unformat space characters and  tabs,  preserving
                 font information in diversion.
       .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 bot­
                 tom.
       .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 fur­
       ther 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 en­
       close 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

       Escape sequences are in-line language elements usually in­
       troduced  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 ar­
       gument 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 one-
       character 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  apos­
       trophes, too, but there is no two-character analogue.

       While 1-character escape sequences are mainly used for in-
       line 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
       \      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.

              The string stored in the string variable with arbi­
              trary 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 separat­
              ed 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: apos­
              trophe, 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 de­
              clared  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  follow­
              ing 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  in­
              ter-word space when a line is adjusted.

              without a soft hyphen character).
       \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.
       \Aanything
              If anything is acceptable as a name  of  a  string,
              macro,  diversion, register, environment or font it
              expands to 1, and 0 otherwise.
       \babc...
              Bracket building function.
       \Banything
              If anything is acceptable as a  valid  numeric  ex­
              pression it expands to 1, and 0 otherwise.
       \c     Interrupt text processing.
       \Cchar 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).
       \Dcharseq
              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 in­
              terpreted 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 num­
              ber 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.
       \hN    Local horizontal motion; move right N (left if neg­
              ative).
       \HN    Set height of current font to N.
       \k[reg]
              Mark  horizontal input place in register with arbi­
              trary length name reg. Alternative forms \k(xy  and
              \kx.
       \lNc   Horizontal  line drawing function (optionally using
              character c).
       \LNc   Vertical line drawing  function  (optionally  using
              character c).
       \nr    The numerical value stored in the register variable

       \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.
       \Nn    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  re­
              quest.
       \oabc...
              Overstrike characters a, b, c, etc.
       \p     Break and spread output line.
       \r     Reverse  1 em  vertical  motion  (reverse  line  in
              nroff).
       \Rname ±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.
       \SN    Slant output N degrees.
       \t     Non-interpreted horizontal tab.
       \u     Reverse (up) 1/2 em vertical motion  (1/2  line  in
              nroff).
       \vN    Local  vertical  motion;  move  down N (up if nega­
              tive).
       \V[env]
              The contents of the environment variable  env.  Al­
              ternative forms \V(xy and \Vx.
       \wstring
              The width of the character sequence string.
       \xN    Extra  line-space  function (negative before, posi­
              tive after).
       \Xstring
              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).
       \Zanything
              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


   SPECIAL CHARACTERS
       Common  special  characters  are  predefined by escape se­
       quences 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 selec­
       tion  of the most important glyphs; a complete list can be
       found in groff_char(7).

              \(bu   ·      Bullet sign.
              \(co   ©      Copyright.
              \(ct   ˘      Cent.
              \(dd          Double dagger.
              \(de   °      Degree.
              \(dg          Dagger.
              \(em   --     Em-dash.
              \(hy   -      Hyphen.
              \(rg   ®      Registered sign.
              \(sc   §      Section sign.
              \(ul   _      Underline character.
              \(==   ==     Identical.
              \(>=   >=     Larger or equal.
              \(<=   <=     Less or equal.
              \(!=   !=     Not equal.
              \(->   ->     Right arrow.
              \(<-   <-     Left arrow.
              \(+-   ±      Plus-minus sign.


REGISTERS

       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 es­
       cape 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
       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[.a]    Post-line  extra  line-space  most recently uti­
                 lized using \x'N'.
       \n[.A]    Set to 1 in troff if option -A is used; always 1
                 in nroff.
       \n[.c]    Current input line number.
       \n[.C]    1  if  compatibility mode is in effect, 0 other­
                 wise.
       \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 cur­
                 rent environment.  The skew of  a  character  is
                 how  far to the right of the center of a charac­
                 ter 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[.H]    Available  horizontal resolution in basic units.
       \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  hy­
                 phenated 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[.int]  Positive if last output line contains \c.
       \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 re­
                 quest).

                 The  current  line-tabs  mode  (as  set  by  the
                 .linetabs request).
       \n[.ll]   The line length that applies to the current out­
                 put 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[.ns]   1 if in no-space mode, 0 otherwise.
       \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  cur­
                 rent 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 dec­
                 imal fraction (string-valued).
       \n[.t]    Distance to the next trap.
       \n[.T]    Set to 1 if option -T is used.
       \n[.tabs] A  string representation of the current tab set­
                 tings 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 regis­
                 ter.
       \n[.ss]   The value of the parameters set by the first ar­
                 gument 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[.V]    Available vertical resolution in basic units.
       \n[.vpt]  1 if vertical position traps are enabled, 0 oth­
                 erwise.
       \n[.w]    Width of previous character.
       \n[.warn] The sum of the number codes of the currently en­
                 abled warnings.
       \n[.x]    The major version number.
       \n[.y]    The minor version number.
       \n[.Y]    The revision number of groff.


   WRITABLE REGISTERS
       The following registers can be read and written by the us­
       er.  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[dn]    Height 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[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[ln]    Output line number.
       \n[mo]    Current month (1-12).
       \n[nl]    Vertical position of  last  printed  text  base-
                 line.
       \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[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 memo­
                 ry is exhausted.
       \n[ssc]   The amount of horizontal space  (possibly  nega­
                 tive) 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[systat]
                 The return value of the system()  function  exe­
                 cuted by the last .sy request.
       \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).
       \n[year]  The current year (year 2000 compliant).
       \n[yr]    Current year minus 1900.  For Y2K compliance use
                 register year instead.

       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 de­
                   fault.
       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  diver­
                   sions.   Automatically handled as empty.  Usu­
                   ally, only one warning per name.
       missing     8192
                   Request that  is  missing  non-optional  argu­
                   ments.
       input       16384
                   Illegal input character.
       number      2
                   Invalid  numeric expressions.  This is enabled
                   by default.
       range       64

       reg         1024
                   Use of undefined number  register.   Automati­
                   cally 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 num­
                   ber 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

       groff provides a compatibility mode that allows to process
       roff  code  written for classical or for other implementa­
       tions of roff in a consistent way.

       Compatibility mode can be turned on with  the  -C  command
       line  option,  and  turned on or off with the .cp request.
       The number register \n(.C is 1 if  compatibility  mode  is
       on, 0 otherwise.

       This  became  necessary  because  the GNU concept for long
       names causes some incompatibilities.  Classical troff will
       interpret

              .dsabcd

       as defining a string ab with contents cd.  Normally, groff


       Also classical troff will interpret \*[ or \n[  as  refer­
       ences  to a string or number register called [. In GNU na­
       tive mode, however, this will normally be  interpreted  as
       the start of a long name.

       In  compatibility  mode, groff will interpret these things
       in the traditional way, but long names are not recognized.

       On the other hand, groff in GNU native mode does not allow
       to use the escape  sequences  \e,  \|,  \^,  \&,  \},  \{,
       \ (space),  \',  \`,  \-,  \_,  \!, \%, and \c in names of
       strings, macros, diversions, number  registers,  fonts  or
       environments, whereas classical troff does.  The \A escape
       sequence can be helpful in avoiding these escape sequences
       in names.

       Fractional  pointsizes cause one noteworthy incompatibili­
       ty.  In classical troff, the .ps request ignores scale in­
       dicators and so

              .ps 10u

       will  set the pointsize to 10 points, whereas in groff na­
       tive mode the pointsize will be set to 10 scaled points.

       In groff mode, there is a fundamental  difference  between
       unformatted input characters, and formatted output charac­
       ters.  Everything that affects  how  an  output  character
       will  be output is stored with the character; once an out­
       put character has been constructed it is unaffected by any
       subsequent  requests that are executed, including the .bd,
       .cs, .tkf, .tr, or .fp requests.

       Normally output  characters  are  constructed  from  input
       characters  at the moment immediately before the character
       is added to the current output line.   Macros,  diversions
       and  strings  are  all,  in fact, the same type of object;
       they contain lists of input characters and output  charac­
       ters in any combination.

       An  output character does not behave like an input charac­
       ter for the purposes of macro processing; it does not  in­
       herit any of the special properties that the input charac­
       ter from which it was constructed  might  have  had.   The
       following example will make things clearer.

              .di x
              \\\\
              .br
              .di
              .x

       input backslashes `\\ is turned into a single output back­
       slash  `\ and the resulting output backslashes are not in­
       terpreted as escape characters when they are reread.

       Classical troff would interpret them as escape  characters
       when  they  were reread and would end up printing a single
       backslash `\.

       The correct way to get a printable `\ is to use the \e es­
       cape  sequence.   This will always print a single instance
       of the current escape character, regardless of whether  or
       not  it is used in a diversion.  It will also work in both
       GNU mode and compatibility mode.

       To store an escape sequence in a diversion  that  will  be
       interpreted  when the diversion is reread, either the tra­
       ditional \! transparent output facility or the new \?  es­
       cape sequence can be used.


BUGS

       At the moment, the documentation of the groff system is in
       a state of change and  evolution.   It  is  possible  that
       there  are  small  inconsistencies between different docu­
       ments temporarily.

       The WARNINGS section belongs to troff(1).


AUTHOR

       This document is part of groff, the GNU roff distribution.
       It was written by Bernd Warken <bwarken@mayn.de>.

       It  is  distributed  under  the terms of the FDL (GNU Free
       Documentation License) version 1.1 or later.   You  should
       have received a copy of the FDL on your system, it is also
       available on-line under

              http://www.gnu.org/copyleft/fdl.html.

       Formerly, the extensions of the groff language  were  kept
       in  the  manual page troff(1).  This document contains the
       essential parts of that documentation, but  the  gory  de­
       tails are found in the groff info file.


SEE ALSO

       The  main  source of information for the groff language is
       the groff info(1) file.

       For a survey of roff and the groff system and further doc­
       umentation pointers see roff(7).

       The  formatter  programs  are  described  in  groff(1) and
       troff(1); a complete of all predefined glyph names can  be
       found in groff_char(7).


              http://cm.bell-labs.com/cm/cs/cstr.html
       and
              http://www.kohala.com/start/troff/.


Man(1) output converted with man2html