troff man page on BSDi

Man page or keyword search:  
man Server   6284 pages
apropos Keyword Search (all sections)
Output format
BSDi logo
[printable version]



TROFF(1)						 TROFF(1)

NAME
       troff - format documents

SYNOPSIS
       troff [ -abivzCERU ] [ -wname ] [ -Wname ] [ -dcs ]
	     [ -ffam ] [ -mname ] [ -nnum ] [ -olist ] [ -rcn ]
	     [ -Tname ] [ -Fdir ] [ -Mdir ] [ files... ]

DESCRIPTION
       This manual page describes the GNU version of troff, which
       is part of the groff document formatting	 system.   It  is
       highly  compatible  with Unix troff.  Usually it should be
       invoked using the groff command, which will also run  pre-
       processors and postprocessors in the appropriate order and
       with the appropriate options.

OPTIONS
       -a	 Generate an ASCII approximation of  the  typeset
		 output.

       -b	 Print	a  backtrace  with  each warning or error
		 message.  This backtrace should help track  down
		 the  cause of the error.  The line numbers given
		 in the backtrace  may	not  always  be	 correct:
		 troff	's  idea of line numbers gets confused by
		 as or am requests.

       -i	 Read the standard  input  after  all  the  named
		 input files have been processed.

       -v	 Print the version number.

       -wname	 Enable	 warning  name.	  Available  warnings are
		 described  in	the  Warnings  subsection  below.
		 Multiple -w options are allowed.

       -Wname	 Inhibit  warning  name.  Multiple -W options are
		 allowed.

       -E	 Inhibit all error messages.

       -z	 Suppress formatted output.

       -C	 Enable compatibility mode.

       -dcs
       -dname=s	 Define c or name to be a string s; c must  be	a
		 one letter name.

       -ffam	 Use fam as the default font family.

       -mname	 Read  in the file tmac.name.  Normally this will
		 be searched for in /usr/share/tmac.  By  default
		 is used the safer macro (reverted using -U ).

Groff Version 1.15	   8 March 2000				1

TROFF(1)						 TROFF(1)

       -U	 Unsafe	 option,  avoids  default  use	of  safer
		 macro.

       -R	 Don't load troffrc.

       -nnum	 Number the first page num.

       -olist	 Output only pages in list, which is a comma-sep-
		 arated	 list  of page ranges; n means print page
		 n, m-n means print every page between m  and  n,
		 -n  means  print  every  page	up to n, n- means
		 print every page from n.  Troff will exit  after
		 printing the last page in the list.

       -rcn
       -rname=n	 Set  number register c or name to n; c must be a
		 one character name; n can be any  troff  numeric
		 expression.

       -Tname	 Prepare  output for device name, rather than the
		 default ps.

       -Fdir	 Search dir for subdirectories devname	(name  is
		 the  name  of	the device) for the DESC file and
		 font	   files      before	  the	   normal
		 /usr/share/groff_font.

       -Mdir	 Search	 directory dir for macro files before the
		 normal /usr/share/tmac.

USAGE
       Only the features not in Unix troff are described here.

   Long names
       The     names	 of	number	   registers,	   fonts,
       strings/macros/diversions,  special  characters	can be of
       any length. In escape sequences, where you can use (xx for
       a  two  character  name,	 you  can use [xxx] for a name of
       arbitrary length:

       \[xxx] Print the special character called xxx.

       \f[xxx]
	      Set font xxx.

       \*[xxx]
	      Interpolate string xxx.

       \n[xxx]
	      Interpolate number register xxx.

   Fractional pointsizes
       A scaled point  is  equal  to  1/sizescale  points,  where
       sizescale  is  specified	 in the DESC file (1 by default.)

Groff Version 1.15	   8 March 2000				2

TROFF(1)						 TROFF(1)

       There is a new scale indicator z which has the  effect  of
       multiplying  by	sizescale.  Requests and escape sequences
       in troff interpret arguments that represent a pointsize as
       being  in  units	 of scaled points, but they evaluate each
       such argument using a default scale indicator of z.  Argu-
       ments  treated  in  this	 way  are  the argument to the ps
       request, the third argument to the cs request, the  second
       and  fourth  arguments to the tkf request, the argument to
       the \H escape sequence,	and  those  variants  of  the  \s
       escape  sequence	 that  take a numeric expression as their
       argument.

       For example, suppose sizescale  is  1000;  then	a  scaled
       point  will be equivalent to a millipoint; the request .ps
       10.25 is equivalent to .ps 10.25z and so sets  the  point-
       size  to	 10250	scaled	points,	 which	is equal to 10.25
       points.

       The number register \n(.s returns the pointsize in  points
       as  decimal fraction.  There is also a new number register
       \n[.ps] that returns the pointsize in scaled points.

       It would make no sense to use the z scale indicator  in	a
       numeric	expression whose default scale indicator was nei-
       ther u nor z, and so troff disallows this.   Similarly  it
       would  make no sense to use a scaling indicator other than
       z or u in a numeric expression whose default scale indica-
       tor was z, and so troff disallows this as well.

       There  is  also	new scale indicator s which multiplies by
       the number of units in a scaled point.  So,  for	 example,
       \n[.ps]s is equal to 1m.	 Be sure not to confuse the s and
       z scale indicators.

   Numeric expressions
       Spaces are permitted in a number expression within  paren-
       theses.

       M indicates a scale of 100ths of an em.

       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 indica-
	      tor.  If c is missing, ignore scaling indicators in
	      the evaluation of e.

   New escape sequences
       \A'anything'
	      This  expands to 1 or 0 according as anything is or
	      is not acceptable as the name of a  string,  macro,
	      diversion,  number  register,  environment or font.
	      It will return 0 if anything  is	empty.	 This  is

Groff Version 1.15	   8 March 2000				3

TROFF(1)						 TROFF(1)

	      useful  if  you  want  to lookup user input in some
	      sort of associative table.

       \C'xxx'
	      Typeset character named xxx.  Normally it	 is  more
	      convenient to use \[xxx].	 But \C has the advantage
	      that it is compatible with recent versions of  UNIX
	      and is available in compatibility mode.

       \E     This is equivalent to an escape character, but it's
	      not interpreted in copy-mode.  For example, strings
	      to  start	 and  end superscripting could be defined
	      like this:

		     .ds { \v'-.3m'\s'\En[.s]*6u/10u'
		     .ds } \s0\v'.3m'

	      The use of \E ensures that these	definitions  will
	      work even if \*{ gets interpreted in copy-mode (for
	      example, by being used in a macro argument.)

       \N'n'  Typeset the character with code n	 in  the  current
	      font.   n	 can  be  any integer.	Most devices only
	      have characters with codes between 0 and	255.   If
	      the  current font does not contain a character with
	      that code, special fonts will not be searched.  The
	      \N escape sequence can be conveniently used on con-
	      junction with the char request:

		     .char \[phone] \f(ZD\N'37'

	      The code of each character is given in  the  fourth
	      column  in  the  font  description  file	after the
	      charset command.	It is possible to include unnamed
	      characters  in the font description file by using a
	      name of ---; the \N escape sequence is the only way
	      to use these.

       \R'name +-n'
	      This has the same effect as

		     .nr name +-n

       \s(nn
       \s+-(nn
	      Set the point size to nn points; nn must be exactly
	      two digits.

       \s[+-n]
       \s+-[n]
       \s'+-n'
       \s+-'n'
	      Set the point size to  n	scaled	points;	 n  is	a
	      numeric  expression  with a default scale indicator

Groff Version 1.15	   8 March 2000				4

TROFF(1)						 TROFF(1)

	      of z.

       \Vx
       \V(xx
       \V[xxx]
	      Interpolate the contents of the  environment  vari-
	      able  xxx , as returned by getenv(3).  \V is inter-
	      preted in copy-mode.

       \Yx
       \Y(xx
       \Y[xxx]
	      This is approximately  equivalent	 to  \X'\*[xxx]'.
	      However the contents of the string or macro xxx are
	      not interpreted; also it is permitted  for  xxx  to
	      have  been defined as a macro and thus contain new-
	      lines (it is not permitted for the argument  to  \X
	      to  contain  newlines).	The inclusion of newlines
	      requires an extension to the Unix troff output for-
	      mat,  and	 will  confuse	drivers	 that do not know
	      about this extension.

       \Z'anything'
	      Print anything and then restore the horizontal  and
	      vertical position; anything may not contain tabs or
	      leaders.

       \$0    The name by which the current  macro  was	 invoked.
	      The als request can make a macro have more than one
	      name.

       \$*    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  sepa-
	      rated by spaces.

       \$(nn
       \$[nnn]
	      In  a  macro,  this gives the nn-th or nnn-th argu-
	      ment.  Macros can have a unlimited number of  argu-
	      ments.

       \?anything\?
	      When  used  in a diversion, this will transparently
	      embed anything in the diversion.	anything is  read
	      in  copy	mode.  When the diversion is reread, any-
	      thing will be interpreted.  anything may	not  con-
	      tain  newlines;  use  \!	if you want to embed new-
	      lines in a diversion.  The escape sequence  \?   is
	      also recognised in copy mode and turned into a sin-
	      gle internal code; it is this code that  terminates
	      anything.	 Thus

Groff Version 1.15	   8 March 2000				5

TROFF(1)						 TROFF(1)

		     .nr x 1
		     .nf
		     .di d
		     \?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
		     .di
		     .nr x 2
		     .di e
		     .d
		     .di
		     .nr x 3
		     .di f
		     .e
		     .di
		     .nr x 4
		     .f

	      will print 4.

       \/     This 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.   For	 example,
	      if  an  italic f is immediately followed by a roman
	      right parenthesis, then in many fonts the top right
	      portion  of  the f will overlap the top left of the
	      right parenthesis	 producing  f),	 which	is  ugly.
	      Inserting	 \/  produces f) and avoids this problem.
	      It is a good idea to use this escape sequence when-
	      ever an italic character is immediately followed by
	      a roman character without any intervening space.

       \,     This modifies the spacing of the following  charac-
	      ter  so that the spacing between that character and
	      the preceding character will correct if the preced-
	      ing  character  is a roman character.  For example,
	      inserting \, between  the	 parenthesis  and  the	f
	      changes  (f  to  (f.  It is a good idea to use this
	      escape sequence whenever a roman character is imme-
	      diately followed by an italic character without any
	      intervening space.

       \)     Like \& except that it  behaves  like  a	character
	      declared	with the cflags request to be transparent
	      for the purposes of end of sentence recognition.

       \~     This produces an unbreakable space  that	stretches
	      like  a  normal  inter-word  space  when	a line is
	      adjusted.

       \#     Everything up to and including the next newline  is
	      ignored.	 This  is interpreted in copy mode.  This
	      is like \" except that \" does not ignore the  ter-
	      minating newline.

Groff Version 1.15	   8 March 2000				6

TROFF(1)						 TROFF(1)

   New requests
       .aln xx yy
	      Create an alias xx for number register object named
	      yy.  The new name and the old name will be  exactly
	      equivalent.   If yy is undefined, a warning of type
	      reg will be generated,  and  the	request	 will  be
	      ignored.

       .als xx yy
	      Create  an  alias xx for request, string, macro, or
	      diversion object named yy.  The new  name	 and  the
	      old  name will be exactly equivalent (it is similar
	      to a hard rather than a soft link).  If yy is unde-
	      fined, a warning of type mac will be generated, and
	      the request will be ignored.  The de, am,	 di,  da,
	      ds, and as requests only create a new object if the
	      name of the macro, diversion or string diversion is
	      currently	 undefined  or	if  it is defined to be a
	      request; normally	 they  modify  the  value  of  an
	      existing object.

       .asciify xx
	      This request only exists in order to make it possi-
	      ble to make  certain  gross  hacks  work	with  GNU
	      troff.   It  `unformats' the diversion xx in such a
	      way that ASCII characters that were  formatted  and
	      diverted	into  xx  will	be  treated like ordinary
	      input characters when xx is reread.   For	 example,
	      this

		     .tr  @.
		     .di  x
		     @nr\  n\  1
		     .br
		     .di
		     .tr  @@
		     .asciify  x
		     .x

	      will set register n to 1.

       .backtrace
	      Print a backtrace of the input stack on stderr.

       .blm xx
	      Set  the	blank  line  macro  to xx.  If there is a
	      blank line macro, it will be invoked when	 a  blank
	      line  is	encountered  instead  of  the usual troff
	      behaviour.

       .break Break out of a while loop.  See also the while  and
	      continue	requests.   Be	sure  not to confuse this
	      with the br request.

Groff Version 1.15	   8 March 2000				7

TROFF(1)						 TROFF(1)

       .cflags n c1 c2...
	      Characters c1, c2,...  have  properties  determined
	      by n, which is ORed from the following:

	      1	     the   character  ends  sentences  (initially
		     characters .?!  have this property);

	      2	     lines can be  broken  before  the	character
		     (initially	 no  characters	 have  this prop-
		     erty); a line will not be broken at a  char-
		     acter  with this property unless the charac-
		     ters on each side both have non-zero hyphen-
		     ation codes.

	      4	     lines  can	 be  broken  after  the character
		     (initially characters  -\(hy\(em  have  this
		     property);	 a  line  will not be broken at a
		     character	with  this  property  unless  the
		     characters	 on  each side both have non-zero
		     hyphenation codes.

	      8	     the character  overlaps  horizontally  (ini-
		     tially  characters	 \(ul\(rn\(ru  have  this
		     property);

	      16     the character overlaps vertically (initially
		     character \(br has this property);

	      32     an end of sentence character followed by any
		     number of characters with this property will
		     be	 treated as the end of a sentence if fol-
		     lowed by a newline or two spaces;	in  other
		     words  the	 character is transparent for the
		     purposes of  end  of  sentence  recognition;
		     this is the same as having a zero space fac-
		     tor    in	  TeX	 (initially    characters
		     "')]*\(dg\(rq have this property).

       .char c string
	      Define  character c to be string.	 Every time char-
	      acter c needs to be printed, string  will	 be  pro-
	      cessed  in  a  temporary environment and the result
	      will be wrapped up into a single object.	 Compati-
	      bility mode will be turned off and the escape char-
	      acter will be set to \ while string is  being  pro-
	      cessed.  Any emboldening, constant spacing or track
	      kerning will be applied to this object rather  than
	      to  individual  characters  in string.  A character
	      defined by this request can be  used  just  like	a
	      normal character provided by the output device.  In
	      particular other characters can be translated to it
	      with  the	 tr  request;  it  can be made the leader
	      character by the lc request; repeated patterns  can
	      be  drawn	 with  the  character using the \l and \L

Groff Version 1.15	   8 March 2000				8

TROFF(1)						 TROFF(1)

	      escape sequences; words  containing  the	character
	      can  be  hyphenated correctly, if the hcode request
	      is used to give the character a  hyphenation  code.
	      There  is	 a special anti-recursion feature: use of
	      character within the character's definition will be
	      handled  like  normal  characters	 not defined with
	      char.  A character definition can be  removed  with
	      the rchar request.

       .chop xx
	      Chop  the	 last  character  off  macro,  string, or
	      diversion xx.  This is useful for removing the new-
	      line  from  the  end  of	diversions that are to be
	      interpolated as strings.

       .close stream
	      Close the	 stream	 named	stream;	 stream	 will  no
	      longer  be  an  acceptable  argument  to	the write
	      request.	See the open request.

       .continue
	      Finish the current iteration of a while loop.   See
	      also the while and break requests.

       .cp n  If  n  is non-zero or missing, enable compatibility
	      mode, otherwise disable it.  In compatibility mode,
	      long  names  are not recognised, and the incompati-
	      bilities caused by long names do not arise.

       .do xxx
	      Interpret .xxx with  compatibility  mode	disabled.
	      For example,

		     .do fam T

	      would have the same effect as

		     .fam T

	      except  that  it	would  work even if compatibility
	      mode had been enabled.  Note that the previous com-
	      patibility   mode	 is  restored  before  any  files
	      sourced by xxx are interpreted.

       .fam xx
	      Set the current font family  to  xx.   The  current
	      font  family  is	part  of the current environment.
	      See the description of the  sty  request	for  more
	      information on font families.

       .fspecial f s1 s2...
	      When  the current font is f, fonts s1, s2,...  will
	      be special, that is, they will searched for charac-
	      ters  not in the current font.  Any fonts specified

Groff Version 1.15	   8 March 2000				9

TROFF(1)						 TROFF(1)

	      in the special request will be searched after fonts
	      specified in the fspecial request.

       .ftr f g
	      Translate	 font f to g.  Whenever a font named f is
	      referred to in \f escape sequence, or  in	 the  ft,
	      ul,  bd,	cs,  tkf,  special,  fspecial, fp, or sty
	      requests, font g will be used.  If g is missing, or
	      equal to f then font f will not be translated.

       .hcode c1 code1 c2 code2...
	      Set  the	hyphenation code of character c1 to code1
	      and that of c2 to code2.	A hyphenation  code  must
	      be  a single input character (not a special charac-
	      ter) other than a digit or a space.  Initially each
	      lower-case  letter has a hyphenation code, which is
	      itself, and each upper-case letter  has  a  hyphen-
	      ation  code  which  is  the  lower  case version of
	      itself.  See also the hpf request.

       .hla lang
	      Set  the	current	 hyphenation  language	to  lang.
	      Hyphenation   exceptions	 specified  with  the  hw
	      request and hyphenation patterns specified with the
	      hpf  request  are	 both associated with the current
	      hyphenation language.  The hla request  is  usually
	      invoked by the troffrc file.

       .hlm n Set  the	maximum	 number of consecutive hyphenated
	      lines to n.  If n is negative, there is no maximum.
	      The  default value is -1.	 This value is associated
	      with the current environment.   Only  lines  output
	      from an environment count towards the maximum asso-
	      ciated with that	environment.   Hyphens	resulting
	      from \% are counted; explicit hyphens are not.

       .hpf file
	      Read  hyphenation	 patterns from file; this will be
	      searched for in the  same	 way  that  tmac.name  is
	      searched	for  when the -mname option is specified.
	      It should have the same format as the  argument  to
	      the \patterns primitive in TeX; the letters appear-
	      ing in this file	are  interpreted  as  hyphenation
	      codes.   A  % character in the patterns file intro-
	      duces a comment that continues to the  end  of  the
	      line.   The  set of hyphenation patterns is associ-
	      ated with the  current  language	set  by	 the  hla
	      request.	The hpf request is usually invoked by the
	      troffrc file.

       .hym n Set the hyphenation margin to n: when  the  current
	      adjustment  mode	is  not	 b,  the line will not be
	      hyphenated if the line is no  more  than	n  short.
	      The  default  hyphenation margin is 0.  The default

Groff Version 1.15	   8 March 2000			       10

TROFF(1)						 TROFF(1)

	      scaling indicator	 for  this  request  is	 m.   The
	      hyphenation  margin  is associated with the current
	      environment.  The	 current  hyphenation  margin  is
	      available in the \n[.hym] register.

       .hys n Set  the	hyphenation  space to n: when the current
	      adjustment mode is b don't hyphenate  the	 line  if
	      the  line can be justified by adding no more than n
	      extra  space  to	each  word  space.   The  default
	      hyphenation  space is 0.	The default scaling indi-
	      cator for this request is m.  The hyphenation space
	      is  associated  with  the current environment.  The
	      current  hyphenation  space  is  available  in  the
	      \n[.hys] register.

       .kern n
	      If  n is non-zero or missing, enable pairwise kern-
	      ing, otherwise disable it.

       .mso file
	      The same as the so  request  except  that	 file  is
	      searched	for  in	 the  same  way that tmac.name is
	      searched for when the -mname option is specified.

       .nroff Make the n built-in condition true and the t built-
	      in condition false.  This can be reversed using the
	      troff request.

       .open stream filename
	      Open filename for writing and associate the  stream
	      named stream with it.  See also the close and write
	      requests.

       .opena stream filename
	      Like open, but if filename  exists,  append  to  it
	      instead of truncating it.

       .pnr   Print  the  names	 and  contents	of  all currently
	      defined number registers on stderr.

       .pso command
	      This is behaves like the	so  request  except  that
	      input comes from the standard output of command.

       .ptr   Print  the  names	 and  positions of all traps (not
	      including input line traps and diversion traps)  on
	      stderr.	Empty  slots  in  the  page trap list are
	      printed as well, because they can affect the prior-
	      ity of subsequently planted traps.

       .rchar c1 c2...
	      Remove  the  definitions	of  characters c1, c2,...
	      This undoes the effect of a char request.

Groff Version 1.15	   8 March 2000			       11

TROFF(1)						 TROFF(1)

       .rj
       .rj n  Right justify the next n input lines.   Without  an
	      argument	right  justify	the next input line.  The
	      number of lines to be right justified is	available
	      in  the  \n[.rj]	register.   This  implicitly does
	      .ce 0.  The ce request implicitly does .rj 0.

       .rnn xx yy
	      Rename number register xx to yy.

       .shc c Set the soft hyphen character to c.  If c is  omit-
	      ted,  the	 soft hyphen character will be set to the
	      default \(hy.  The soft  hyphen  character  is  the
	      character	 which	will  be  inserted when a word is
	      hyphenated at a line break.   If	the  soft  hyphen
	      character does not exist in the font of the charac-
	      ter immediately preceding a potential break  point,
	      then  the	 line  will  not be broken at that point.
	      Neither  definitions  (specified	with   the   char
	      request)	nor  translations  (specified with the tr
	      request)	are  considered	 when  finding	the  soft
	      hyphen character.

       .shift n
	      In  a  macro,  shift  the arguments by n positions:
	      argument i becomes argument i-n; arguments 1  to	n
	      will  no	longer	be  available.	 If n is missing,
	      arguments will be shifted by 1.  Shifting by  nega-
	      tive amounts is currently undefined.

       .special s1 s2...
	      Fonts  s1, s2, are special and will be searched for
	      characters not in the current font.

       .sty n f
	      Associate style f with font  position  n.	  A  font
	      position	can  be	 associated either with a font or
	      with a style.  The current font is the index  of	a
	      font  position  and  so  is also either a font or a
	      style.  When it is a style, the font that is  actu-
	      ally used is the font the name of which is the con-
	      catenation of the name of the  current  family  and
	      the name of the current style.  For example, if the
	      current font is 1 and font position 1 is associated
	      with style R and the current font family is T, then
	      font TR will be used.  If the current font is not a
	      style,  then  the	 current family is ignored.  When
	      the requests cs,	bd,  tkf,  uf,	or  fspecial  are
	      applied  to  a  style,  then  they  will instead be
	      applied to the member of the current family  corre-
	      sponding	to that style.	The default family can be
	      set with the -f option.  The styles command in  the
	      DESC  file  controls  which font positions (if any)
	      are initially associated with  styles  rather  than

Groff Version 1.15	   8 March 2000			       12

TROFF(1)						 TROFF(1)

	      fonts.

       .tkf f s1 n1 s2 n2
	      Enable  track kerning for font f.	 When the current
	      font is f the width  of  every  character	 will  be
	      increased	 by an amount between n1 and n2; when the
	      current point size is less than or equal to s1  the
	      width  will  be increased by n1; when it is greater
	      than or equal to s2 the width will be increased  by
	      n2; when the point size is greater than or equal to
	      s1 and less than or equal to  s2	the  increase  in
	      width is a linear function of the point size.

       .trf filename
	      Transparently output the contents of file filename.
	      Each line is output as it would be were it preceded
	      by  \!; however, the lines are not subject to copy-
	      mode interpretation.  If the file does not end with
	      a newline, then a newline will be added.	For exam-
	      ple, you can define a macro x containing	the  con-
	      tents of file f, using

		     .di x
		     .trf f
		     .di

	      Unlike with the cf request, the file cannot contain
	      characters such as NUL that  are	not  legal  troff
	      input characters.

       .trnt abcd
	      This  is the same as the tr request except that the
	      translations do not apply to text that is transpar-
	      ently  throughput	 into  a  diversion with \!.  For
	      example,

	      .tr ab
	      .di x
	      \!.tm a
	      .di
	      .x

	      will print b; if trnt is used instead of tr it will
	      print a.

       .troff Make  the	 n  built-in  condition	 false, and the t
	      built-in condition true.	This undoes the effect of
	      the nroff request.

       .vpt n Enable  vertical	position  traps if n is non-zero,
	      disable them otherwise.	Vertical  position  traps
	      are  traps set by the wh or dt requests.	Traps set
	      by the it request are not vertical position  traps.
	      The   parameter	that  controls	whether	 vertical

Groff Version 1.15	   8 March 2000			       13

TROFF(1)						 TROFF(1)

	      position traps are enabled  is  global.	Initially
	      vertical position traps are enabled.

       .warn n
	      Control  warnings.   n  is  the  sum of the numbers
	      associated with each warning that is to be enabled;
	      all  other  warnings  will be disabled.  The number
	      associated with  each  warning  is  listed  in  the
	      `Warnings' section.  For example, .warn 0 will dis-
	      able all warnings, and .warn  1  will  disable  all
	      warnings	except that about missing characters.  If
	      n is not given, all warnings will be enabled.

       .while c anything
	      While condition  c  is  true,  accept  anything  as
	      input;  c	 can be any condition acceptable to an if
	      request; anything can comprise  multiple	lines  if
	      the  first  line	starts	with \{ and the last line
	      ends with \}.  See  also	the  break  and	 continue
	      requests.

       .write stream anything
	      Write  anything to the stream named stream.  stream
	      must previously have been the subject  of	 an  open
	      request.	 anything is read in copy mode; a leading
	      " will be stripped.

   Extended requests
       .cf filename
	      When used in a diversion, this will  embed  in  the
	      diversion	 an object which, when reread, will cause
	      the contents of filename to be transparently copied
	      through to the output.  In Unix troff, the contents
	      of filename is immediately copied	 through  to  the
	      output  regardless  of  whether  there is a current
	      diversion; this behaviour is so anomalous	 that  it
	      must be considered a bug.

       .ev xx If  xx is not a number, this will switch to a named
	      environment called xx.  The environment  should  be
	      popped with a matching ev request without any argu-
	      ments, just as for numbered environments.	 There is
	      no  limit on the number of named environments; they
	      will be created the first time that they are refer-
	      enced.

       .fp n f1 f2
	      The  fp  request	has  an	 optional third argument.
	      This argument gives the external name of the  font,
	      which  is	 used  for  finding  the font description
	      file.  The second argument gives the internal  name
	      of  the  font which is used to refer to the font in
	      troff after it has been mounted.	If  there  is  no
	      third  argument then the internal name will be used

Groff Version 1.15	   8 March 2000			       14

TROFF(1)						 TROFF(1)

	      as the external name.  This feature allows  you  to
	      use fonts with long names in compatibility mode.

       .ss m n
	      When two arguments are given to the ss request, the
	      second argument gives the sentence space size.   If
	      the  second  argument  is	 not  given, the sentence
	      space size will be the same as the word space size.
	      Like  the word space size, the sentence space is in
	      units of one twelfth of  the  spacewidth	parameter
	      for  the	current	 font.	 Initially  both the word
	      space size and the sentence space size are 12.  The
	      sentence	space  size is used in two circumstances:
	      if the end of a sentence occurs at  the  end  of	a
	      line  in	fill  mode, then both an inter-word space
	      and a sentence space will be added; if  two  spaces
	      follow  the  end	of  a sentence in the middle of a
	      line, then the second  space  will  be  a	 sentence
	      space.   Note that the behaviour of Unix troff will
	      be exactly that exhibited by GNU troff if a  second
	      argument	is never given to the ss request.  In GNU
	      troff, as in Unix troff, you should always follow a
	      sentence with either a newline or two spaces.

       .ta n1 n2...nn T r1 r2...rn
	      Set  tabs	 at positions n1, n2,..., nn and then set
	      tabs  at	nn+r1,	nn+r2,....,  nn+rn  and	 then  at
	      nn+rn+r1,	 nn+rn+r2,...,	nn+rn+rn, and so on.  For
	      example,

		     .ta T .5i

	      will set tabs every half an inch.

   New number registers
       The following read-only registers are available:

       \n[.C] 1 if compatibility mode is in effect, 0  otherwise.

       \n[.cdp]
	      The  depth  of the last character added to the cur-
	      rent 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  cur-
	      rent  environment.  It is positive if the character
	      extends above the baseline.

Groff Version 1.15	   8 March 2000			       15

TROFF(1)						 TROFF(1)

       \n[.csk]
	      The skew of the last character added to the current
	      environment.  The skew of a character is how far to
	      the right of the center of a character  the  center
	      of  an accent over that character should be placed.

       \n[.ev]
	      The name or  number  of  the  current  environment.
	      This is a string-valued register.

       \n[.fam]
	      The  current  font family.  This is a string-valued
	      register.

       \n[.fp]
	      The number of the next free font position.

       \n[.g] Always 1.	 Macros	 should	 use  this  to	determine
	      whether they are running under GNU troff.

       \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 hyphen-
	      ated 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[.in]
	      The indent that applies to the current output line.

       \n[.kern]
	      1 if pairwise kerning is enabled, 0 otherwise.

       \n[.lg]
	      The  current  ligature  mode  (as	 set  by  the  lg
	      request.)

Groff Version 1.15	   8 March 2000			       16

TROFF(1)						 TROFF(1)

       \n[.ll]
	      The  line length that applies to the current output
	      line.

       \n[.lt]
	      The title length as set by the lt request.

       \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 the \n[.trunc] register.

       \n[.pn]
	      The number of the next page: either the  value  set
	      by  a pn request, or the number of the current page
	      plus 1.

       \n[.ps]
	      The current pointsize in scaled points.

       \n[.psr]
	      The last-requested pointsize in scaled points.

       \n[.rj]
	      The number of lines to be right-justified as set by
	      the rj request.

       \n[.sr]
	      The last requested pointsize in points as a decimal
	      fraction.	 This is a string-valued register.

       \n[.tabs]
	      A string representation of the current tab settings
	      suitable	for use as an argument to the ta request.

       \n[.trunc]
	      The amount of vertical space truncated by the  most
	      recently	sprung vertical position trap, or, if the
	      trap was sprung by a ne request, minus  the  amount
	      of  vertical motion produced by the ne request.  In
	      other words, at the point a trap is sprung, it rep-
	      resents  the  difference of what the vertical posi-
	      tion would have been but for the trap, and what the
	      vertical	position actually is.  Useful in conjunc-
	      tion with the \n[.ne] register.

       \n[.ss]
       \n[.sss]
	      These give the values of the parameters set by  the
	      first and second arguments of the ss request.

       \n[.vpt]
	      1	 if vertical position traps are enabled, 0 other-
	      wise.

Groff Version 1.15	   8 March 2000			       17

TROFF(1)						 TROFF(1)

       \n[.warn]
	      The sum of the numbers associated with each of  the
	      currently	 enabled warnings.  The number associated
	      with each warning is listed in the `Warnings'  sub-
	      section.

       \n(.x  The major version number.	 For example, if the ver-
	      sion number is 1.03 then \n(.x will contain 1.

       \n(.y  The minor version number.	 For example, if the ver-
	      sion number is 1.03 then \n(.y will contain 03.

       The following registers are set by the \w escape sequence:

       \n[rst]
       \n[rsb]
	      Like the st and sb registers, but takes account  of
	      the heights and depths of characters.

       \n[ssc]
	      The  amount of horizontal space (possibly negative)
	      that should be added to the last character before a
	      subscript.

       \n[skw]
	      How  far to right of the center of the last charac-
	      ter in the \w argument, the  center  of  an  accent
	      from  a roman font should be placed over that char-
	      acter.

       The following read/write number registers are available:

       \n[systat]
	      The return value of the system() function	 executed
	      by the last sy request.

       \n[slimit]
	      If greater than 0, the maximum number of objects on
	      the input stack.	If less than or equal to 0, there
	      is  no  limit on the number of objects on the input
	      stack.  With no limit, recursion can continue until
	      virtual memory is exhausted.

   Miscellaneous
       Fonts  not  listed  in  the  DESC  file	are automatically
       mounted on the next available font position when they  are
       referenced.   If	 a  font is to be mounted explicitly with
       the fp request on an unused font position,  it  should  be
       mounted	on  the	 first unused font position, which can be
       found in the \n[.fp] register;  although	 troff	does  not
       enforce	this  strictly,	 it  will  not allow a font to be
       mounted at a position whose number is  much  greater  than
       that of any currently used position.

Groff Version 1.15	   8 March 2000			       18

TROFF(1)						 TROFF(1)

       Interpolating  a string does not hide existing macro argu-
       ments.  Thus in a macro, a more efficient way of doing

	      .xx \\$@

       is

	      \\*[xx]\\

       If the font description	file  contains	pairwise  kerning
       information,  characters	 from  that  font will be kerned.
       Kerning between two characters can be inhibited by placing
       a \& between them.

       In  a  string  comparison  in a condition, characters that
       appear at different input levels to  the	 first	delimiter
       character  will	not  be recognised as the second or third
       delimiters.  This applies also to the tl request.  In a \w
       escape  sequence,  a character that appears at a different
       input level to the starting delimiter character	will  not
       be  recognised  as  the closing delimiter character.  When
       decoding a macro argument  that	is  delimited  by  double
       quotes,	a  character  that  appears  at a different input
       level to the starting  delimiter	 character  will  not  be
       recognised as the closing delimiter character.  The imple-
       mentation of \$@ ensures that the double quotes	surround-
       ing  an	argument  will appear the same input level, which
       will be different to  the  input	 level	of  the	 argument
       itself.	In a long escape name ] will not be recognized as
       a closing delimiter except when	it  occurs  at	the  same
       input  level  as the opening ].	In compatibility mode, no
       attention is paid to the input-level.

       There are some new types of condition:

       .if rxxx
	      True if there is a number register named xxx.

       .if dxxx
	      True if there is a  string,  macro,  diversion,  or
	      request named xxx.

       .if cch
	      True  if	there  is a character ch available; ch is
	      either an ASCII character or  a  special	character
	      \(xx  or \[xxx]; the condition will also be true if
	      ch has been defined by the char request.

   Warnings
       The warnings that can be given by troff are  divided  into
       the  following  categories.  The name associated with each
       warning is used by the -w and -W options;  the  number  is
       used by the warn request, and by the .warn register.

Groff Version 1.15	   8 March 2000			       19

TROFF(1)						 TROFF(1)

       char	      1	  Non-existent	 characters.	This   is
			  enabled by default.

       number	      2	  Invalid numeric expressions.	 This  is
			  enabled by default.

       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.

       delim	      8	  Missing or  mismatched  closing  delim-
			  iters.

       el	     16	  Use  of the el request with no matching
			  ie request.

       scale	     32	  Meaningless scaling indicators.

       range	     64	  Out of range arguments.

       syntax	    128	  Dubious syntax in numeric  expressions.

       di	    256	  Use  of  di  or  da without an argument
			  when there is no current diversion.

       mac	    512	  Use of undefined  strings,  macros  and
			  diversions.	When an undefined string,
			  macro or diversion is used, that string
			  is automatically defined as empty.  So,
			  in most cases, at most one warning will
			  be given for each name.

       reg	   1024	  Use	of  undefined  number  registers.
			  When an undefined  number  register  is
			  used,	 that  register	 is automatically
			  defined to have a value of 0.	 a  defi-
			  nition  is  automatically  made  with a
			  value of 0.  So, in most cases, at most
			  one  warning will be given for use of a
			  particular name.

       tab	   2048	  Inappropriate use of a  tab  character.
			  Either  use  of a tab character where a
			  number was  expected,	 or  use  of  tab
			  character  in	 an  unquoted macro argu-
			  ment.

       right-brace 4096	  Use of \} where a number was	expected.

       missing	   8192	  Requests  that are missing non-optional
			  arguments.

       input	  16384	  Illegal input characters.

Groff Version 1.15	   8 March 2000			       20

TROFF(1)						 TROFF(1)

       escape	  32768	  Unrecognized escape sequences.  When an
			  unrecognized escape sequence is encoun-
			  tered, the escape character is ignored.

       space	  65536	  Missing  space  between  a  request  or
			  macro and its argument.   This  warning
			  will	be  given  when an undefined name
			  longer than two characters  is  encoun-
			  tered,  and the first two characters of
			  the name  make  a  defined  name.   The
			  request  or  macro will not be invoked.
			  When this warning is given, no macro is
			  automatically defined.  This is enabled
			  by default.  This  warning  will  never
			  occur in compatibility mode.

       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 do not  occur
			  in ignored text.

       There  are  also names that can be used to refer to groups
       of warnings:

       all    All  warnings  except  di,  mac  and  reg.   It  is
	      intended	that  this  covers  all warnings that are
	      useful with traditional macro packages.

       w      All warnings.

   Incompatibilities
       Long names cause some incompatibilities.	 Unix troff  will
       interpret

	      .dsabcd

       as  defining  a string ab with contents cd.  Normally, GNU
       troff will interpret this as  a	call  of  a  macro  named
       dsabcd.	Also Unix troff will interpret \*[ or \n[ as ref-
       erences to a string or number register called [.	  In  GNU
       troff,  however,	 this will normally be interpreted as the
       start of a long name.  In  compatibility	 mode  GNU  troff
       will  interpret	these  things in the traditional way.  In
       compatibility mode, however, long  names	 are  not  recog-
       nised.	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.

       GNU troff does not allow the use of the	escape	sequences
       \\|\^\&\}\{\(space)\'\`\-\_\!\%\c  in  names  of	 strings,

Groff Version 1.15	   8 March 2000			       21

TROFF(1)						 TROFF(1)

       macros, diversions, number registers,  fonts  or	 environ-
       ments;  Unix  troff  does.   The \A escape sequence may be
       helpful in avoiding  use	 of  these  escape  sequences  in
       names.

       Fractional  pointsizes  cause one noteworthy incompatibil-
       ity.  In Unix troff the ps request ignores  scale  indica-
       tors and so

	      .ps 10u

       will  set the pointsize to 10 points, whereas in GNU troff
       it will set the pointsize to 10 scaled points.

       In GNU troff there is  a	 fundamental  difference  between
       unformatted, input characters, and formatted, output char-
       acters.	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 bd, cs,
       tkf, tr, or fp requests.	 Normally output  characters  are
       constructed  from  input	 characters at the moment immedi-
       ately 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 char-
       acters  and output characters in any combination.  An out-
       put 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.	 For example,

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

       will  print  \\	in  GNU	 troff;	 each pair of input \s is
       turned into one output \ and the resulting output  \s  are
       not interpreted as escape characters when they are reread.
       Unix troff would interpret them as escape characters  when
       they  were  reread  and	would end up printing one \.  The
       correct way to obtain a printable  \  is	 to  use  the  \e
       escape  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 troff and Unix troff.  If you wish for some reason  to
       store  in  a  diversion	an  escape  sequence that will be
       interpreted when the diversion is reread, you  can  either
       use  the	 traditional \!	 transparent output facility, or,
       if this is unsuitable, the new \?  escape sequence.

ENVIRONMENT

Groff Version 1.15	   8 March 2000			       22

TROFF(1)						 TROFF(1)

       GROFF_TMAC_PATH
	      A colon separated list of directories in	which  to
	      search for macro files.

       GROFF_TYPESETTER
	      Default device.

       GROFF_FONT_PATH
	      A	 colon	separated list of directories in which to
	      search  for  the	devname	 directory.   troff  will
	      search in directories given in the -F option before
	      these,	 and	 in	standard      directories
	      (/usr/local/lib/groff_font:/usr/share/groff_font)
	      after these.

FILES
       /usr/share/tmac/troffrc
	      Initialization file

       /usr/share/tmac/tmac.name
	      Macro files

       /usr/share/groff_font/devname/DESC
	      Device description file for device name.

       /usr/share/groff_font/devname/F
	      Font file for font F of device name.

SEE ALSO
       groff(1)	 tbl(1),  pic(1),  eqn(1),  grops(1),  grodvi(1),
       grotty(1),    grohtml(1),   groff_font(5),   groff_out(5),
       groff_char(7)

Groff Version 1.15	   8 March 2000			       23

[top]

List of man pages available for BSDi

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net