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

FreeBSD Manual Pages

  
 
  

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

NAME
       roff - a	survey of the roff typesetting system

DESCRIPTION
       roff  is	the general name for a set of type-setting programs, known un-
       der names like troff, nroff, groff, etc.

       The roff	type-setting system consists of	a formatting  language,	 macro
       packages, preprocessors,	postprocessors for output devices, user	front-
       end programs, and conversion tools.

       The most	common roff system today is the	free  software	implementation
       groff (from `GNU	roff').	 The pre-groff implementations are referred to
       as `classical' (dating back as long as 1973).

       groff is	backward-compatible to its classical ancestors,	but  has  many
       extensions, and is still	evolving.  As it is available for almost every
       computer	system it is the de-facto roff standard	today.

       In spite	of its age, roff is in wide use	today, e.g., the manual	 pages
       on  UNIX	 systems (man-pages) are written in roff.  The roff output for
       text devices is still unmatched,	and its	graphical output has the  same
       quality as the other free type-setting programs and is better than some
       of the commercial systems.

       This document gives only	an overview and	provides pointers  to  further
       documentation.

       This document is	not maintained and might be out	of date.  For the real
       documentation refer to the groff	info file that contains	the  detailed,
       actual and concise reference information.

FORMATTING LANGUAGE
       There  are  three  terms	that refer to the language of the roff system.
       The term	troff language is used when the	classical aspects of roff  are
       stressed,  the term groff language includes the GNU extensions, whereas
       roff language is	the general term.

       The main	source of documentation	for all	aspects	of the groff  language
       is  the	groff  info  file.  The	manual page groff(7) gives a short de-
       scription of all	predefined language elements.

       Documents using roff are	normal text files decorated by formatting ele-
       ments.  It is very easy to write	high-quality documents by using	one of
       the macro packages.  These are like high-level  programming  languages,
       while the bare roff language compares to	a low-level language like C or
       assembler.

       The roff	language is a full programming	language  providing  low-level
       requests,  definition  of  macros,  escape sequences, string variables,
       number or size registers, and C-like flow controls.

       Some clarification on the language elements seems to  be	 wanted.   Re-
       quests  are  basic formatting commands defined by programming languages
       like C, C++, etc., whereas macros  are  formatting  commands  that  are
       written in the roff language.  A	document writer	will not note any dif-
       ference in usage	for requests or	macros,	both are written on a line  on
       their  own  starting  with  a  dot `.'. But the user may	define her own
       macros if desired.

       Escape sequences	are in-line elements starting with  a  backslash  `\'.
       They are	used to	implement various features, including the insertion of
       non-ASCII characters with \(, the content of strings with \* and	regis-
       ter  variables with \n, font changes with \f, in-line comments with \",
       the escaping of special control characters like \\, and many other fea-
       tures.

FORMATTERS
       Formatters are the front-end programs that analyze a groff document and
       translate it into a form	that is	suitable for a	special	 device.   The
       traditional  roff  had two formatters, nroff for	text devices and troff
       for graphical devices.

       These programs still exist in the  groff	 implementation,  but  usually
       they  are  accessed  through a program called groff.  This combined and
       extended	the old	functionality into a single program.  It has many com-
       mand-line options, most of them herited from troff.  To ease the	option
       jungle, the user-friendly utility grog (from `groff  guess')  was  cre-
       ated.   It  tries  to guess from	the document which arguments should be
       used and	displays a suitable command line.  Though not  being  perfect,
       it is a good starting point.

PREPROCESSORS
       The classical preprocessors that	are still available in groff.

	      eqn    for including mathematical	equations.
	      grap   for  constructing	graphical  elements (this preprocessor
		     doesn't come with groff; it is an extra package).
	      grn    for including gremlin pictures.
	      pic    for creating diagrams.
	      refer  for bibliographic references.
	      soelim for including other roff files.
	      tbl    for rectangular tables.

       Each of these preprocessors defines its own language that is translated
       into  roff  code	 when  run through the preprocessor program.  So parts
       written in these	languages may be  included  within  a  roff  document.
       Such an enhanced	document is run	through	one or more corresponding pre-
       processors before it is fed into	the actual formatter.

       The preprocessor	programs extract and transform the document parts  de-
       termined	 for  them.  They can be called	either in a UNIX pipeline with
       their program name or automatically with	a groff	option.

			    +-------------+--------------+
			    |preprocessor | groff option |
			    +-------------+--------------+
			    |	 eqn	  |	 -e	 |
			    |	 grap	  |	 -G	 |
			    |	 grn	  |	 -g	 |
			    |	 pic	  |	 -p	 |
			    |	refer	  |	 -R	 |
			    |	 tbl	  |	 -r	 |
			    |	soelim	  |	 -s	 |
			    +-------------+--------------+
MACRO PACKAGES
       Macro packages are collections of macros	that are suitable to format  a
       special	kind of	documents in a convenient way.	This greatly eases the
       usage of	roff.  The macro definitions of	a package are kept in  a  file
       called  name.tmac  (or  tmac.name) where	name is	the internal roff name
       for this	package.  All tmac files are stored in a single	or few	direc-
       tories at standard positions.

       A  macro	package	that is	used in	a document is specified	by the command
       line option -m for the formatter	like troff -m name or  groff -m	 name.
       General	details	on the naming of macro packages	and their placement is
       found in	groff_tmac(5).

       Famous classical	macro packages are man,	mandoc,	and  mdoc  for	manual
       pages  and  me,	ms,  and mm for	books, articles, and letters.  Besides
       these collections, groff	provides an increasing	number	of  new	 macro
       packages	 for  various applications, for	example	integration of or con-
       version into other file formats.

FILE NAME EXTENSIONS
       Manual pages (man-pages)	take the section number	as a file name	exten-
       sion,  e.g., the	filename for this document is roff.7, i.e., it is kept
       in section 7 of the man-pages.

       The classical macro packages take the package  name  as	an  extension,
       e.g.   file.me  for  a document using the me macro package, file.mm for
       mm, file.ms for ms, file.pic for	pic files, etc.

EDITING
       Most text editors provide support for  editing  documents  using	 roff.
       Especially useful is the	nroff-mode in all flavors of the Emacs editor.

ENVIRONMENT
       GROFF_TMAC_PATH
	      A	 colon	separated  list	 of directories	in which to search for
	      macro files, see groff_tmac(5).

       GROFF_TYPESETTER
	      Default device.

       GROFF_FONT_PATH
	      A	colon separated	list of	directories in which to	search for the
	      devname directory.  troff	will first search in directories given
	      with the -F command line option, then  in	 GROFF_FONT_PATH,  and
	      finally in the standard directories (/usr/share/groff_font).

FILES
       By  default,  groff installs all	of its data files in subdirectories of
       /usr/share/groff_font and in /usr/share/tmac (except wrapper files  for
       system-specific	macro  packages	 which	will  be  in /usr/share/tmac).
       These locations might vary for different	systems.   In  the  following,
       the   former   is  referred  to	as  _groff_font_dir_,  the  latter  as
       _groff_macro_dir_.

       _groff_macro_dir_/troffrc
	      Initialization file for troff.

       _groff_macro_dir_/name.tmac
       _groff_macro_dir_/tmac.name
	      Macro files.

       _groff_font_dir_/devname/DESC
	      Device description file for device name.

       _groff_font_dir_/devname/F
	      Font file	for font F of device name.

       Finally,	a local	macro directory	/usr/share/tmac	is provided for	 site-
       specific	 macros	 and  packages;	by default, it will be searched	before
       the main	macro directory.

BUGS
       The groff documentation is in evolution at the moment.  It is  possible
       that  small inconsistencies between different documents exist temporar-
       ily.

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

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

	      _http://www.gnu.org/copyleft/fdl.html_.

SEE ALSO
       The main	source of information is the groff info(1) file.

       The  predefined	elements  of the groff language	are also documented in
       the manual page groff(7).

       Formatters  and	their  wrappers:  groff(1),  grog(1),  nroff(1),   and
       troff(1).

       Postprocessors	for   the   output   devices:  grodvi(1),  grohtml(1),
       grolbp(1), grolj4(1), grops(1), and grotty(1).

       Standard	preprocessors: eqn(1), grn(1), grap(1),	pic(1),	refer(1), soe-
       lim(1), and tbl(1).

       The  man	 pages for macro packages include groff_tmac(5), groff_man(7),
       groff_markup(7),	 groff_mdoc(7),	 groff_mdoc.samples(7),	  groff_me(7),
       groff_mm(7), groff_mmroff(7), and groff_ms(7).

       The  following  utilities  are  available:  addftinfo(1),  afmtodif(1),
       hpftodit(1),  indxbib(1),  lookbib(1),  pfbtops(1),  tfmtodit(1),   and
       gxditview(1).

       For   details  on  the  GNU  implementation  of	the  roff  system  see
       groff_char(7), groff_font(7), groff_out(7), and the file	README in  the
       main  directory	of the groff source distribution.  These also give de-
       tails on	how to contact or join the groff developer group.

       Many classical documents	are still available on-line.   Especially  in-
       formative are the original Bell Labs proceedings	for the	old, free UNIX
       7 found at http://cm.bell-labs.com/cm/cs/cstr.html and  the  collection
       of the late Richard S. Stevens at http://www.kohala.com/start/troff/.

Groff Version 1.17.2		 6 August 2001			       ROFF(7)

NAME | DESCRIPTION | FORMATTING LANGUAGE | FORMATTERS | PREPROCESSORS | MACRO PACKAGES | FILE NAME EXTENSIONS | EDITING | ENVIRONMENT | FILES | BUGS | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=roff&sektion=7&manpath=FreeBSD+4.7-RELEASE>

home | help