* man/roff.man: Revised.

* src/roff/groff/groff.man: Replace man page references with a
pointer to roff.man.

* man/roff.man: Completely rewritten.

* Makefile.sim, groff_mm.man, groff_mmse.man: Minor fixes.
* mmroff.man: This is a section 1 man page.
Minor fixes.
* Makefile.sub: Install mmroff.man in section 1.

9 files changed, 1070 insertions, 390 deletions

diff --git a/ChangeLog b/ChangeLog
index 1a392a95..4fdd74c4 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2001-12-09  Werner LEMBERG  <wl@gnu.org>
+
+	* man/roff.man: Revised.
+	* src/roff/groff/groff.man: Replace man page references with a
+	pointer to roff.man.
+
+2001-12-09  Bernd Warken  <bwarken@mayn.de>
+
+	* man/roff.man: Completely rewritten.
+
 2001-12-06  Ralph Corderoy  <ralph@inputplus.demon.co.uk>
 
 	* src/preproc/eqn/main.cc (inline_equation): Improve error message.
@@ -119,8 +129,8 @@
 
 2001-11-28  Werner LEMBERG  <wl@gnu.org>
 
-	* tmac/an-old.tmac, tmac/doc.tmac, contrib/mm/m.tmac: Assure that
-	the macro package is loaded only once.
+	* tmac/an-old.tmac, tmac/doc.tmac: Assure that the macro package is
+	loaded only once.
 
 	* tmac/groff_man.man: Minor cosmetic fix.
 
@@ -507,14 +517,14 @@
 
 	* src/roff/troff/troff.man: Remove superfluous line.
 
-	* tmac/s.tmac, contrib/mm/m.tmac: Enable all warnings only if no -W
-	or -w option is given on the command line (or rather, if only the
-	default warnings are set).
+	* tmac/s.tmac: Enable all warnings only if no -W or -w option is
+	given on the command line (or rather, if only the default warnings
+	are set).
 
 2001-09-03  Werner LEMBERG  <wl@gnu.org>
 
-	* contrib/mm/groff_mm.man, man/groff.man, src/preproc/eqn/eqn.man,
-	tmac/groff_mdoc.man: Don't use .ne for TTY devices.
+	* man/groff.man, src/preproc/eqn/eqn.man, tmac/groff_mdoc.man: Don't
+	use .ne for TTY devices.
 
 2001-08-31  Werner LEMBERG  <wl@gnu.org>
 
@@ -690,16 +700,9 @@
 
 2001-07-26  Werner LEMBERG  <wl@gnu.org>
 
-	* contrib/mm/groff_mm.man: Start always a new line after end of
-	sentence.  Add some compatibility info to the HF variable.
-
 	* src/preproc/refer/refer.cc: Include `lib.h'.
 	* src/devices/grohtml/post-html.cc: Ditto.
 
-2001-07-26  Larry Jones  <larry.jones@sdrc.com>
-
-	* contrib/mm/m.tmac: Fix initialization of Hps1 and Hps2.
-
 2001-07-25  Gaius Mulley  <gaius@glam.ac.uk>
 
 	* aclocal.m4 (GROFF_PAGE): Add `AC_DEFINE(PAGEA4)'.
@@ -1080,10 +1083,6 @@ Version 1.17.1 released
 
 	* src/roff/troff/input.cc (read_size): Fix special case `\s0'.
 
-2001-05-16  Bruce Lilly  <blilly@erols.com>
-
-	* contrib/mm/m.tmac (TH): Fix incorrect error message.
-
 2001-05-16  Werner LEMBERG  <wl@gnu.org>
 
 	* src/roff/troff/input.cc (read_size): Emit warning if value becomes
@@ -1438,10 +1437,6 @@ Version 1.17 released
 	* src/devices/grohtml/html-text.cc (issue_table_begin): Set
 	`frame=void', not `frame=none'.  Add `border=0'.
 
-2001-04-12  Ruslan Ermilov  <ru@FreeBSD.org>
-
-	* contrib/mm/groff_mm.man: Fixing some typos.
-
 2001-04-12  Werner LEMBERG  <wl@gnu.org>
 
 	* PROBLEMS: Add some words on how to avoid wrapper macros.
@@ -2925,11 +2920,6 @@ Version 1.17 released
 
 	* src/roff/troff/TODO: Updated.
 
-2000-08-28  Bruno Haible  <haible@clisp.cons.org>
-
-	* contrib/mm/Makefile.sub: New target 'all', makes all prerequisites
-	of 'install'.
-
 2000-08-25  Werner LEMBERG  <wl@gnu.org>
 
 	* doc/groff.texinfo: Fix comment how to compile the DVI file.
@@ -3838,7 +3828,7 @@ Version 1.16 released
 
 2000-03-07  OKAZAKI Tetsurou  <okazaki@be.to>
 
-	* Makefile.in, contrib/mm/Makefile.sub, src/preproc/eqn/Makefile.sub,
+	* Makefile.in, Makefile.sub, src/preproc/eqn/Makefile.sub,
 	src/roff/groff/Makefile.sub, src/roff/nroff/Makefile.sub,
 	src/utils/afmtodit/Makefile.sub: Use $(INSTALL_SCRIPT) for script
 	files.
diff --git a/contrib/mm/ChangeLog b/contrib/mm/ChangeLog
index ab3ed838..d3c2e674 100644
--- a/contrib/mm/ChangeLog
+++ b/contrib/mm/ChangeLog
@@ -1,9 +1,47 @@
+Sun Dec 9 00:00:00 2001 Werner LEMBERG  (wl@gnu.org)
+
+	* Makefile.sim, groff_mm.man, groff_mmse.man: Minor fixes.
+	* mmroff.man: This is a section 1 man page.
+	Minor fixes.
+	* Makefile.sub: Install mmroff.man in section 1.
+
+Wed Nov 28 00:00:00 2001 Werner LEMBERG (wl@gnu.org)
+
+	* m.tmac: Assure that the macro package is loaded only once.
+
+Wed Sep 5 00:00:00 2001 Werner LEMBERG (wl@gnu.org)
+
+	* m.tmac: Enable all warnings only if no -W or -w option is given on
+	  the command line (or rather, if only the default warnings are
+	  set).
+
+Mon Sep 3 00:00:00 2001 Werner LEMBERG (wl@gnu.org)
+
+	* groff_mm.man: Don't use .ne for TTY devices.
+
+Thu Jul 26 00:00:00 2001 Werner LEMBERG (wl@gnu.org)
+
+	* groff_mm.man: Start always a new line after end of sentence.  Add
+	  some compatibility info to the HF variable.
+
+Thu Jul 26 00:00:00 2001 Larry Jones (larry.jones@sdrc.com)
+
+	* m.tmac: Fix initialization of Hps1 and Hps2.
+
+Wed May 16 00:00:00 2001 Bruce Lilly (blilly@erols.com)
+
+	* m.tmac (TH): Fix incorrect error message.
+
+Thu Apr 12 00:00:00 2001 Ruslan Ermilov (ru@FreeBSD.org)
+
+	* groff_mm.man: Fixing some typos.
+
 Mon Mar 5 09:30:18 2001 Jörgen Hägg (jh@axis.com)
 
 	* S didn't reset to default point size
 	* (dummy line to force cvs update...)
 
-Sat Jan 06 10:30:00 2001 Werner Lemberg (wl@gnu.org)
+Sat Jan 06 10:30:00 2001 Werner LEMBERG (wl@gnu.org)
 
 	* Fixed assignment of page offset given as a command line argument.
 
@@ -18,6 +56,11 @@ Thu Sep 14 05:52:48 2000 Jörgen Hägg (jh@axis.com)
 	  understand why the e-mail address was supposed to be
 	  'jh at axis.com' in the Changelog. :-)
 
+Mon Aug 28 00:00:00 2000 Bruno Haible (haible at clisp.cons.org)
+
+	* Makefile.sub: New target 'all', makes all prerequisites of
+	'install'.
+
 Thu Sep 7 06:17:42 2000 Jörgen Hägg (jh at axis.com)
 
 	* version 2.0
@@ -34,6 +77,10 @@ Sun Jun 4 21:39:00 2000 Kaneda Hiroshi (vanitas at ma3.seikyou.ne.jp)
 
 	* Fixing a lot of typos in groff_mm.man
 
+Tue Mar 7 00:00:00 2000 OKAZAKI Tetsurou (okazaki at be.to)
+
+	* Makefile.sub: Use $(INSTALL_SCRIPT) for script files.
+
 Sun Jan 30 22:52:20 2000 Jörgen Hägg (jh at axis.com)
 
 	* version 1.34
diff --git a/contrib/mm/Makefile.sim b/contrib/mm/Makefile.sim
index e1d4a142..6f789185 100644
--- a/contrib/mm/Makefile.sim
+++ b/contrib/mm/Makefile.sim
@@ -1,5 +1,5 @@
 #
-# $Id: Makefile.sim,v 2.1 2000/11/17 04:26:02 jhaegg Exp $
+# $Id: Makefile.sim,v 2.2 2001/12/09 12:15:09 wlemb Exp $
 #
 # To install mgm separately as gm.tmac:
 # make -f Makefile.sub tmacdir=/usr/local/lib/groff/tmac srcdir=. \
@@ -33,9 +33,9 @@ install: groff_mm.n groff_mmse.n
 	$(MAKE) -f Makefile.sub tmacdir=$(tmacdir) srcdir=$(srcdir) \
 		INSTALL_DATA='$(install)' tmac_m=$(tmac_m) install
 
- uninstall: groff_mm.n groff_mmse.n
-      $(MAKE) -f Makefile.sub tmacdir=$(tmacdir) srcdir=$(srcdir) \
-              INSTALL_DATA='$(install)' tmac_m=$(tmac_m) uninstall_sub
+uninstall: groff_mm.n groff_mmse.n
+	$(MAKE) -f Makefile.sub tmacdir=$(tmacdir) srcdir=$(srcdir) \
+		INSTALL_DATA='$(install)' tmac_m=$(tmac_m) uninstall_sub
 
 
 .man.n:
diff --git a/contrib/mm/Makefile.sub b/contrib/mm/Makefile.sub
index 87cf0504..d5dc9c0e 100644
--- a/contrib/mm/Makefile.sub
+++ b/contrib/mm/Makefile.sub
@@ -1,14 +1,15 @@
 #
-# $Id: Makefile.sub,v 2.1 2000/11/17 04:26:02 jhaegg Exp $
+# $Id: Makefile.sub,v 2.2 2001/12/09 12:15:09 wlemb Exp $
 #
 PROG=mmroff
+MAN1=\
+  mmroff.n
 MAN7=\
   groff_mm.n \
-  groff_mmse.n \
-  mmroff.n
+  groff_mmse.n
 FILES=0.MT 5.MT 4.MT ms.cov se_ms.cov 
 # Local configuration files with default values.
-LOCALE = locale se_locale
+LOCALE=locale se_locale
 CLEANADD=temp
 
 all: mmroff
@@ -32,7 +33,8 @@ install_m:
 	$(INSTALL_DATA) $(srcdir)/m.tmac $(tmacdir)/$(tmac_m_prefix)m.tmac
 	@sed -e "s;^.mso m.tmac;.mso $(tmac_m_prefix)m.tmac;g" \
 		$(srcdir)/mse.tmac > $(tmacdir)/$(tmac_m_prefix)mse.tmac
-install_mmroff : mmroff
+
+install_mmroff: mmroff
 	-test -d $(bindir) || $(mkinstalldirs) $(bindir)
 	-rm -f $(bindir)/mmroff
 	$(INSTALL_SCRIPT) mmroff $(bindir)/mmroff
@@ -42,7 +44,6 @@ mmroff: mmroff.pl
 	-sed -e 's;/usr/bin/perl;$(PERLPATH);' $(srcdir)/mmroff.pl >$@
 	-chmod +x $@
 
-
 uninstall_sub:
 	-for f in $(FILES); do rm -f $(tmacdir)/mm/$$f; done
 	-for f in $(LOCALE); do \
diff --git a/contrib/mm/groff_mm.man b/contrib/mm/groff_mm.man
index 21a9ba75..7085867d 100644
--- a/contrib/mm/groff_mm.man
+++ b/contrib/mm/groff_mm.man
@@ -1,5 +1,5 @@
 .\"
-.\" $Id: groff_mm.man,v 2.4 2001/09/04 04:33:32 wlemb Exp $
+.\" $Id: groff_mm.man,v 2.5 2001/12/09 12:15:09 wlemb Exp $
 .\"
 .de T2
 .if t .ne 2v
@@ -2075,8 +2075,7 @@ Jörgen Hägg, Lund, Sweden <jh@axis.se>.
 .BR @g@pic (@MAN1EXT@),
 .BR @g@eqn (@MAN1EXT@)
 .br
-.BR mm (@MAN7EXT@)
-.BR m@TMAC_M_PREFIX@mse (@MAN7EXT@)
+.BR groff_mmse (@MAN7EXT@)
 .
 .\" Local Variables:
 .\" mode: nroff
diff --git a/contrib/mm/groff_mmse.man b/contrib/mm/groff_mmse.man
index f915b8e7..511eac58 100644
--- a/contrib/mm/groff_mmse.man
+++ b/contrib/mm/groff_mmse.man
@@ -1,5 +1,5 @@
 .\"
-.\" $Id: groff_mmse.man,v 2.1 2001/06/27 12:47:16 wlemb Exp $
+.\" $Id: groff_mmse.man,v 2.2 2001/12/09 12:15:09 wlemb Exp $
 .\" Skrivet av Jörgen Hägg, Lund, Sverige
 .\"
 .TH GROFF_MMSE @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
@@ -79,7 +79,7 @@ Jörgen Hägg, Lund, Sweden <Jorgen.Hagg@axis.se>
 .BR @g@pic (@MAN1EXT@),
 .BR @g@eqn (@MAN1EXT@)
 .br
-.BR m@TMAC_M_PREFIX@m (@MAN7EXT@)
+.BR groff_mm (@MAN7EXT@)
 .
 .\" Local Variables:
 .\" mode: nroff
diff --git a/contrib/mm/mmroff.man b/contrib/mm/mmroff.man
index f128ce49..a891ff5e 100644
--- a/contrib/mm/mmroff.man
+++ b/contrib/mm/mmroff.man
@@ -1,7 +1,7 @@
 .\"
-.\" $Id: mmroff.man,v 2.1 2001/06/27 12:47:16 wlemb Exp $
+.\" $Id: mmroff.man,v 2.2 2001/12/09 12:15:09 wlemb Exp $
 .\"
-.TH MMROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
+.TH MMROFF @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
 .SH NAME
 mmroff \- reference preprocessor
 .SH SYNOPSIS
@@ -43,9 +43,6 @@ Jörgen Hägg, Lund, Sweden <jh@axis.se>.
 .BR @g@tbl (@MAN1EXT@),
 .BR @g@pic (@MAN1EXT@),
 .BR @g@eqn (@MAN1EXT@)
-.br
-.BR mm (@MAN7EXT@)
-.BR m@TMAC_M_PREFIX@mse (@MAN7EXT@)
 .
 .\" Local Variables:
 .\" mode: nroff
diff --git a/man/roff.man b/man/roff.man
index a4c636b4..2550d8a5 100644
--- a/man/roff.man
+++ b/man/roff.man
@@ -1,11 +1,13 @@
-'\" t
 .ig
 roff.man
 
+Last update: 23 nov 2001
+
 This file is part of groff, the GNU roff type-setting system.
 
 Copyright (C) 2000, 2001 Free Software Foundation, Inc.
 written by Bernd Warken <bwarken@mayn.de>
+maintained by Werner Lemberg <wl@gnu.org>
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.1 or
@@ -21,301 +23,741 @@ FDL in the main directory of the groff source package.
 .\" Setup
 .\" --------------------------------------------------------------------
 .
+.mso www.tmac
+.
 .if n \{\
 .  mso tty-char.tmac
 .  ftr CR R
 .  ftr CI I
 .  ftr CB B
 .\}
+.if '\*[.T]'dvi' \{\
+.  ftr CB CW
+.\}
 .
-.\" text lines in macro definitions or bracketed sections \{...\}
-.de text
-.  if 1 \&\\$*\&
-..
+.ds backslash \(rs\"
+.ds dquote ""\"
+.ds comment \*[backslash]\*[dquote]\"
 .
-.de option
-.  ds @tmp@ \f(CB\\$1\fP
-.  shift 1
-.  text \\*[@tmp@]\\$*
-.  rm @tmp@
-..
+.\" Begin of macro definitions
+.eo
 .
-.de 'char
-.  ds @tmp@ `\f(CB\\$1\fP'
+.\"ig igURL
+.if d@URL \
+.  rm @URL
+.als @URL URL
+.rm URL
+.de URL
+.  ds @arg1 "\$1
 .  shift
-.  text \\*[@tmp@]\\$*
-.  rm @tmp@
+.  @URL "\fI\*[@arg1]\fP" \$@
+.  rm @arg1
+.\"igURL
+..
+.de argname
+.  ds @arg1 \$1
+.  shift 1
+.  nop \fI\*[@arg1]\fP\$*
+.  rm @arg1
 ..
-.
 .de esc
-.  ds @tmp@ \f(CB\e\\$1\fP
+.  ds @arg1 \$1
 .  shift
-.  text \\*[@tmp@]\\$*
-.  rm @tmp@
+.  nop \fB\*[backslash]\*[@arg1]\fP\$*
+.  rm @arg1
 ..
-.
-.de argname
-.  ds @tmp@ \f(CI\\$1\fP
+.de option
+.  ds @arg1 \$1
 .  shift 1
-.  text \\*[@tmp@]\\$*
-.  rm @tmp@
+.  nop \fB\*[@arg1]\fP\$*
+.  rm @arg1
 ..
-.
 .de prefixednumber
-.  ds @tmp@ \&\\$1\ \f(CR\\$2\fP
+.  ds @arg1 \$1
+.  ds @arg2 \$2
 .  shift 2
-.  text \\*[@tmp@]\\$*
-.  rm @tmp@
+.  nop \*[@arg1]\ \fR\*[@arg2]\fP\$*
+.  rm @arg1
+.  rm @arg2
 ..
-.
-.de TQ
+.de quoted_char
+.  ds @arg1 \$1
+.  shift
+.  nop `\fB\*[@arg1]\fP'\$*
+.  rm @arg1
+..
+.de TP+
 .br
 .ns
-.TP \\$1
+.TP \$1
 ..
+.ec
+.\" End of macro definitions
+.
 .
 .\" --------------------------------------------------------------------
 .\" Title
 .\" --------------------------------------------------------------------
+.
 .TH ROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
 .SH NAME
 roff \- a survey of the roff typesetting system
+.
+.
 .\" --------------------------------------------------------------------
 .SH DESCRIPTION
 .\" --------------------------------------------------------------------
+.
 .I roff
 is the general name for a set of type-setting programs, known under
 names like
 .IR troff ,
 .IR nroff ,
+.IR ditroff ,
 .IR groff ,
 etc.
-.LP
-The roff type-setting system consists of a formatting language, macro
-packages, preprocessors, postprocessors for output devices, user
-front-end programs, and conversion tools.
-.LP
+.
+A roff type-setting system consists of an extensible text formatting
+language and a set of front-end programs for printing and converting
+to other text formats.
+.
+.P
 The most common roff system today is the free software implementation
+GNU roff,
+.IR groff .
+.
+The pre-groff implementations are referred to as
+.I classical
+(dating back as long as 1973).
+.
+.P
 .I groff
-(from `GNU\ roff').
-The pre-groff implementations are referred to as `classical' (dating
-back as long as 1973).
-.LP
+implements the look-and-feel and functionality of its classical
+ancestors, but has many extensions.
+.
+As
 .I 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.
-.LP
+is available for almost every computer system it is the de-facto roff
+standard today.
+.
+.P
 In spite of its age, roff is in wide use today, e.g., the manual pages
 on UNIX systems
-.RI ( man-pages )
-are written in roff.
+.RI ( man-pages ),
+many software books, system documentation, standards, and corporate
+documents 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.
-.LP
+.P
 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.
-.\" --------------------------------------------------------------------
-.SH "FORMATTING LANGUAGE"
-.\" --------------------------------------------------------------------
-There are three terms that refer to the language of the
-.I roff
-system.
+documentation, cf. section
+.BR "SEE ALSO" .
+.
+The full documentation of the
+.I groff
+system is found in the
+.I groff info
+.IR file .
+.
 The term
-.I troff language
-is used when the classical aspects of
 .I roff
-are stressed, the term
-.I groff language
-includes the GNU extensions, whereas
-.I roff language
-is the general term.
-.LP
-The main source of documentation for all aspects of the
-.I groff language
-is the groff info file.  The manual page
-.BR groff (@MAN7EXT@)
-gives a short description of all predefined language elements.
-.LP
-Documents using roff are normal text files decorated by formatting
-elements.
-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.
-.LP
-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.
-.ig /
-In the 1980s, it was even possible to write the common utilities for
-system administration by only using troff.
-There were contests on writing the most unreadable program fake by
-exclusively using troff.
-Because of security impacts, these dangerous features were removed in
-.IR groff .
-./
-.LP
-Some clarification on the language elements seems to be wanted.
-Requests 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 difference in usage for requests or
-macros, both are written on a line on their own starting with a dot
-.'char . .
-But the user may define her own macros if desired.
-.LP
-Escape sequences are in-line elements starting with a backslash
-.'char \e .
-They are used to implement various features, including the insertion of
-non-ASCII characters with
-.esc ( ,
-the content of strings with
-.esc *
-and register variables with
-.esc n ,
-font changes with
-.esc f ,
-in-line comments with
-.esc \(dq ,
-the escaping of special control characters like
-.esc \e ,
-and many other features.
+relates to elements common to both the classical and the modern
+implementations, while
+.I groff
+includes the extensions as well.
+.
+.
 .\" --------------------------------------------------------------------
-.SH FORMATTERS
+.SH "HISTORY"
 .\" --------------------------------------------------------------------
-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
+.
+The
 .I roff
-had two formatters,
-.B nroff
-for text devices and
+text processing system has a very long history, dating back to the
+1960s.
+.
+The roff system itself is intimately connected to the Unix operating
+system, but roff had roots in the earlier operating systems CTSS and
+Multics.
+.
+.P
+.I roff
+evolved from its predecessor
+.I runoff
+written by
+.I Jerry Saltzer
+on the
+.I CTSS
+operating system
+.RI ( "Compatible Time Sharing System" )
+in 1961, which was further developed into the famous Unix predecessor
+operating system
+.URL "Multics" http://www.multicians.org ,
+available from 1963.
+.
+Both operating systems could only be run on very expensive computers
+at that time, so they were mostly used in research and for official
+and military tasks.
+.
+.P
+The possibilities of the
+.I runoff
+program were quite limited as compared to roff.
+.
+Only text output was needed in the 1960s.
+.
+This could be implemented by a set of requests of length 2, many of
+which are still identically used in roff.
+.
+The runoff program was first written in
+.IR PL/1 ,
+later on in
+.IR BCPL ,
+the grandmother of the
+.I C
+programming language.
+.
+In the Multics operating system, the help system was handled by
+runoff, similar to roff's task on the Unix manual pages.
+.
+There are still documents written in the runoff language, for examples
+see Saltzer's homepage (follow the links on the Multics web page).
+.
+.P
+In the 1970s, the Multics off-spring
+.I Unix
+became more and more popular because it could be run on affordable
+machines and was free at that time.
+.
+At MIT, there was a need to drive the Wang
+.I Graphic Systems CAT
+typesetter, a graphical output device from a PDP-11 computer running
+Unix.
+.
+As runoff was too limited for this task it was further developed into
+a more powerful text formatting system by
+.IR "Josef F. Osanna" ,
+a main developer of Multics and runoff ports.
+.
+This was called
+.IR roff ,
+a short form for
+.IR runoff .
+.
+The first version was written in the PDP-11 assembly language and
+released in 1973.
+.
+.I Brian Kernighan
+joined the roff development by rewriting it in the C programming
+language.
+.
+The C version was released in 1975.
+.
+.P
+This first roff system could produce output for only 2 devices:
 .B troff
-for graphical devices.
-.LP
-These programs still exist in the
+.RI ( "typesetter roff" )
+had a graphical output for the
+.I CAT
+typesetter as its only device, while
+.B nroff
+produced text output suitable for terminals or line printers.
+.
+.P
+The syntax of the formatting language of the
+.BR nroff / troff
+programs was documented in the famous
+.IR "Troff User's Manual [CSTR #54]" ,
+first published in 1976, with further revisions up to 1992 by Kernighan.
+.
+The system described therein is referred to as the
+.IR "classical troff" .
+All later
+.I roff
+systems tried to establish compatibility with this specification.
+.
+.P
+After Osanna had died in 1977 by a heart-attack at the age of about 50
+Kernighan went on with developping troff.
+.
+The next milestone was to equip troff with a general interface to
+support more devices, the intermediate output format and the
+postprocessor system.
+.
+This completed the structure of a
+.I "roff system"
+as it is still in use today, see section
+.IR "PARTS OF A ROFF SYSTEM" .
+.
+In 1979, these novelties were described in the paper
+.IR "[CSTR #97]" .
+This new troff version is the basis for all existing newer troff
+systems, including
+.IR groff .
+.
+.P
+A major catastrophy occurred when the free Unix 7 was commercialized.
+.
+A whole bunch of commercial operating systems emerged, fighting each
+other with incompatibilities.
+.
+That's why there are now many different roff systems.
+.
+All of them used Osanna/Kernighan's free source code and his troff
+papers as their main documentation, but sold them together with
+"their" system \(em with only minor modifications.
+.
+Though most commercial roff systems added incompatible extensions, all
+of them try to achieve compatibility with the original, free troff.
+.
+Some of these roff implementations were renamed into
+.BR ditroff (@MAN1EXT@),
+originating from
+.IR "device independent troff" .
+This name is an exaggeration.
+.
+.P
+As a counter-measure to the galopping commercialization, more and more
+free software projects emerged during the 1980s and 1990s.
+.
+The most important roff projects was the GNU port of troff, created by
+James Clark.
+.
+It was called
 .I groff
-implementation, but usually they are accessed through a program called
-.BR groff .
-This combined and extended the old functionality into a single program.
-It has many command-line options, most of them herited from
-.BR troff .
-To ease the option jungle, the user-friendly utility
-.B grog
-(from `groff guess') was created.
-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.
-.\" --------------------------------------------------------------------
-.SH PREPROCESSORS
-.\" --------------------------------------------------------------------
-The classical preprocessors that are still available in groff.
+.RI ( "GNU roff" ).
+.
+The groff system is actively developed.
+.
+Though being compatible with the classical troff, many extensions were
+added that greatly simplify roff programming.
+.
+It is the first roff system that is available on almost all operating
+systems \(em and it is free.
+.
+This makes groff the de-facto roff standard today.
+.
+.
+.\" --------------------------------------------------------------------
+.SH "USING ROFF"
+.\" --------------------------------------------------------------------
+.
+Most people won't even notice that they are actually using roff.
+.
+When you read a Unix manual page roff is working in the background.
+.
+But using roff explicitly isn't difficult either.
+.
+.P
+Some roff implementations provide a wrapper program that makes
+direct calling of the roff system easy.
+.
+For example, the GNU roff program
+.BR groff (@MAN1EXT@)
+has options for automatically calling preprocessors and a
+postprocessor; the program
+.BR grog (@MAN1EXT@)
+even tries to guess from the document which arguments should be used
+for a run of groff.
+.
+.P
+Note that the GNU versions of troff and nroff sometimes have a prefix in
+its name to distinguish them from the system troff and nroff in case
+both are installed.
+.
+Usually, the prefix is `g'; for example, GNU troff is then available as
+gtroff.
+.
+On this platform,
+.ie '@g@'' no prefix is used.
+.el the prefix is `@g@'.
+.
+The wrapper program groff never changes its name.
+.
+.P
+Arbitrary roff documents can be viewed with a native roff viewer
+called
+.BR xditview (@MAN1EXT@),
+a standard program of the
+.BR X (@MAN7EXT@)
+window distribution.
+.
+The groff distribution provides an improved version of xditview called
+.BR gxditview (@MAN1EXT@).
+.
+.
+.\" --------------------------------------------------------------------
+.SS "The roff Pipe"
+.\" --------------------------------------------------------------------
+.
+Each roff system consists of preprocessors, roff formatter programs,
+and a set of device postprocessors.
+.
+This concept makes heavily use of the
+.I piping
+mechanism, i.e. a series of programs is called one after the other,
+where the output of each program in the queue is taken as the input
+for the next program.
+.
+.P
+\&.\|.\|.\&
+.B | preproc1 | preproc2 |
+\&.\|.\|.\&
+.B | troff | postproc
+.
+.P
+The preprocessors generate roff code that is fed into a roff formatter
+(e.g. troff), which in turn generates
+.I intermediate output
+that is fed into a device postprocessor program for printing or final
+output.
+.
+.P
+All of these parts use programming languages of their own; each
+language is totally unrelated to the other parts.
+.
+Moreover, roff macro packages can be inluded.
+.
+So most roff documents use the macros of some package, intermixed with
+code for one or more preprocessors, but do not need many elements from
+the plain roff language.
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Preprocessors"
+.\" --------------------------------------------------------------------
+.
+A roff preprocessor is any program that generates output that
+syntactically obeys the rules of the roff formatting language.
+.
+Each preprocessor defines a language of its own that is translated
+into roff code when run through the preprocessor program.
+.
+Parts written in these languages may be included within a roff
+document; they are identified by special roff requests or macros.
+.
+Each document that is enhanced by preprocessor code must be run
+through all corresponding preprocessors before it is fed into the
+actual roff formatter program, for the formatter just ignores all
+alien code.
+.
+The preprocessor programs extract and transform only the document
+parts that are determined for them.
+.
+.P
+There are a lot of free and commercial preprocessor programs.
+.
+Some of these aren't available on each system, but there is a small
+set of preprocessors that historically were considered part of the
+roff system.
+.
+The classical preprocessors are
+.
+.P
 .RS
-.LP
 .PD 0
 .TP
-.I eqn
-for including mathematical equations.
+.BR tbl
+for tables
+.TP
+.BR eqn
+for mathematical formul\(ae
+.TP
+.BR pic
+for drawing diagrams
+.TP
+.BR refer
+for bibliographic references
+.TP
+.BR soelim
+for including macro files from standard locations
+.PD
+.RE
+.
+.P
+Other known preprocessors include
+.
+.P
+.RS
+.PD 0
+.TP
+.I chem
+for drawing chemical formul\(ae
 .TP
 .I grap
-for constructing graphical elements (this preprocessor doesn't come with
-groff; it is an extra package).
+for constructing graphical elements
 .TP
 .I grn
-for including gremlin pictures.
+for including gremlin pictures
+.PD
+.RE
+.
+.P
+Note that the GNU versions of those preprocessors sometimes have a prefix in
+its name to distinguish them from the system's troff preprocessors in case
+both are installed.
+.
+Usually, the prefix is `g'; for example, GNU eqn is then available as geqn.
+.
+On this platform,
+.ie '@g@'' no prefix is used.
+.el the prefix is `@g@'.
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Formatter Programs"
+.\" --------------------------------------------------------------------
+.
+A
+.I roff formatter
+is a program that parses documents written in the roff
+formatting language or uses some of the roff macro packages.
+.
+It generates
+.IR "intermediate output" ,
+which is intended to be fed into a single device postprocessor that
+must be specified by a command-line option to the formatter program.
+.
+The documents must have been run through all necessary preprocessors
+before.
+.
+.P
+The roff formatter is the heart of the roff system.
+.
+The traditional roff had two formatters,
+.B nroff
+for text devices and
+.B troff
+for graphical devices.
+.P
+Modern roff implementations use to provide the functionality of both
+formatters within a single program, most often called
+.IR troff .
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Postprocessing"
+.\" --------------------------------------------------------------------
+.
+The output produced by a roff formatter is represented in yet another
+language the
+.IR "intermediate output format"
+or
+.IR "troff output" .
+This language was first specified in
+.IR "[CSTR #97]" ;
+its GNU extension is documented in
+.BR groff_out (@MAN5EXT@).
+.
+The intermediate output language is a kind of assembly language as
+compared to the high-level roff language.
+.
+.P
+The generated intermediate output is optimized for a special device,
+but the language is the same for every device.
+.
+Each device has a postprocessor program that parses the generated
+intermediate output and generates code in suitable form that may be
+sent directly to the device.
+.
+Devices are hardware interfaces like printers, text or graphical
+terminals, etc., or software interfaces such as a
+conversion into a different text or graphical format.
+.
+.P
+Of course, the devices have greatly changed since the classical
+times.
+.
+The old hardware doesn't exist any longer and the old graphical
+conversions weren't precise enough.
+.
+For example, the Postscript device
+.I post
+in classical troff had a resolution
+of 720, while groff
+.I ps
+has 72000, a refinement of factor 100.
+.
+.P
+Today the operating systems provide device drivers for most
+printer-like hardware, so it isn't necessary to write a special
+hardware postprocessor for each printer.
+.
+In groff, there are only 3 hardware postprocessors left.
+.
+.P
+.PD 0
+.RS
 .TP
-.I pic
-for creating diagrams.
+.BR grolbp (@MAN1EXT@)
+for some Canon printers,
+.TP
+.BR grolj4 (@MAN1EXT@)
+for printers compatible to the HP LaserJet\~4,
+.TP
+.BR grotty (@MAN1EXT@)
+for output on text-based terminals with various encodings.
+.PD
+.RE
+.
+.P
+The groff conversion devices are
+.
+.P
+.RS
+.PD 0
 .TP
-.I refer
-for bibliographic references.
+.BR grodvi (@MAN1EXT@)
+for the dvi format,
 .TP
-.I soelim
-for including other roff files.
+.BR grohtml (@MAN1EXT@)
+for html format,
 .TP
-.I tbl
-for rectangular tables.
+.BR grops (@MAN1EXT@)
+for Postscript.
 .PD
 .RE
-.LP
-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
-preprocessors before it is fed into the actual formatter.
-.LP
-The preprocessor programs extract and transform the document parts
-determined for them.
-They can be called either in a UNIX pipeline with their program name or
-automatically with a groff option.
-.LP
-.TS
-center, box, tab (@);
-C | C
-CfCB | CfCB.
-preprocessor@groff option
-=
-eqn@\-e
-grap@\-G
-grn@\-g
-pic@\-p
-refer@\-R
-tbl@\-t
-soelim@\-s
-.TE
-.LP
+.
+.P
+When combined with the many existing free conversion tools this should
+be enough to convert a troff document into almost any existing data
+format.
+.
+.
+.\" --------------------------------------------------------------------
+.SH "ROFF PROGRAMMING"
+.\" --------------------------------------------------------------------
+.
+Documents using roff are normal text files decorated by roff
+formatting elements.
+.
+The roff formatting language is quite powerful; it is almost a full
+programming language and provides elements to enlarge the language.
+.
+With these, it became possible to develop macro packages that are
+tailored for special applications.
+.
+Such macro packages are much handier than plain roff.
+.
+So most people will choose a macro package without worrying about the
+internals of the roff language.
+.
 .
 .\" --------------------------------------------------------------------
 .SH "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
 .IB name .tmac
-(or
+(classically
 .BI tmac. name\c
-) where
-.I name
-is the internal roff name for this package.
-All tmac files are stored in a single or few directories at standard
+).
+.
+All tmac files are stored in one or more directories at standardized
 positions.
-.LP
-A macro package that is used in a document is specified by the command line
-option
-.option \-m
-for the formatter like
-.option "troff\ \-m"
-.argname name
-or
-.option "groff\ \-m"
-.argname name .
-General details on the naming of macro packages and their placement is
-found in
+.
+Details on the naming of macro packages and their placement is found
+in
 .BR groff_tmac (@MAN5EXT@).
-.LP
+.
+.P
+A macro package that is to be used in a document can be announced to
+the formatter by the command line option
+.option \-m ,
+see
+.BR troff (@MAN1EXT@);
+or can be specified within a document using the file inclusion
+requests of the roff language, see
+.BR groff (@MAN7EXT@).
+.
+.P
 Famous classical macro packages are
 .IR man ,
-.IR mandoc ,
 and
-.I mdoc
-for manual pages and
+.I doc
+for manual pages, and
 .IR me ,
 .IR ms ,
 and
 .I 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
-conversion into other file formats.
+.
+Others are available.
+.
+.\" --------------------------------------------------------------------
+.SS "The roff Formatting Language"
+.\" --------------------------------------------------------------------
+The roff language with examples is documented in the
+.IR "groff info file" .
+.
+The manual page
+.BR groff (@MAN7EXT@)
+gives short descriptions of the language elements.
+.
+.P
+The roff language is a full programming language providing requests,
+definition of macros, escape sequences, string variables, number or
+size registers, and flow controls.
+.
+.P
+.I Requests
+are the predefined basic formatting commands similar to the commands
+at the shell prompt.
+.
+The user can define request-like elements using predefined
+roff elements.
+.
+These are then called
+.IR macros .
+.
+A document writer will not note any difference in usage for requests or
+macros, both are written on a line on their own starting with a dot
+.quoted_char . .
+.
+.P
+.I Escape sequences
+are roff elements starting with a backslash
+.quoted_char \*[backslash] .
+They can be inserted anywhere, also in the midst of text in a line.
+.
+They are used to implement various features, including the insertion of
+non-ASCII characters with
+.esc ( ,
+font changes with
+.esc f ,
+in-line comments with
+.esc \(dq ,
+the escaping of special control characters like
+.esc \e ,
+and many other features.
+.
+.P
+.I Strings
+are variables that can store a string.
+.
+A string is stored by the
+.B .ds
+request.
+.
+The stored string can be retrieved later by the
+.B \*[backslash]*
+escape sequence.
+.
+.P
+.I Registers
+store numbers and sizes.
+.
+A register can be set with the request
+.B .nr
+and its value can be retrieved by the escape sequence
+.BR "\*[backslash]n" .
 .\" --------------------------------------------------------------------
 .SH "FILE NAME EXTENSIONS"
 .\" --------------------------------------------------------------------
@@ -325,7 +767,8 @@ extension, e.g., the filename for this document is
 i.e., it is kept in
 .prefixednumber section 7
 of the man-pages.
-.LP
+.
+.P
 The classical macro packages take the package name as an extension, e.g.
 .IB file. me
 for a document using the
@@ -342,40 +785,134 @@ for
 .I pic
 files,
 etc.
-.ig
-.LP
+.
+.P
 But there is no general naming scheme for roff documents, though
-.IB file. roff
-or
-.IB file. rof
-seems to be a good choice.
-.LP
+.IB file. tr
+for
+.I troff file
+is seen now and then.
+.
+Maybe there should be a standardization for the filename extensions of
+roff files.
+.
+.P
 File name extensions can be very handy in conjunction with the
 .BR less (1)
 pager.
-It provides the possibility to feed all input into a command-line pipe that
-is specified in the shell environment variable
-.B LESSOPEN
-This process is not well documented, so here an example
+.
+It provides the possibility to feed all input into a command-line pipe
+that is specified in the shell environment variable
+.BR LESSOPEN .
+This process is not well documented, so here an example:
+.
+.IP
 .B LESSOPEN='|lesspipe %s'
+.
+.P
 where
 .B lesspipe
 is either a system supplied command or a shell script of your own.
-..
+.
 .\" --------------------------------------------------------------------
-.SH EDITING
+.SH "EDITING ROFF"
 .\" --------------------------------------------------------------------
-Most text editors provide support for editing documents using roff.
-Especially useful is the
-.B nroff-mode
-in all flavors of the Emacs editor.
+The best program for editing a roff document is Emacs (or Xemacs), see
+.BR emacs (1).
+It provides an
+.I nroff
+mode that is suitable for all kinds of roff dialects.
+.
+This mode can be activated by the following methods.
+.
+.P
+When editing a file within Emacs the mode can be changed by typing
+.RB ` "M-x nroff-mode" ',
+where
+.B M-x
+means to hold down the
+.B Meta
+key (or
+.BR Alt )
+and hitting the
+.B x
+key at the same time.
+.
+.P
+But it is also possible to have the mode automatically selected when
+the file is loaded into the editor.
+.Topic
+There is a set of file name extensions, e.g. the man-pages that
+trigger the automatic activation of the nroff-mode.
+.Topic
+Any file with one of the first line(s) containing the character
+sequence
+.B \%-*-\ nroff\ -*-
+is switched into nroff-mode when loaded.
+.
+But do not use this, it confuses some applications such as the
+.B man
+program.
+.Topic
+The best method is to include the following 3 comment lines at the end
+of the file.
+.
+.IP
+.nf
+.B .\*[comment] Local Variables:
+.B .\*[comment] mode: nroff
+.B .\*[comment] End:
+.fi
+.
+.P
+All roff processors handle automated spacing after the end of a
+sentence.
+.
+The safest way to not disturb this or to mix it up with abbreviations
+is to start each sentence on a line of its own without preceding white
+space.
+.
+To additionally use the auto-fill mode in Emacs, it is best to insert
+an empty roff request (a line consisting of a dot `.' only) after each
+sentence.
+.
+This suits the general roff rule to never use blank lines because they
+can produce unexpected behavior in the vertical spacing; so each line
+that is supposed to be empty or blank should instead use the line
+comment
+.B .\*[comment]
+or the empty request, a line containing a dot only.
+.
+The following example shows how optimal roff editing could look.
+.
+.IP
+.nf
+.I This is a sentence.
+.I .
+.I This is
+.I another one.
+.I .
+.I etc.
+.fi
+.
+.P
+Besides Emacs, some other editors provide nroff style files too, e.g.
+.BR vim ,
+an extension of the
+.B vi
+program.
+.
+But none of them can reach the functionality of Emacs.
+.
+.
 .\" --------------------------------------------------------------------
 .SH ENVIRONMENT
 .\" --------------------------------------------------------------------
+.
 .TP
 .SM
 .B GROFF_TMAC_PATH
-A colon separated list of directories in which to search for
+A colon-separated list of directories in which to search for
 macro files, see
 .BR groff_tmac (@MAN5EXT@).
 .TP
@@ -385,7 +922,7 @@ Default device.
 .TP
 .SM
 .B GROFF_FONT_PATH
-A colon separated list of directories in which to search for the
+A colon-separated list of directories in which to search for the
 .BI dev name
 directory.
 .B troff
@@ -395,9 +932,12 @@ command line option, then in
 .BR GROFF_FONT_PATH ,
 and finally in the standard directories
 .RB ( @FONTPATH@ ).
+.
+.
 .\" --------------------------------------------------------------------
 .SH FILES
 .\" --------------------------------------------------------------------
+.
 By default,
 .I groff
 installs all of its data files in subdirectories of
@@ -408,6 +948,7 @@ and in
 in
 .IR @SYSTEMMACRODIR@ ).
 These locations might vary for different systems.
+.
 In the following, the former is referred to as
 .IR <groff_font_dir> ,
 the latter as
@@ -417,7 +958,7 @@ the latter as
 Initialization file for troff.
 .TP
 .IB <groff_macro_dir> / name .tmac
-.TQ
+.TP+
 .IB <groff_macro_dir> /tmac. name
 Macro files.
 .TP
@@ -430,114 +971,238 @@ Font file for font
 .I F
 of device
 .IR name .
-.LP
+.P
 Finally, a local macro directory
 .I @LOCALMACRODIR@
 is provided for site-specific macros and packages; by default, it will be
 searched before the main macro directory.
+.
+.
 .\" --------------------------------------------------------------------
 .SH BUGS
 .\" --------------------------------------------------------------------
-The groff documentation is in evolution at the moment.
-It is possible that small inconsistencies between different documents exist
-temporarily.
+.
+UNIX\(rg is a registered trademark of the Open Group.
+.
+.P
+The sections FILES and ENVIRONMENT should go to a different man-page.
+.
+.
 .\" --------------------------------------------------------------------
-.SH AUTHOR
+.SH "SEE ALSO"
 .\" --------------------------------------------------------------------
-This document is part of groff, the GNU roff distribution.  It was
-written by Bernd Warken <bwarken@mayn.de>.
-.LP
-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
-.RS
-.LP
-.IR <http://www.gnu.org/copyleft/fdl.html> .
-.RE
+.
+There is a lot of documentation on roff.
+.
+The original papers on classical troff are still available, and all
+aspects of groff are documented in great detail.
+.
+.
 .\" --------------------------------------------------------------------
-.SH "SEE ALSO"
+.SS "Historical roff Documentation"
 .\" --------------------------------------------------------------------
-The main source of information is the
-.I groff
+.
+Many classical
+.troff
+documents are still available on-line.
+.
+.P
+The old history is best documented at the
+.URL "Multics site" http://\:www.multicians.org .
+This contains a lot of information on the MIT projects, CTSS, Multics,
+early Unix, including runoff.
+.
+Especially useful are a glossary and the many links to other documents.
+.
+.P
+The web site
+.URL "Bell Labs Computing and Mathematical Sciences Research" \
+http://\:cm.bell-labs.com/\:cm/\:index.html
+provides a search facility for tracking information on the early
+developers.
+.
+.P
+The best documentation on the issues of the original, free Unix with
+its standard programs are the papers in the series
+.URL "Bell Labs CSTR" http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr.html .
+.
+These also contain the two main documents of the early nroff/troff,
+being
+.TP
+.I [CSTR #54]
+The 1992 revision of Osanna/Kernighan's 1976 paper
+.URL "Nroff/\:Troff User's Manual" \
+http://\:cm.bell-labs.com/\:cm/\:cs/\:54.ps .
+.TP
+.I [CSTR #97]
+Brian Kernighan's 1979 paper
+.URL "A Typesetter-independent TROFF" \
+http://\:cm.bell-labs.com/\:cm/\:cs/\:97.ps .
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Info File"
+.\" --------------------------------------------------------------------
+.
+The
+.IR "groff info file"
+contains all information on the groff system within a single document.
+.
+Besides the documentation of features, examples and background
+information is provided.
+.
+It can be read within some integrated desktop help systems, or within
+.BR emacs (1),
+or from the shell prompt using the
 .BR info (1)
-file.
-.LP
-The predefined elements of the
-.I groff
-language are also documented in the manual page
+command.
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Manual Pages"
+.\" --------------------------------------------------------------------
+.
+The
+.I manual pages
+or shortly
+.I man-pages
+are the main documentation system on many operating system.
+.
+Due to its complex structure, a full roff system has many man-pages,
+each describing a single aspect of roff.
+.
+.P
+In this document, a reference to a man-page looks like this:
 .BR groff (@MAN7EXT@).
-.LP
-Formatters and their wrappers:
-.BR groff (@MAN1EXT@),
-.BR grog (@MAN1EXT@),
-.BR nroff (@MAN1EXT@),
-and
-.BR troff (@MAN1EXT@).
-.LP
-Postprocessors for the output devices:
-.BR grodvi (@MAN1EXT@),
-.BR grohtml (@MAN1EXT@),
-.BR grolbp (@MAN1EXT@),
-.BR grolj4 (@MAN1EXT@),
-.BR grops (@MAN1EXT@),
-and
-.BR grotty (@MAN1EXT@).
-.LP
-Standard preprocessors:
-.BR eqn (@MAN1EXT@),
-.BR grn (@MAN1EXT@),
-.BR grap (1),
-.BR pic (@MAN1EXT@),
-.BR refer (@MAN1EXT@),
-.BR soelim (@MAN1EXT@),
-and
-.BR tbl (@MAN1EXT@).
-.LP
-The man pages for macro packages include
-.BR groff_tmac (@MAN5EXT@),
-.BR groff_man (@MAN7EXT@),
-.BR groff_markup (@MAN7EXT@),
-.BR groff_mdoc (@MAN7EXT@),
-.BR groff_mdoc.samples (@MAN7EXT@),
-.BR groff_me (@MAN7EXT@),
-.BR groff_mm (@MAN7EXT@),
-.BR groff_mmroff (@MAN7EXT@),
-and
-.BR groff_ms (@MAN7EXT@).
-.LP
+.
+This refers to a manual page
+.I groff
+in section\~\c
+.IR 7 .
+.
+To read the example, look-up section\~7 in your desktop help system or
+call from the shell prompt
+.
+.IP
+#
+.B man @MAN7EXT@ groff
+.
+.P
+For more details, see the documentation of the
+.B man
+program in section\~1, i.e.
+.BR man (@MAN1EXT@).
+.
+.P
+The following is a list of the man-pages found in groff and related
+GNU packages.
+.
+.TP
+Roff preprocessors:
+.BR \%@g@eqn (@MAN1EXT@),
+.BR \%@g@grn (@MAN1EXT@),
+.BR \%@g@pic (@MAN1EXT@),
+.BR \%@g@refer (@MAN1EXT@),
+.BR \%@g@soelim (@MAN1EXT@),
+.BR \%@g@tbl (@MAN1EXT@),
+.BR grap (1).
+.
+.TP
+Roff language with the groff extensions:
+.BR \%groff (@MAN7EXT@),
+.BR \%groff_char (@MAN7EXT@),
+.BR \%groff_font (@MAN7EXT@).
+.
+.TP
+The intermediate output language with groff extensions:
+.BR \%groff_out (@MAN7EXT@).
+.
+.TP
+Roff formatter programs:
+.BR \%@g@nroff (@MAN1EXT@),
+.BR \%@g@troff (@MAN1EXT@).
+.
+.TP
+Wrapper programs for formatters:
+.BR \%groff (@MAN1EXT@),
+.BR \%grog (@MAN1EXT@).
+.
+.TP
+The groff postprocessors for the output devices:
+.BR \%grodvi (@MAN1EXT@),
+.BR \%grohtml (@MAN1EXT@),
+.BR \%grolbp (@MAN1EXT@),
+.BR \%grolj4 (@MAN1EXT@),
+.BR \%grops (@MAN1EXT@),
+.BR \%grotty (@MAN1EXT@).
+.
+.TP
+Groff macro packages and macro-specific utilities:
+.BR \%groff_tmac (@MAN5EXT@),
+.BR \%groff_man (@MAN7EXT@),
+.BR \%groff_mdoc (@MAN7EXT@),
+.BR \%groff_me (@MAN7EXT@),
+.BR \%groff_mm (@MAN7EXT@),
+.BR \%groff_mmse (@MAN7EXT@),
+.BR \%mmroff (@MAN7EXT@),
+.BR \%groff_ms (@MAN7EXT@),
+.BR \%groff_www (@MAN7EXT@).
+.
+.TP
 The following utilities are available:
-.BR addftinfo (@MAN1EXT@),
-.BR afmtodif (@MAN1EXT@),
-.BR hpftodit (@MAN1EXT@),
-.BR indxbib (@MAN1EXT@),
-.BR lookbib (@MAN1EXT@),
-.BR pfbtops (@MAN1EXT@),
-.BR tfmtodit (@MAN1EXT@),
-and
-.BR gxditview (@MAN1EXT@).
-.LP
-For details on the GNU implementation of the
-.I roff
-system see
-.BR groff_char (@MAN7EXT@),
-.BR groff_font (@MAN7EXT@),
-.BR groff_out (@MAN7EXT@),
-and the file
+.BR \%addftinfo (@MAN1EXT@),
+.BR \%afmtodit (@MAN1EXT@),
+.BR \%gxditview (@MAN1EXT@),
+.BR \%hpftodit (@MAN1EXT@),
+.BR \%@g@indxbib (@MAN1EXT@),
+.BR \%@g@lookbib (@MAN1EXT@),
+.BR \%pfbtops (@MAN1EXT@),
+.BR \%tfmtodit (@MAN1EXT@),
+.BR \%gxditview (@MAN1EXT@),
+.BR \%xditview (1).
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Groff Development"
+.\" --------------------------------------------------------------------
+.
+For details on the GNU implementation of the roff system see the file
 .I README
 in the main directory of the groff source distribution.
-These also give details on how to contact or join the
+.
+This also gives details on how to contact or join the
 .I groff
 developer group.
-.LP
-Many classical
-.troff
-documents are still available on-line.
-Especially informative are the original Bell Labs proceedings for the old,
-free UNIX 7 found at
-.I http://cm.bell-labs.com/cm/cs/cstr.html
-and the collection of the late Richard S. Stevens at 
-.IR http://www.kohala.com/start/troff/ .
 .
+.
+.\" --------------------------------------------------------------------
+.SH AUTHORS
+.\" --------------------------------------------------------------------
+.
+Copyright (C) 1989, 2001 Free Software Foundation, Inc.
+.P
+This document 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 at the
+.URL "GNU copyleft site" http://\:www.gnu.org/\:copyleft/\:fdl.html .
+.
+.P
+This document is part of
+.IR groff ,
+the GNU roff distribution.
+.
+It was written by
+.URL "Bernd Warken" mailto:bwarken@mayn.de .
+The historical facts are based on the research of
+.URL "Ted Harding" mailto:Ted.Harding@nessie.mcc.ac.uk .
+This document is maintained by
+.URL "Werner Lemberg" mailto:wl@gnu.org .
+.
+.\" --------------------------------------------------------------------
+.\" Emacs setup
+.\" --------------------------------------------------------------------
 .\" Local Variables:
 .\" mode: nroff
 .\" End:
diff --git a/src/roff/groff/groff.man b/src/roff/groff/groff.man
index d4f06ca6..805c6a17 100644
--- a/src/roff/groff/groff.man
+++ b/src/roff/groff/groff.man
@@ -464,29 +464,10 @@ The actual version can be found at
 .IP
 \%http://www.lunabase.org/~faber/Vault/software/grap/
 .SH "SEE ALSO"
-.BR grog (@MAN1EXT@),
-.BR @g@troff (@MAN1EXT@),
-.BR @g@tbl (@MAN1EXT@),
-.BR @g@pic (@MAN1EXT@),
-.BR @g@eqn (@MAN1EXT@),
-.BR @g@grn (@MAN1EXT@),
-.BR grap (1),
-.BR @g@soelim (@MAN1EXT@),
-.BR @g@refer (@MAN1EXT@),
-.BR grops (@MAN1EXT@),
-.BR grodvi (@MAN1EXT@),
-.BR grotty (@MAN1EXT@),
-.BR grolj4 (@MAN1EXT@),
-.BR grolbp (@MAN1EXT@),
-.BR grohtml (@MAN1EXT@),
-.BR gxditview (@MAN1EXT@),
-.BR groff_font (@MAN5EXT@),
-.BR groff_out (@MAN5EXT@),
-.BR groff_man (@MAN7EXT@),
-.BR groff_ms (@MAN7EXT@),
-.BR groff_me (@MAN7EXT@),
-.BR groff_www (@MAN7EXT@),
-.BR groff_char (@MAN7EXT@)
+.BR roff (@MAN7EXT) ;
+this man page provides an exhaustive list of programs and packages related
+to
+.BR groff .
 .
 .\" Local Variables:
 .\" mode: nroff