Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
GROFF(7)	       Miscellaneous Information Manual		      GROFF(7)

       groff - a short reference for the GNU roff language

       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 lan-
       guage 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 modi-
       fied by escape sequences, which are recognized by a  leading  backslash
       `\'.  These  are	 in-line  or even in-word formatting elements or func-
       tions.  Some of these take arguments separated by  single  quotes  "'",
       others  are regulated by	a length encoding introduced by	an open	paren-
       thesis `(' 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

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

       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.   Re-
       quests  are written on a	line of	their own starting with	a dot `.' or a
       "'", whereas Escape sequences are in-line functions and in-word format-
       ting 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  re-
       quests.	 Macro	packages are pre-defined sets of macros	written	in the
       groff language.	A user's possibilities to create escape	sequences her-
       self 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  pa-
       rameters	 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 se-
       quences.	 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  diversion	stores
       information  into a macro for later usage.  A trap is a positional con-
       dition 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.

       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  us-
	      ing  the .cc request, the	control	character can be set to	a dif-
	      ferent 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 separa-
	      tor in some functional escape sequences (but any pair of charac-
	      ters  not	 part  of the argument will work).  In all other posi-
	      tions, it	denotes	the  single  quote  or	apostrophe  character.
	      Groff  provides  a printable representation with the \(cq	escape

       "      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	after-
	      wards  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

       (      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 []

       [      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  calcula-
	      tions.  To get a defined space width, escape sequences like `\ '
	      (this is the escape character followed by	a space), \|,  \^,  or
	      \h should	be used.

	      In  text	paragraphs,  newlines mostly behave like space charac-
	      ters.  Continuation lines	can be specified by  an	 escaped  new-
	      line,  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 pre-defined tab position.  There is
	      a	sophisticated interface	for handling tab positions.

       A numerical value is a signed or	unsigned  integer  or  float  with  or
       without	an appended scale indicator.  A	scale indicator	is a one-char-
       acter 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  expres-

		  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 occur	in tests raised	by the .if, .ie, and  the  .while  re-
       quests.	 The following table characterizes the different types of con-

		 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
		 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.

       This  section  provides	a short	reference for the predefined requests.
       In groff, request and macro names can be	arbitrarily long.  No bracket-
       ing 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 cho-
       sen to be descriptive.  Only the	following denotations need  clarifica-

		 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 in-
       herent 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

       .	 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
       .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
       .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 escape  sequences
		 in diversion.
		 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.
       .bp +-N	 Eject current page; next page number +-N.
       .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  ob-
       .close stream
		 Close the stream.
		 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	 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  contained  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	macro, respectively.
       .di	 End current diversion.
       .di macro Divert	to macro.
       .do name	 Interpret .name with compatibility mode disabled.
       .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 current environ-
		 ment.	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 internal 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
       .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 register.
		 Enable	line-tabs mode (i.e., calculate	tab positions 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 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 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  in-
       .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-increment 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
       .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 filename.
       .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 in-
		 put line traps	and diversion traps) 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 char-
		 acters	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  re-
       .sy command-line
		 Execute program command-line.
       .ta T N	 Set  tabs  after  every position that is a multiple of	N (de-
		 fault 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.
       .tm anything
		 Print anything	on terminal (UNIX standard message output).
       .tm1 anything
		 Print anything	on terminal (UNIX  standard  message  output),
		 allowing  leading whitespace if anything starts with "	(which
		 will be stripped off).
       .tmc anything
		 Similar to .tm1 without emitting a final newline.
       .tr abcd....
		 Translate a to	b, c to	d, etc.	on output.
       .trf filename
		 Transparently output the contents of file filename.
       .trnt abcd....
		 This is the same as the .tr request except that the  transla-
		 tions	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  informa-
		 tion in diversion.
       .vpt n	 Enable	vertical position traps	if n is	non-zero, disable them
       .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 are in-line language elements usually introduced by a
       backslash `\' and followed by an	escape name and	 sometimes  by	a  re-
       quired  argument.  Input	processing is continued	directly after the es-
       caped 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 argu-
       ments (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 apostrophes, too,
       but there is no two-character analogue.

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

       \"     Beginning	of a comment.  Everything up to	the end	of the line is
       \#     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
       \*(st  The string stored	in the string variable with  2-character  name
	      The  string  stored in the string	variable with arbitrary	length
	      name stringvar.
       \$0    The name by which	the current macro was invoked.	The  .als  re-
	      quest 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.
	      Macro argument with number nexp, where nexp is a	numerical  ex-
	      pression evaluating to an	integer	>=1.
       \$*    In  a macro, the concatenation of	all the	arguments separated by
       \$@    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 interpreta-
	      tion as escape character in copy mode.  For  a  printable	 back-
	      slash, 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,	 back-
	      quote (ASCII 0x60).
       \-     The - sign in the	current	font.
       \.     An uninterpreted dot (period), even at start of line.
       \%     Default optional hyphenation character.
       \!     Transparent line indicator.
	      In  a  diversion,	 this will transparently embed anything	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 spac-
	      ing 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.
       \:     Inserts a	zero-width break point (similar	to \%  but  without  a
	      soft hyphen character).
	      Ignored newline, for continuation	lines.
       \{     Begin conditional	input.
       \}     End conditional input.
       \(st   The special character with 2-character name st, see section SPE-
	      The named	character with arbitrary length	name name.
       \a     Non-interpreted leader character.
	      If anything is acceptable	as a name of a string,	macro,	diver-
	      sion,  register, environment or font it expands to 1, and	0 oth-
	      Bracket building function.
	      If anything is acceptable	as a valid numeric expression  it  ex-
	      pands to 1, and 0	otherwise.
       \c     Interrupt	text processing.
	      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).
	      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
       \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.
	      Change to	font with arbitrary length name	or  number  expression
	      Return format of register	with name reg suitable for .af.	Alter-
	      native 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.
	      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.
	      The  numerical  value stored in the register variable with arbi-
	      trary lenght name	reg.
       \N'n'  Typeset the character with code n	in the current font,  no  spe-
	      cial fonts are searched.	Useful for adding characters to	a font
	      using the	.char request.
	      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.
	      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).
	      The contents of the environment variable env. Alternative	 forms
	      \V(xy and	\Vx.
	      The width	of the character sequence string.
       \x'N'  Extra line-space function	(negative before, positive after).
	      Output string as device control function.
	      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).
	      Print anything and then restore the horizontal and vertical  po-
	      sition; 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 charac-
       ter escape sequences, but introduce escape names	with two or more char-

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

       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   <degree>
	      \(dg   <*>    Dagger.
	      \(em   --	    Em-dash.
	      \(hy   -	    Hyphen.
	      \(rg   (R)    Registered sign.
	      \(sc   <section>
			    Section sign.
	      \(ul   _	    Underline character.
	      \(==   ==	    Identical.
	      \(>=   >=	    Larger or equal.
	      \(<=   <=	    Less or equal.
	      \(!=   !=	    Not	equal.
	      \(->   ->	    Right arrow.
	      \(<-   <-	    Left arrow.
	      \(+-   +-	    Plus-minus sign.

       Registers are variables that store a value.  In groff,  most  registers
       store  numerical	 values	(see section NUMERICAL 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.

       The following registers have predefined values that should not be modi-
       fied by the user	(usually, registers starting with a dot	a  read-only).
       Mostly,	they  provide information on the current settings or store re-
       sults from request calls.

       \n[.$]	 Number	of arguments in	the current macro.
       \n[.a]	 Post-line  extra  line-space  most  recently  utilized	 using
       \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 otherwise.
       \n[.cdp]	 The depth of the last character added to the current environ-
		 ment.	It is positive if  the	character  extends  below  the
       \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	 envi-
		 ronment.   It	is positive if the character extends above the
       \n[.csk]	 The skew of the last character	added to the current  environ-
		 ment.	The skew of a character	is how far to the right	of the
		 center	of a character the center of an	accent over that char-
		 acter should be placed.
       \n[.d]	 Current  vertical place in current diversion; equal to	regis-
		 ter nl.
       \n[.ev]	 The name or number of the  current  environment  (string-val-
       \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 run-
		 ning 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
       \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[.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 request).
		 The current line-tabs mode (as	set by the .linetabs 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
       \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 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
       \n[.s]	 Current point size as a decimal fraction.
       \n[.sr]	 The last requested pointsize in points	as a decimal  fraction
       \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 settings suitable
		 for use as an argument	to the .ta request.
		 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 po-
		 sition	 would have been but for the trap, and what the	verti-
		 cal position actually is.  Useful in conjunction with the .ne
       \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[.V]	 Available vertical resolution in basic	units.
       \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 warn-
       \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.

       The following registers can be read and written by the user.  They have
       predefined  default values, but these can be modified for customizing a

       \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 char-
       \n[rst]	 Like st, but takes account of the heights and depths of char-
       \n[sb]	 Depth of string below base line (generated by width  function
       \n[skw]	 Right skip width from the center of the last character	in the
		 \w argument.
		 If greater than 0, the	maximum	number of objects on the input
		 stack.	 If <=0	there is no limit, i.e., recursion can contin-
		 ue until virtual memory is exhausted.
       \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
		 The  return  value  of	 the system() function executed	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 num-
       ber.  The codes are powers of 2 to allow	bit-encoding with a single in-
       teger.	There  are  also  names	that can be used to refer to groups of

       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]	regis-

       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
       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 cur-
		   rent	diversion.
       el	   16
		   Use of the .el request with no matching .ie request.
       escape	   32768
		   Unrecognized	escape sequence.  Then the escape character is
       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  out-
		   side	of ignored text.
       mac	   512
		   Use of undefined strings, macros, and diversions.  Automat-
		   ically handled as empty.  Usually,  only  one  warning  per
       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, only 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
       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     |		      |
       groff provides a	compatibility mode that	allows to  process  roff  code
       written for classical or	for other implementations of roff in a consis-
       tent 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


       as  defining a string ab	with contents cd.  Normally, groff will	inter-
       pret this as a call of a	macro named dsabcd.

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

       In compatibility	mode, groff will interpret these things	in the	tradi-
       tional 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 se-
       quence can be helpful in	avoiding these escape sequences	in names.

       Fractional pointsizes cause one noteworthy incompatibility.  In classi-
       cal troff, the .ps request ignores scale	indicators and so

	      .ps 10u

       will set	the pointsize to 10 points, whereas in groff native  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 characters.  Everything that af-
       fects how an output character will be output is stored with the charac-
       ter; once an output 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 characters
       in any combination.

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

	      .di x

       In  GNU	mode  this  will be printed as \\. So each pair	of input back-
       slashes `\\' is turned into a single output backslash `\' and  the  re-
       sulting	output	backslashes  are  not interpreted 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 escape se-
       quence.	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 traditional	\! transparent
       output facility or the new \? escape sequence can be used.

       At the moment, the documentation	of the groff system is in a  state  of
       change and evolution.  It is possible that there	are small inconsisten-
       cies between different documents	temporarily.

       The WARNINGS section belongs to troff(1).

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

       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

       Formerly,  the extensions of the	groff language were kept in the	manual
       page troff(1).  This document contains the essential parts of that doc-
       umentation, but the gory	details	are found in the groff info file.

       The  main source	of information for the groff language is the groff in-
       fo(1) file.

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

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

       The classical troff documentation is available on-line at

Groff Version 1.17.2		 6 August 2001			      GROFF(7)


Want to link to this manual page? Use this URL:

home | help