* doc/groff.texinfo: Added macros `@Defmpreg' and `@Defmpregx' for

registers defined in macro packages.
Revising the ms part.

* doc/groff.texinfo: Add documentation for ms macros.

First step in adding PS support for the Euro symbol.  `eu' is the
official Euro logo, `Eu' is a font-specific glyph variant.

* font/devps/text.enc: Add `Euro' at position 9.
* font/devps/generate/textmap: Add `Euro' as symbol `Eu'.
* font/devps/symbolmap: Regenerated.

* NEWS: Updated.

* man/roff.man: Revised.

7 files changed, 1517 insertions, 429 deletions

diff --git a/ChangeLog b/ChangeLog
index a27444de..d9a9a274 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,28 @@
+2002-01-04  Werner LEMBERG  <wl@gnu.org>
+
+	* doc/groff.texinfo: Added macros `@Defmpreg' and `@Defmpregx' for
+	registers defined in macro packages.
+	Revising the ms part.
+
+2002-01-04  Larry Kollar  <kollar@alltel.net>
+
+	* doc/groff.texinfo: Add documentation for ms macros.
+
+2002-01-02  Werner LEMBERG  <wl@gnu.org>
+
+	First step in adding PS support for the Euro symbol.  `eu' is the
+	official Euro logo, `Eu' is a font-specific glyph variant.
+
+	* font/devps/text.enc: Add `Euro' at position 9.
+	* font/devps/generate/textmap: Add `Euro' as symbol `Eu'.
+	* font/devps/symbolmap: Regenerated.
+
+	* NEWS: Updated.
+
+2002-01-02  Bernd Warken  <bwarken@mayn.de>
+
+	* man/roff.man: Revised.
+
 2002-01-01  Bernd Warken  <bwarken@mayn.de>
 
 	* src/roff/groff/groff.man: Completely rewritten.
diff --git a/NEWS b/NEWS
index d2995604..8d18d54c 100644
--- a/NEWS
+++ b/NEWS
@@ -110,6 +110,8 @@ o Color support for glyphs has been added.
 
 o New option `-h' to select the style of headings in HTML output.
 
+o New option `-b' to set the background colour to white.
+
 Miscellaneous
 -------------
 
diff --git a/doc/groff.texinfo b/doc/groff.texinfo
index d6b8e049..a5509204 100644
--- a/doc/groff.texinfo
+++ b/doc/groff.texinfo
@@ -102,6 +102,23 @@
 @end macro
 
 
+@c definition of registers specific to macro packages
+
+@macro Defmpreg{name, package}
+@vindex \name\ @r{[}\package\@r{]}
+@deffn Register @t{\\n[\name\]}
+@end macro
+
+@macro Defmpregx{name, package}
+@vindex \name\ @r{[}\package\@r{]}
+@deffnx Register @t{\\n[\name\]}
+@end macro
+
+@macro endDefmpreg
+@end deffn
+@end macro
+
+
 @c definition of macros
 
 @macro Defmac{name, arg, package}
@@ -1078,7 +1095,6 @@ GNU/Linux system.
 
 
 
-
 @c =====================================================================
 @c =====================================================================
 
@@ -2367,7 +2383,7 @@ become common usage to make the first line of the man page look like
 this:
 
 @Example
-.\" @var{word}
+'\" @var{word}
 @endExample
 
 @pindex geqn@r{, invocation in manual pages}
@@ -2397,7 +2413,1250 @@ and automatically call the right preprocessor(s).
 @section @file{ms}
 @cindex @file{ms}
 
-@c XXX documentation
+The @file{-ms}
+macros are suitable for reports, letters, books,
+user manuals, and so forth.
+The package provides macros for cover pages, section headings,
+paragraphs, lists, footnotes, pagination,
+and a table of contents.
+
+@menu
+* ms Intro::
+* General ms Structure::
+* ms Document Control Registers::
+* ms Cover Page Macros::
+* ms Body Text::
+* ms Page Layout::
+* Differences from AT&T ms::
+@end menu
+
+@c ---------------------------------------------------------------------
+
+@node ms Intro, General ms Structure, ms, ms
+@subsection Introduction to @file{ms}
+
+The original @file{-ms} macros were included with
+@acronym{AT&T} @code{troff} as well as the
+@file{man} macros.
+While the @file{man} package is intended for brief documents
+that can be read on-line as well as printed, the @file{ms}
+macros are suitable for longer documents that are meant to be
+printed rather than read on-line.
+
+The @file{ms} macro package included with @code{groff}
+is a complete, bottom-up re-implementation.
+Several macros (specific to @acronym{AT&T}
+or Berkeley) are not included, while several new commands are.
+@xref{Differences from AT&T ms}, for more information.
+
+@c ---------------------------------------------------------------------
+
+@node General ms Structure, ms Document Control Registers, ms Intro, ms
+@subsection General structure of an @file{ms} document
+@cindex @file{ms}, general structure
+
+The @file{ms} macro package expects a certain amount of structure,
+but not as much as packages such as @file{man} or @file{mdoc}.
+
+The simplest documents can begin with a paragraph macro
+(such as @code{LP} or @code{PP}),
+and consist of text separated by paragraph macros
+or even blank lines.
+Longer documents have a structure as follows:
+
+@table @strong
+@item Document type
+If you invoke the @code{RP}
+(report) macro on the first line of the document,
+@code{groff} prints the cover page information on its own page;
+otherwise it prints the information on the
+first page with your document text immediately following.
+Other document formats found in @acronym{AT&T} @code{troff}
+are specific to @acronym{AT&T} or Berkeley, and are not supported in
+@code{groff}.
+
+@item Format and layout
+By setting number registers,
+you can change your document's type (font and size),
+margins, spacing, headers and footers, and footnotes.
+@xref{ms Document Control Registers}, for more details.
+
+@item Cover page
+A cover page consists of a title, the author's name and institution,
+an abstract, and the date.
+@footnote{Actually, only the title is required.}
+@xref{ms Cover Page Macros}, for more details.
+
+@item Body
+Following the cover page is your document.
+You can use the @file{ms}
+macros to write reports, letters, books, and so forth.
+The package is designed for structured documents,
+consisting of paragraphs interspersed with headings
+and augmented by lists, footnotes, tables, and other
+common constructs.
+@xref{ms Body Text}, for more details.
+
+@item Table of contents
+Longer documents usually include a table of contents,
+which you can invoke by placing the
+@code{TC}
+macro at the end of your document.
+The @file{ms}
+macros have minimal indexing facilities, consisting of the
+@code{IX} macro, which prints an entry on standard error.
+Printing the table of contents at the end is necessary since
+@code{groff} is a single-pass text formatter,
+thus it cannot determine the page number of each section
+until that section has actually been set and printed.
+Since @file{ms} output is intended for hardcopy,
+you can manually relocate the pages containing
+the table of contents between the cover page and the
+body text after printing.
+@end table
+
+@c ---------------------------------------------------------------------
+
+@node ms Document Control Registers, ms Cover Page Macros, General ms Structure, ms
+@subsection Document control registers
+@cindex @file{ms}, document control registers
+
+The following is a list of document control number registers.
+For the sake of consistency,
+set registers related to margins at the beginning of your document,
+or just after the @code{RP} macro.
+You can set other registers later in your document,
+but you should keep them together at the beginning
+to make them easy to find and edit as necessary.
+
+@unnumberedsubsubsec Margin Settings
+
+@Defmpreg{PO, ms}
+Defines the page offset (i.e.@: the left margin).
+There is no explicit right margin setting; the combination of
+the @code{PO} and @code{LL} registers implicitly define the
+right margin width.
+
+Effective: next page.
+
+Default value: 1@dmn{i}.
+@endDefmpreg
+
+@Defmpreg{LL, ms}
+Defines the line length (i.e.@: the width of the body text).
+
+Effective: next paragraph.
+
+Default: 6@dmn{i}.
+@endDefmpreg
+
+@Defmpreg{LT, ms}
+Defines the title length (i.e.@: the header and footer width).
+This is usually the same as @code{LL}, but not necessarily.
+
+Effective: next paragraph.
+
+Default: 6@dmn{i}.
+@endDefmpreg
+
+@Defmpreg{HM, ms}
+Defines the header margin height at the top of the page.
+
+Effective: next page.
+
+Default: 1@dmn{i}.
+@endDefmpreg
+
+@Defmpreg{FM, ms}
+Defines the footer margin height at the bottom of the page.
+
+Effective: next page.
+
+Default: 1@dmn{i}.
+@endDefmpreg
+
+@unnumberedsubsubsec Text Settings
+
+@Defmpreg{PS, ms}
+Defines the point size of the body text.
+
+Effective: next paragraph.
+
+Default: 10@dmn{p}.
+@endDefmpreg
+
+@Defmpreg{VS, ms}
+Defines the space between lines (line height plus leading).
+
+Effective: next paragraph.
+
+Default: 12@dmn{p}.
+@endDefmpreg
+
+@unnumberedsubsubsec Paragraph Settings
+
+@Defmpreg{PI, ms}
+Defines the initial indent of a @code{.PP} paragraph.
+
+Effective: next paragraph.
+
+Default: 5@dmn{n}.
+@endDefmpreg
+
+@Defmpreg{PD, ms}
+Defines the space between paragraphs.
+
+Effective: next paragraph.
+
+Default: 0.3@dmn{v}.
+@endDefmpreg
+
+@Defmpreg{QI, ms}
+Defines the indent on both sides of a quoted (@code{.QP}) paragraph.
+
+Effective: next paragraph.
+
+Default: 5@dmn{n}.
+@endDefmpreg
+
+@unnumberedsubsubsec Footnote Settings
+
+@Defmpreg{FL, ms}
+Defines the length of a footnote.
+
+Effective: next footnote.
+
+Default: @math{@code{\n[LL]} * 5 / 6}.
+@endDefmpreg
+
+@Defmpreg{FI, ms}
+Defines the footnote indent.
+
+Effective: next footnote.
+
+Default: 2@dmn{n}.
+@endDefmpreg
+
+@Defmpreg{FF, ms}
+The footnote format:
+@table @code
+@item 0
+Prints the footnote number as a superscript; indents the footnote (default).
+
+@item 1
+Prints the number followed by a period (like 1.)
+and indents the footnote.
+
+@item 2
+Like 1, without an indent.
+
+@item 3
+Like 1, but prints the footnote number as a hanging paragraph.
+@end table
+
+Effective: next footnote.
+
+Default: 0.
+@endDefmpreg
+
+@unnumberedsubsubsec Miscellaneous Number Registers
+
+@Defmpreg{MINGW, ms}
+Defines the minimum width between columns in a multi-column document.
+
+Effective: next page.
+
+Default: 2@dmn{n}.
+@endDefmpreg
+
+@c ---------------------------------------------------------------------
+
+@node ms Cover Page Macros, ms Body Text, ms Document Control Registers, ms
+@subsection Cover page macros
+@cindex @file{ms}, cover page macros
+@cindex Cover page macros, @file{ms}
+
+Use the following macros to create a cover page for your document
+in the order shown.
+
+@Defmac{RP, [@code{no}], ms}
+Specifies the report format for your document.
+The report format creates a separate cover page.
+The default action (no @code{.RP}
+macro) is to print a subset of the
+cover page on page 1 of your document.
+
+If you use the word @code{no} as an optional argument,
+@code{groff} prints a title page but
+does not repeat any of the title page information
+(title, author, abstract, etc.)
+on page 1 of the document.
+@endDefmac
+
+@Defmac{DA, [@dots{}], ms}
+(optional) Print the current date, or the arguments to the macro if any,
+on the title page (if specified) and in the footers.
+This is the default for @code{nroff}.
+@endDefmac
+
+@Defmac{ND, [@dots{}], ms}
+(optional) Print the current date, or the arguments to the macro if any,
+on the title page (if specified) but not in the footers.
+This is the default for @code{troff}.
+@endDefmac
+
+@Defmac{TL, , ms}
+Specifies the document title.
+@code{groff} collects text following the @code{.TL}
+macro into the title, until reaching the author name or abstract.
+@endDefmac
+
+@Defmac{AU, , ms}
+Specifies the author's name, which appears on the
+line (or lines) immediately following.
+You can specify multiple authors as follows:
+
+@Example
+.AU
+John Doe
+.AI
+University of West Bumblefuzz
+.AU
+Martha Buck
+.AI
+Monolithic Corporation
+
+...
+@endExample
+@endDefmac
+
+@Defmac{AI, , ms}
+Specifies the author's institution.
+You can specify multiple institutions in the same way
+that you specify multiple authors.
+@endDefmac
+
+@Defmac{AB, [@code{no}], ms}
+Begins the abstract.
+The default is to print the word @acronym{ABSTRACT},
+centered and in italics, above the text of the abstract.
+The word @code{no} as an optional argument suppresses this heading.
+@endDefmac
+
+@Defmac{AE, , ms}
+End the abstract.
+@endDefmac
+
+The following is example mark-up for a title page.
+@cindex Title page, example markup
+@cindex Example markup, title page
+
+@Example
+@cartouche
+.RP
+.TL
+The Inevitability of Code Bloat
+in Commercial and Free Software
+.AU
+J. Random Luser
+.AI
+University of West Bumblefuzz
+.AB
+This report examines the long-term growth
+of the code bases in two large, popular software
+packages; the free Emacs and the commercial
+Microsoft Word.
+While differences appear in the type or order
+of features added, due to the different
+methodologies used, the results are the same
+in the end.
+.PP
+The free software approach is shown to be
+superior in that while free software can
+become as bloated as commercial offerings,
+free software tends to have fewer serious
+bugs and the added features are in line with
+user demand.
+.AE
+
+... the rest of the paper follows ...
+@end cartouche
+@endExample
+
+@c ---------------------------------------------------------------------
+
+@node ms Body Text, Paragraphs in ms, ms Cover Page Macros, ms
+@subsection Body text
+@cindex @file{ms}, body text
+
+This section describes macros used to mark up the body of your document.
+Examples include paragraphs, sections, and other groups.
+
+@menu
+* Paragraphs in ms::
+* Headings in ms::
+* Highlighting in ms::
+* Lists in ms::
+* ms Displays and Keeps::
+* ms Insertions::
+* ms Footnotes::
+@end menu
+
+@c ---------------------------------------------------------------------
+
+@node Paragraphs in ms, Headings in ms, ms Body Text, ms Body Text
+@subsubsection Paragraphs
+@cindex @file{ms}, paragraph macros
+
+The following paragraph types are available.
+
+@Defmac{PP, , ms}
+Sets a paragraph with an initial indent.
+@endDefmac
+
+@Defmac{LP, , ms}
+Sets a paragraph with no initial indent.
+@endDefmac
+
+@Defmac{QP, , ms}
+Sets a paragraph that is indented at both left and right margins.
+The effect is identical to the @acronym{HTML} @code{<BLOCKQUOTE>} element.
+The next paragraph or heading returns margins to normal.
+@endDefmac
+
+The following markup uses all three paragraph macros.
+
+@Example
+@cartouche
+.NH 2
+Cases used in the study
+.LP
+The following software and versions were
+considered for this report.
+.PP
+For commercial software, we chose
+.B "Microsoft Word for Windows" ,
+starting with version 1.0 through the
+current version (Word 2000).
+.PP
+For free software, we chose
+.B Emacs ,
+from its first appearance as a standalone
+editor through the current version (v20).
+.QP
+Franklin's Law applied to software:
+software expands to outgrow both
+RAM and disk space over time.
+@end cartouche
+@endExample
+
+@c ---------------------------------------------------------------------
+
+@node Headings in ms, Highlighting in ms, Paragraphs in ms, ms Body Text
+@subsubsection Headings
+@cindex @file{ms}, heading macros
+
+Use headings to create a hierarchical structure for your document.
+The @file{ms} macros print headings in @strong{bold},
+using the same font family and point size as the body text.
+
+The following describes the heading macros:
+
+@Defmac{NH, @Var{curr-level}, ms}
+@Defmacx{NH, @t{S} @Var{level0} @dots{}, ms}
+Numbered heading.
+The argument is either a numeric argument to indicate the
+level of the heading, or the letter @code{S} followed by numeric arguments
+to set the heading level explicitly.
+
+If you specify heading levels out of sequence, such as invoking
+@samp{.NH 3} after @samp{.NH 1}, @code{groff}
+prints a warning on standard error.
+@endDefmac
+
+@Defmac{SH, , ms}
+Unnumbered subheading.
+@endDefmac
+
+@c ---------------------------------------------------------------------
+
+@node Highlighting in ms, Lists in ms, Headings in ms, ms Body Text
+@subsubsection Highlighting
+@cindex @file{ms}, highlighting macros
+
+The @file{ms} macros provide a variety of methods to highlight
+or emphasize text:
+
+@Defmac{B, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
+Sets its first argument in @strong{bold type}.
+If you specify a second argument, @code{groff} prints it in the
+previous font after the bold text, with no intervening space
+(this allows you to set punctuation after the highlighted text
+without highlighting the punctuation).
+Similarly, it prints the third argument (if any) in the previous
+font @strong{before} the first argument.
+For example,
+
+@Example
+.B foo ) (
+@endExample
+
+prints (@strong{foo}).
+
+If you give this macro no arguments, @code{groff}
+prints all text following in bold until
+the next highlighting, paragraph, or heading macro.
+@endDefmac
+
+@Defmac{R, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
+Sets its first argument in roman (or regular) type.
+It operates similarly to the @code{B} macro otherwise.
+@endDefmac
+
+@Defmac{I, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
+Sets its first argument in @emph{italic type}.
+It operates similarly to the @code{B} macro otherwise.
+@endDefmac
+
+@Defmac{CW, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
+Sets its first argument in a @code{constant width face}.
+It operates similarly to the @code{B} macro otherwise.
+@endDefmac
+
+@Defmac{BI, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
+Sets its first argument in bold italic type.
+It operates similarly to the @code{B} macro otherwise.
+@endDefmac
+
+@Defmac{BX, [@Var{txt}], ms}
+Prints its argument and draws a box around it.
+If you want to box a string that contains spaces,
+use a digit-width space (@code{\0}).
+@endDefmac
+
+@Defmac{UL, [@Var{txt} [@Var{post}]], ms}
+Prints its first argument with an underline.
+If you specify a second argument, @code{groff}
+prints it in the previous font after
+the underlined text, with no intervening space.
+@endDefmac
+
+@Defmac{LG, , ms}
+Prints all text following in larger type
+(two points larger than the current point size) until
+the next font size, highlighting, paragraph, or heading macro.
+You can specify this macro multiple times
+to enlarge the point size as needed.
+@endDefmac
+
+@Defmac{SM, , ms}
+Prints all text following in smaller type
+(two points smaller than the current point size) until
+the next type size, highlighting, paragraph, or heading macro.
+You can specify this macro multiple times
+to reduce the point size as needed.
+@endDefmac
+
+@Defmac{NL, , ms}
+Prints all text following in the normal point size
+(that is, the value of the @code{PS} register).
+@endDefmac
+
+@c ---------------------------------------------------------------------
+
+@node Lists in ms, ms Displays and Keeps, Highlighting in ms, ms Body Text
+@subsubsection Lists
+@cindex @file{ms}, list macros
+
+The @code{.IP} macro handles duties for all lists.
+
+@Defmac{IP, [@Var{marker} [@Var{width}]], ms}
+The @var{marker} is usually a bullet character (@code{\[bu]})
+for unordered lists, a number (or auto-incrementing number
+register) for numbered lists, or a word or phrase for indented
+(glossary-style) lists.
+
+The @var{width} specifies the indent for the body of each list item;
+its default unit is @samp{n}.
+Once specified, the indent remains the same for all
+list items in the document until specified again.
+@endDefmac
+
+The following is an example of a bulleted list.
+@cindex Example markup, bulleted list (ms)
+@cindex Bulleted list, example markup (ms)
+
+@Example
+A bulleted list:
+.IP \[bu] 2
+lawyers
+.IP \[bu]
+guns
+.IP \[bu]
+money
+@endExample
+
+Produces:
+
+@Example
+A bulleted list:
+
+o lawyers
+
+o guns
+
+o money
+@endExample
+
+@sp 1
+
+The following is an example of a numbered list.
+@cindex Example markup, numbered list (ms)
+@cindex Numbered list, example markup (ms)
+
+@Example
+.nr step 1 1
+A numbered list:
+.IP \\n[step] 3
+lawyers
+.IP \\n+[step]
+guns
+.IP \\n+[step]
+money
+@endExample
+
+Produces:
+
+@Example
+A numbered list:
+
+1. lawyers
+
+2. guns
+
+3. money
+@endExample
+
+Note the use of the auto-incrementing number
+register in this example.
+
+@sp 1
+The following is an example of a glossary-style list.
+@cindex Example markup, glossary-style list (ms)
+@cindex Glossary-style list, example markup (ms)
+
+@Example
+A glossary-style list:
+.IP lawyers 0.4i
+Two or more attorneys.
+.IP guns
+Firearms, preferably
+large-caliber.
+.IP money
+Gotta pay for those
+lawyers and guns!
+@endExample
+
+Produces:
+
+@Example
+A glossary-style list:
+
+lawyers
+      Two or more attorneys.
+
+guns  Firearms, preferably large-caliber.
+
+money
+      Gotta pay for those lawyers and guns!
+@endExample
+
+In the last example, the @code{IP} macro places the definition
+on the same line as the term if it has enough space; otherwise,
+it breaks to the next line and starts the definition below the
+term.
+This may or may not be the effect you want, especially if some
+of the definitions break and some do not.
+The following examples show two possible ways to force a break.
+
+The first workaround uses the @code{.br}
+request to force a break after printing the term or label.
+
+@Example
+@cartouche
+A glossary-style list:
+.IP lawyers 0.4i
+Two or more attorneys.
+.IP guns
+.br
+Firearms, preferably large-caliber.
+.IP money
+Gotta pay for those lawyers and guns!
+@end cartouche
+@endExample
+
+@sp 1
+The second workaround uses the @code{\p} escape to force the break.
+Note the space following the escape; this is important.
+If you omit the space, @code{groff} prints the first word on
+the same line as the term or label (if it fits) @strong{then}
+breaks the line.
+
+@Example
+@cartouche
+A glossary-style list:
+.IP lawyers 0.4i
+Two or more attorneys.
+.IP guns
+\p Firearms, preferably large-caliber.
+.IP money
+Gotta pay for those lawyers and guns!
+@end cartouche
+@endExample
+
+@sp 1
+To set nested lists, use the @code{RS} and @code{RE} macros.
+@cindex @file{ms}, nested lists
+@cindex Nested lists (ms)
+
+@Defmac{RS, , ms}
+@Defmacx{RE, , ms}
+These macros begin and end a section indented to line
+up with the body of an @code{IP} macro.
+@endDefmac
+
+For example:
+
+@Example
+@cartouche
+.IP \[bu] 2
+Lawyers:
+.RS
+.IP \[bu]
+Dewey,
+.IP \[bu]
+Cheatham,
+.IP \[bu]
+and Howe.
+.RE
+.IP \[bu]
+Guns
+@end cartouche
+@endExample
+
+Produces:
+
+@Example
+o Lawyers:
+
+  o  Dewey,
+
+  o  Cheatham,
+
+  o  and Howe.
+
+o Guns
+@endExample
+
+@c ---------------------------------------------------------------------
+
+@node ms Displays and Keeps, ms Insertions, Lists in ms, ms Body Text
+@subsubsection Displays and keeps
+@cindex @file{ms}, displays
+@cindex @file{ms}, keeps
+@cindex Keeps (ms)
+@cindex Displays (ms)
+
+Use displays to show text-based examples or figures
+(such as code listings).
+
+Displays turn off filling, so lines of code are displayed
+as-is without inserting @code{br} requests in between each line.
+Displays can be @dfn{kept} on a single page, or allowed
+to break across pages.
+
+@Defmac{DS, @t{L}, ms}
+@Defmacx{LD, , ms}
+@Defmacx{DE, , ms}
+Left-justified display.
+The @samp{.DS L} call generates a page break, if necessary,
+to keep the entire display on one page.
+The @code{LD} macro allows the display to break across pages.
+The @code{DE} macro ends the display.
+@endDefmac
+
+@Defmac{DS, @t{I}, ms}
+@Defmacx{ID, , ms}
+@Defmacx{DE, , ms}
+Indents the display as defined by the @code{DI} register.
+The @samp{.DS I} call generates a page break, if necessary,
+to keep the entire display on one page.
+The @code{ID} macro allows the display to break across pages.
+The @code{DE} macro ends the display.
+@endDefmac
+
+@Defmac{DS, @t{B}, ms}
+@Defmacx{BD, , ms}
+@Defmacx{DE, , ms}
+Sets a block-centered display: the entire display is left-justified,
+but indented so that the longest line in the display is centered
+on the page.
+The @samp{.DS B} call generates a page break, if necessary,
+to keep the entire display on one page.
+The @code{BD} macro allows the display to break across pages.
+The @code{DE} macro ends the display.
+@endDefmac
+
+@Defmac{DS, @t{C}, ms}
+@Defmacx{CD, , ms}
+@Defmacx{DE, , ms}
+Sets a centered display: each line in the display is centered.
+The @samp{.DS C} call generates a page break, if necessary,
+to keep the entire display on one page.
+The @code{CD} macro allows the display to break across pages.
+The @code{DE} macro ends the display.
+@endDefmac
+
+@Defmac{DS, @t{R}, ms}
+@Defmacx{RD, , ms}
+@Defmacx{DE, , ms}
+Right-justifies each line in the display.
+The @samp{.DS R} call generates a page break, if necessary,
+to keep the entire display on one page.
+The @code{RD} macro allows the display to break across pages.
+The @code{DE} macro ends the display.
+@endDefmac
+
+@sp 1
+On occasion, you may want to @dfn{keep} other text together on a page.
+For example, you may want to keep two paragraphs together, or
+a paragraph that refers to a table (or list, or other item)
+immediately following.
+The @file{ms} macros provide the @code{KS} and @code{KE}
+macros for this purpose.
+
+@Defmac{KS, , ms}
+@Defmacx{KE, , ms}
+The @code{KS} macro begins a block of text to be kept on a
+single page, and the @code{KE} macro ends the block.
+@endDefmac
+
+@Defmac{KF, , ms}
+@Defmacx{KE, , ms}
+Specifies a @dfn{floating keep};
+if the keep cannot fit on the current page, @code{groff}
+holds the contents of the keep and allows text following
+the keep (in the source file) to fill in the remainder of
+the current page.
+When the page breaks, whether by an explicit @code{bp}
+request or by reaching the end of the page, @code{groff}
+prints the floating keep at the top of the new page.
+This is useful for printing large graphics or tables
+that do not need to appear exactly where specified.
+@endDefmac
+
+You can also use the @code{ne} request to force a page break if
+there is not enough vertical space remaining on the page.
+
+@sp 1
+Use the following macros to draw a box around a section of
+text (such as a display).
+
+@Defmac{B1, , ms}
+@Defmacx{B2, , ms}
+Marks the beginning and ending of text that is to have a
+box drawn around it.
+The @code{B1} macro begins the box; the @code{B2} macro ends it.
+Text in the box is automatically placed in a diversion (keep).
+@endDefmac
+
+@c ---------------------------------------------------------------------
+
+@node ms Insertions, Example multi-page table, ms Displays and Keeps, ms Body Text
+@subsubsection Tables, figures, equations, and references
+@cindex @file{ms}, tables
+@cindex @file{ms}, figures
+@cindex @file{ms}, equations
+@cindex @file{ms}, references
+@cindex Tables (ms)
+@cindex Figures (ms)
+@cindex Equations (ms)
+@cindex References (ms)
+
+The @file{ms} macros support the standard
+@code{groff} preprocessors:
+@code{tbl}, @code{pic}, @code{eqn}, and @code{refer}.
+@pindex tbl
+@pindex pic
+@pindex eqn
+@pindex refer
+You mark text meant for preprocessors by enclosing it
+in pairs of tags as follows.
+
+@Defmac{TS, [@code{H}], ms}
+@Defmacx{TE, , ms}
+Denotes a table, to be processed by the @code{tbl} preprocessor.
+The optional argument @code{H} to @code{TS} instructs @code{groff}
+to create a running header with the information
+up to the @code{TH} macro.
+@code{groff} prints the header at the beginning of the
+table; if the table runs onto another page, @code{groff}
+prints the header on the next page as well.
+@endDefmac
+
+@Defmac{PS, , ms}
+@Defmacx{PE, , ms}
+Denotes a graphic, to be processed by the @code{pic} preprocessor.
+You can create a @code{pic} file by hand, using the @acronym{AT&T}
+@code{pic} manual available on the Web as a reference, or by using
+a graphics program such as @code{xfig}.
+@endDefmac
+
+@Defmac{EQ, [@Var{align}], ms}
+@Defmacx{EN, , ms}
+Denotes an equation, to be processed by the @code{eqn} preprocessor.
+The optional @var{align} argument can be @code{C}, @code{L}, or
+@code{I} to center (the default), left-justify, or indent the equation.
+@endDefmac
+
+@Defmac{[, , ms}
+@Defmacx{], , ms}
+Denotes a reference, to be processed by the @code{refer} preprocessor.
+The @acronym{GNU} @cite{refer(1)} manpage provides a comprehensive
+reference to the preprocessor and the format of the bibliographic
+database.
+@endDefmac
+
+@menu
+* Example multi-page table::
+@end menu
+
+@c ---------------------------------------------------------------------
+
+@node Example multi-page table, ms Footnotes, ms Insertions, ms Insertions
+@subsubsection An example multi-page table
+@cindex Example markup, multi-page table (ms)
+@cindex Multi-page table, example markup (ms)
+
+The following is an example of how to set up a
+table that may print across two or more pages.
+
+@Example
+@cartouche
+.TS H
+allbox expand;
+cb | cb .
+Text      ...of heading...
+_
+.TH
+.T&
+l | l .
+... the rest of the table follows...
+.CW
+.TE
+@end cartouche
+@endExample
+
+@c ---------------------------------------------------------------------
+
+@node ms Footnotes, ms Page Layout, Example multi-page table, ms Body Text
+@subsubsection Footnotes
+@cindex @file{ms}, footnotes
+@cindex Footnotes (ms)
+
+The @file{ms} macro package has a flexible footnote system.
+You can specify either numbered footnotes or symbolic footnotes
+(that is, using a marker such as a dagger symbol).
+
+@Defstr{*, ms}
+Specifies the location of a numbered footnote marker in the text.
+@endDefesc
+
+@Defmac{FS, , ms}
+@Defmacx{FE, , ms}
+Specifies the text of the footnote.
+The default action is to create a numbered footnote;
+you can create a symbolic footnote by placing the character
+(such as @code{\[dg]} for the dagger character) at the proper location,
+followed by the symbol and the text of the footnote
+enclosed by @code{FS} and @code{FE} macros.
+@endDefmac
+
+You can control how @code{groff}
+prints footnote numbers by changing the value of the
+@code{FF} register.  @xref{ms Document Control Registers}.
+
+@c ---------------------------------------------------------------------
+
+@node ms Page Layout, ms Headers and Footers, ms Footnotes, ms
+@subsection Page layout
+@cindex @file{ms}, page layout
+@cindex Page layout (ms)
+
+The default output from the @file{ms}
+macros provides a minimalist page layout:
+it prints a single column, with the page number centered at the top
+of each page.
+It prints no footers.
+
+You can change the layout by setting
+the proper number registers and strings.
+
+@menu
+* ms Headers and Footers::
+* ms Margins::
+* ms Multiple Columns::
+* ms TOC::
+@end menu
+
+@c ---------------------------------------------------------------------
+
+@node ms Headers and Footers, ms Margins, ms Page Layout, ms Page Layout
+@subsubsection Headers and footers
+@cindex @file{ms}, headers
+@cindex @file{ms}, footers
+@cindex Headers (ms)
+@cindex Footers (ms)
+
+For documents that do not distinguish between odd and even pages,
+set the following strings:
+
+@Defstr{LH, ms}
+@Defstrx{CH, ms}
+@Defstrx{RH, ms}
+Sets the left, center, and right headers.
+@endDefstr
+
+@Defstr{LF, ms}
+@Defstrx{CF, ms}
+@Defstrx{RF, ms}
+Sets the left, center, and right footers.
+@endDefstr
+
+@sp 1
+For documents that need different information printed in the
+even and odd pages, use the following macros:
+
+@Defmac{OH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
+@Defmacx{EH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
+@Defmacx{OF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
+@Defmacx{EF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
+The @code{OH} and @code{EH} macros define headers for the odd and even pages;
+the @code{OF} and @code{EF} macros define footers for the odd and even pages.
+This is more flexible than defining the individual strings.
+
+You can replace the quote (@code{'}) marks with any character not
+appearing in the header or footer text.
+@endDefmac
+
+@c ---------------------------------------------------------------------
+
+@node ms Margins, ms Multiple Columns, ms Headers and Footers, ms Page Layout
+@subsubsection Margins
+@cindex @file{ms}, margins
+
+You control margins using a set of number registers.
+@xref{ms Document Control Registers}, for details.
+
+@c ---------------------------------------------------------------------
+
+@node ms Multiple Columns, ms TOC, ms Margins, ms Page Layout
+@subsubsection Multiple columns
+@cindex @file{ms}, multiple columns
+@cindex Multiple columns (ms)
+
+The @file{ms} macros can set text in as many columns as will
+reasonably fit on the page.
+The following macros are available;
+all of them force a page break if a multi-column mode is already set.
+However, if the current mode is single-column, starting a multi-column
+mode does @strong{not} force a page break.
+
+@Defmac{1C, , ms}
+Single-column mode.
+@endDefmac
+
+@Defmac{2C, , ms}
+Two-column mode.
+@endDefmac
+
+@Defmac{MC, [@Var{width} [@Var{gutter}]], ms}
+Multi-column mode.
+If you specify no arguments, it is equivalent to the
+@code{.2C} macro.
+Otherwise, @var{width} is the width of each column and
+@var{gutter} is the space between columns.
+The @code{MINGW} number register controls the default gutter width.
+@endDefmac
+
+@c ---------------------------------------------------------------------
+
+@node ms TOC, Differences from AT&T ms, ms Multiple Columns, ms Page Layout
+@subsubsection Creating a table of contents
+@cindex @file{ms}, creating table of contents
+@cindex Table of contents, creating (ms)
+
+The facilities in the @file{ms} macro package for creating
+a table of contents are semi-automated at best.
+Assuming that you want the table of contents to consist of
+the document's headings, you need to repeat those headings
+wrapped in @code{XS} and @code{XE} macros.
+
+@Defmac{XS, , ms}
+@Defmacx{XE, , ms}
+These macros bracket a table of contents entry.
+The macros are very simple; they cannot indent a heading based on its level.
+The easiest way to work around this is to add tabs
+to the table of contents string.
+The following is an example:
+
+@Example
+@cartouche
+.NH 1
+Introduction
+.XS
+Introduction
+.XE
+.LP
+...
+.CW
+.NH 2
+Methodology
+.XS
+	Methodology
+.XE
+.LP
+...
+@end cartouche
+@endExample
+@endDefmac
+
+@Defmac{TC, , ms}
+Prints the table of contents at the specified point.
+You should usually place this macro at the end of the
+file, since @code{groff} is a single-pass formatter and
+can only print what has been collected up to the point
+that the @code{TC} macro appears.
+@endDefmac
+
+The @cite{Groff and Friends HOWTO}
+includes a @code{sed} script that automatically inserts
+@code{XS} and @code{XE} macro entries after each heading in a document.
+
+Altering the @code{NH} macro to automatically build the table
+of contents is perhaps initially more difficult, but would save
+a great deal of time in the long run if you use @file{ms} regularly.
+
+@c ---------------------------------------------------------------------
+
+@node Differences from AT&T ms, Missing ms Macros, ms TOC, ms
+@subsection Differences from @acronym{AT&T} @file{ms}
+@cindex @file{ms}, differences from @acronym{AT&T}
+@cindex @acronym{AT&T}, @code{ms} differences
+
+This section lists the (minor) differences between the
+@code{groff -ms} macros and @acronym{AT&T}
+@code{troff -ms} macros.
+
+@menu
+* Missing ms Macros::
+* Additional ms Macros::
+@end menu
+
+@c ---------------------------------------------------------------------
+
+@node Missing ms Macros, Additional ms Macros, Differences from AT&T ms, Differences from AT&T ms
+@subsubsection @code{troff} macros not appearing in @code{groff}
+
+Macros missing from @code{groff -ms}
+are cover page macros specific to Bell Labs.
+The macros known to be missing are:
+
+@table @code
+@item .TM
+Technical memorandum; a cover sheet style
+
+@item .IM
+Internal memorandum; a cover sheet style
+
+@item .MR
+Memo for record; a cover sheet style
+
+@item .MF
+Memo for file; a cover sheet style
+
+@item .EG
+Engineer's notes; a cover sheet style
+
+@item .TR
+Computing Science Tech Report; a cover sheet style
+
+@item .OK
+Other keywords
+
+@item .CS
+Cover sheet information
+
+@item .MH
+A cover sheet macro
+@end table
+
+@c ---------------------------------------------------------------------
+
+@node Additional ms Macros, , Missing ms Macros, Differences from AT&T ms
+@subsubsection @code{groff} macros not appearing in AT&T @code{troff}
+
+The @code{groff -ms} macros have a few minor extensions
+compared to the @acronym{AT&T} @code{troff -ms} macros.
+
+@Defmac{AM, , ms}
+Improved accent marks.
+@endDefmac
+
+@Defmac{DS, @t{I}, ms}
+Indented display.
+The default behavior of @acronym{AT&T} @code{troff -ms}
+was to indent; the @code{groff} default prints displays
+flush left with the body text.
+@endDefmac
+
+@Defmac{CW, , ms}
+Print text in @code{constant width} (Courier) font.
+@endDefmac
+
+@Defmac{IX, , ms}
+Indexing term (printed on standard error).
+You can write a script to capture and process an index
+generated in this manner.
+@endDefmac
+
+@sp 1
+The following additional number registers
+appear in @code{groff -ms}:
+
+@Defmpreg{MINGW, ms}
+Specifies a minimum space
+between columns (for multi-column output); this takes the
+place of the @code{GW} register that was documented but apparently
+not implemented in @acronym{AT&T} @code{troff}.
+@endDefmpreg
+
+@sp 1
+Several new string registers are available as well.
+You can change these to handle (for example) the local language.
+
+@Defstr{REFERENCES, ms}
+Contains the string printed at the beginning of the
+references (bibliography) page.
+@endDefstr
+
+@Defstr{ABSTRACT, ms}
+Contains the string printed at the beginning of the abstract.
+@endDefstr
+
+@Defstr{TOC, ms}
+Contains the string printed at the beginning of the table of contents.
+@endDefstr
 
 
 @c =====================================================================
@@ -2416,6 +3675,9 @@ and automatically call the right preprocessor(s).
 @cindex @file{mm}
 
 @c XXX documentation
+@c XXX this is a placeholder until we get stuff knocked into shape
+See the @code{mm} manpage (type @command{man 7 groff_mm} at
+the command line).
 
 
 
@@ -7431,7 +8693,7 @@ The @code{als} request can make a macro have more than one name.
 This would be called as
 
 @Example
-.vl $Id: groff.texinfo,v 1.87 2001/12/16 23:47:26 wlemb Exp $
+.vl $Id: groff.texinfo,v 1.88 2002/01/05 21:22:13 wlemb Exp $
 @endExample
 @endDefesc
 
@@ -8125,7 +9387,8 @@ and @code{dl} contain the vertical and horizontal size of the diversion.
 @group
 .\" Center text both horizontally & vertically
 .
-.\" Enclose macro definitions in .eo and .ec to avoid the doubling of \
+.\" Enclose macro definitions in .eo and .ec
+.\" to avoid the doubling of the backslash
 .eo
 .\" macro .(c starts centering mode
 .de (c
diff --git a/font/devps/generate/textmap b/font/devps/generate/textmap
index 5b5e0ea8..56ef7af1 100644
--- a/font/devps/generate/textmap
+++ b/font/devps/generate/textmap
@@ -64,6 +64,7 @@ Ecircumflex ^E
 Edieresis :E
 Egrave `E
 Eth -D
+Euro Eu
 IJ IJ
 Iacute 'I
 Icircumflex ^I
diff --git a/font/devps/symbolmap b/font/devps/symbolmap
index 03d6e70b..10edc795 100644
--- a/font/devps/symbolmap
+++ b/font/devps/symbolmap
@@ -64,6 +64,7 @@ Ecircumflex ^E
 Edieresis :E
 Egrave `E
 Eth -D
+Euro Eu
 IJ IJ
 Iacute 'I
 Icircumflex ^I
diff --git a/font/devps/text.enc b/font/devps/text.enc
index dde5bb7c..ecb201f7 100644
--- a/font/devps/text.enc
+++ b/font/devps/text.enc
@@ -7,6 +7,7 @@ zcaron 5
 Ydieresis 6
 trademark 7
 quotesingle 8
+Euro 9
 space 32
 exclam 33
 quotedbl 34
diff --git a/man/roff.man b/man/roff.man
index 2550d8a5..4295be51 100644
--- a/man/roff.man
+++ b/man/roff.man
@@ -1,18 +1,18 @@
 .ig
 roff.man
 
-Last update: 23 nov 2001
+Last update: 02 Jan 2002
 
 This file is part of groff, the GNU roff type-setting system.
 
-Copyright (C) 2000, 2001 Free Software Foundation, Inc.
+Copyright (C) 2000, 2001, 2002 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
 any later version published by the Free Software Foundation; with the
-Invariant Sections being this .ig-section and AUTHOR, with no
+Invariant Sections being this .ig-section and AUTHORS, with no
 Front-Cover Texts, and with no Back-Cover Texts.
 
 A copy of the Free Documentation License is included as a file called
@@ -23,6 +23,10 @@ FDL in the main directory of the groff source package.
 .\" Setup
 .\" --------------------------------------------------------------------
 .
+.if \n[.g] \{\
+.  do mso www.tmac
+.\}
+.
 .mso www.tmac
 .
 .if n \{\
@@ -42,17 +46,11 @@ FDL in the main directory of the groff source package.
 .\" Begin of macro definitions
 .eo
 .
-.\"ig igURL
-.if d@URL \
-.  rm @URL
-.als @URL URL
-.rm URL
-.de URL
-.  ds @arg1 "\$1
-.  shift
-.  @URL "\fI\*[@arg1]\fP" \$@
-.  rm @arg1
-.\"igURL
+.de text
+.  nop \)\$*
+..
+.de ellipsis
+.  text .\|.\|.\&\"
 ..
 .de argname
 .  ds @arg1 \$1
@@ -72,14 +70,6 @@ FDL in the main directory of the groff source package.
 .  nop \fB\*[@arg1]\fP\$*
 .  rm @arg1
 ..
-.de prefixednumber
-.  ds @arg1 \$1
-.  ds @arg2 \$2
-.  shift 2
-.  nop \*[@arg1]\ \fR\*[@arg2]\fP\$*
-.  rm @arg1
-.  rm @arg2
-..
 .de quoted_char
 .  ds @arg1 \$1
 .  shift
@@ -91,8 +81,15 @@ FDL in the main directory of the groff source package.
 .ns
 .TP \$1
 ..
-.ec
+.\" --------------------------------------------------------------------
+.\" A shell command line
+.de ShellCommand
+.  br
+.  IR "shell>" "\h'1m'\f(CB\$*\fP\/"
+..
+.\" --------------------------------------------------------------------
 .\" End of macro definitions
+.ec
 .
 .
 .\" --------------------------------------------------------------------
@@ -101,7 +98,7 @@ FDL in the main directory of the groff source package.
 .
 .TH ROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
 .SH NAME
-roff \- a survey of the roff typesetting system
+roff \- introduction and overview of roff typesetting
 .
 .
 .\" --------------------------------------------------------------------
@@ -118,8 +115,12 @@ names like
 etc.
 .
 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.
+language and a set of programs for printing and converting to other
+text formats.
+.
+Traditionally, it is the main text processing system of Unix; every
+Unix-like operating system still distributes a roff system as a core
+package.
 .
 .P
 The most common roff system today is the free software implementation
@@ -130,44 +131,31 @@ The pre-groff implementations are referred to as
 .I classical
 (dating back as long as 1973).
 .
-.P
 .I groff
 implements the look-and-feel and functionality of its classical
 ancestors, but has many extensions.
 .
 As
 .I groff
-is available for almost every computer system it is the de-facto roff
-standard today.
+is the only roff system that is available for every (or 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 ),
+.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
+output has the same quality as other free type-setting programs and
 is better than some of the commercial systems.
+.
 .P
 This document gives only an overview and provides pointers to further
 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 roff
-relates to elements common to both the classical and the modern
-implementations, while
-.I groff
-includes the extensions as well.
-.
 .
 .\" --------------------------------------------------------------------
 .SH "HISTORY"
@@ -194,7 +182,7 @@ 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 ,
+.URL "Multics" http://\:www.multicians.org ,
 available from 1963.
 .
 Both operating systems could only be run on very expensive computers
@@ -208,7 +196,7 @@ 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
+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
@@ -222,7 +210,7 @@ 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
+There are still documents written in the runoff language; for examples
 see Saltzer's homepage (follow the links on the Multics web page).
 .
 .P
@@ -231,7 +219,8 @@ In the 1970s, the Multics off-spring
 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
+At MIT (the Massachusetts Institute of Technology), there was a need to
+drive the Wang
 .I Graphic Systems CAT
 typesetter, a graphical output device from a PDP-11 computer running
 Unix.
@@ -256,9 +245,9 @@ language.
 The C version was released in 1975.
 .
 .P
-This first roff system could produce output for only 2 devices:
+This first roff system could produce output for only 2\~devices:
 .B troff
-.RI ( "typesetter roff" )
+.RI ( "typesetter roff\/" )
 had a graphical output for the
 .I CAT
 typesetter as its only device, while
@@ -269,8 +258,9 @@ produced text output suitable for terminals or line printers.
 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.
+.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" .
@@ -279,7 +269,7 @@ All later
 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
+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
@@ -288,22 +278,22 @@ postprocessor system.
 .
 This completed the structure of a
 .I "roff system"
-as it is still in use today, see section
+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]" .
+.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.
+A major catastrophy occurred when the free Unix\~7 operating system was
+commercialized.
 .
-That's why there are now many different roff systems.
+A whole bunch of divergent operating systems emerged, fighting each
+other with incompatibilities, and finally causing 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
@@ -322,7 +312,7 @@ This name is an exaggeration.
 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
+The most important roff project was the GNU port of troff, created by
 James Clark.
 .
 It was called
@@ -346,46 +336,33 @@ This makes groff the de-facto roff standard today.
 .
 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.
+When you read a system manual page (man page) roff is working in the
+background.
+.
+Arbitrary roff documents can be viewed with a native roff viewer
+called
+.BR xditview (1x),
+a standard program of the
+.BR X (7x)
+window distribution.
 .
 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.
+Some roff implementations provide wrapper programs that make it easy
+to use the roff system on the shell command line.
 .
-For example, the GNU roff program
+For example, the GNU roff implementation
 .BR groff (@MAN1EXT@)
-has options for automatically calling preprocessors and a
-postprocessor; the program
+provides command line options to avoid the long command pipes of
+classical troff;
+a 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@).
+tries to guess from the document which arguments should be used
+for a run of groff; people who do not like specifying command line
+options should try the
+.BR groffer (@MAN1EXT@)
+program for graphically displaying groff files and man pages.
 .
 .
 .\" --------------------------------------------------------------------
@@ -402,10 +379,14 @@ 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
+.B cat
+.I file
+.ellipsis
+.B | preproc |
+.ellipsis
+.B | troff
+.I options
+.B | postproc
 .
 .P
 The preprocessors generate roff code that is fed into a roff formatter
@@ -440,17 +421,17 @@ 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
+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.
+There are a lot of free and commercial roff preprocessors.
 .
 Some of these aren't available on each system, but there is a small
-set of preprocessors that historically were considered part of the
+set of preprocessors that are considered as an integral part of each
 roff system.
 .
 The classical preprocessors are
@@ -459,52 +440,44 @@ The classical preprocessors are
 .RS
 .PD 0
 .TP
-.BR tbl
+.B tbl
 for tables
 .TP
-.BR eqn
+.B eqn
 for mathematical formul\(ae
 .TP
-.BR pic
+.B pic
 for drawing diagrams
 .TP
-.BR refer
+.B refer
 for bibliographic references
 .TP
-.BR soelim
+.B soelim
 for including macro files from standard locations
 .PD
 .RE
 .
 .P
-Other known preprocessors include
+Other known preprocessors that are not available on all systems
+include
 .
 .P
 .RS
 .PD 0
 .TP
-.I chem
-for drawing chemical formul\(ae
+.B chem
+for drawing chemical formul\(ae.
 .TP
-.I grap
-for constructing graphical elements
+.B grap
+for constructing graphical elements.
 .TP
-.I grn
-for including gremlin pictures
+.B grn
+for including
+.BR gremlin (1)
+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"
@@ -512,8 +485,8 @@ On this platform,
 .
 A
 .I roff formatter
-is a program that parses documents written in the roff
-formatting language or uses some of the roff macro packages.
+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" ,
@@ -524,6 +497,23 @@ The documents must have been run through all necessary preprocessors
 before.
 .
 .P
+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
+compared to the high-level roff language.
+.
+The generated intermediate output is optimized for a special device,
+but the language is the same for every device.
+.
+.P
 The roff formatter is the heart of the roff system.
 .
 The traditional roff had two formatters,
@@ -531,52 +521,53 @@ The traditional roff had two formatters,
 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 .
+Often, the name
+.I troff
+is used as a general term to refer to both formatters.
 .
 .
 .\" --------------------------------------------------------------------
-.SS "Postprocessing"
+.SS "Devices and Postprocessors"
 .\" --------------------------------------------------------------------
 .
-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.
+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
-The generated intermediate output is optimized for a special device,
-but the language is the same for every device.
+A roff postprocessor is a program that transforms troff output into a
+form suitable for a special 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.
+The roff postprocessors are like device drivers for the output target.
 .
-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
+For each device there is a postprocessor program that fits the device
+optimally.
+.
+The postprocessor parses the generated intermediate output and
+generates device-specific code that is sent directly to the device.
 .
 .P
-Of course, the devices have greatly changed since the classical
-times.
+The names of the devices and the postprocessor programs are not fixed
+because they greatly depend on the software and hardware abilities of
+the actual computer.
+.
+For example, the classical devices mentioned in
+.I [CSTR\~#54]
+have greatly changed since the classical times.
 .
 The old hardware doesn't exist any longer and the old graphical
-conversions weren't precise enough.
+conversions are quite imprecise as compared to their modern
+counterparts.
 .
+.P
 For example, the Postscript device
 .I post
 in classical troff had a resolution
-of 720, while groff
+of 720, while
+.IR groff 's
 .I ps
 has 72000, a refinement of factor 100.
 .
@@ -585,46 +576,6 @@ 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
-.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
-.BR grodvi (@MAN1EXT@)
-for the dvi format,
-.TP
-.BR grohtml (@MAN1EXT@)
-for html format,
-.TP
-.BR grops (@MAN1EXT@)
-for Postscript.
-.PD
-.RE
-.
-.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"
@@ -646,7 +597,7 @@ internals of the roff language.
 .
 .
 .\" --------------------------------------------------------------------
-.SH "MACRO PACKAGES"
+.SS "Macro Packages"
 .\" --------------------------------------------------------------------
 .
 Macro packages are collections of macros that are suitable to format a
@@ -672,36 +623,39 @@ 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
+.BR troff (@MAN1EXT@),
+or it 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 ,
-and
-.I doc
-for manual pages, and
-.IR me ,
-.IR ms ,
+.I man
+for traditional man pages,
+.I mdoc
+for BSD-style manual pages;
+the macro sets for books, articles, and letters are
+.I me
+(probably from the first name of its creator
+.I Eric
+Allman),
+.I ms
+(from
+.IR "Manuscript Macros\/" ),
 and
 .I mm
-for books, articles, and letters.
+(from
+.IR "Memorandum Macros\/" ).
 .
-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.
+The classical roff formatting language is documented in the
+.I Troff User's Manual
+.IR "[CSTR\~#54]" .
 .
-.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.
@@ -711,14 +665,14 @@ size registers, and flow controls.
 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.
+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
+macros; both are written on a line on their own starting with a dot
 .quoted_char . .
 .
 .P
@@ -758,15 +712,17 @@ 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"
 .\" --------------------------------------------------------------------
-Manual pages (man-pages) take the section number as a file name
+.
+Manual pages (man pages) take the section number as a file name
 extension, e.g., the filename for this document is
 .IR roff.7 ,
-i.e., it is kept in
-.prefixednumber section 7
-of the man-pages.
+i.e., it is kept in section\~7
+of the man pages.
 .
 .P
 The classical macro packages take the package name as an extension, e.g.
@@ -814,9 +770,11 @@ where
 .B lesspipe
 is either a system supplied command or a shell script of your own.
 .
+.
 .\" --------------------------------------------------------------------
 .SH "EDITING ROFF"
 .\" --------------------------------------------------------------------
+.
 The best program for editing a roff document is Emacs (or Xemacs), see
 .BR emacs (1).
 It provides an
@@ -827,7 +785,7 @@ 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" ',
+.RB ` "M-x nroff mode" ',
 where
 .B M-x
 means to hold down the
@@ -835,20 +793,20 @@ means to hold down the
 key (or
 .BR Alt )
 and hitting the
-.B x
-key at the same time.
+.BR 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.
+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
+Any file containing the character
 sequence
 .B \%-*-\ nroff\ -*-
-is switched into nroff-mode when loaded.
+in the first line is switched into nroff mode when loaded.
 .
 But do not use this, it confuses some applications such as the
 .B man
@@ -881,111 +839,34 @@ 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.
+or the empty request, a line consisting of 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.
+This is a sentence.
+.text .
+This is a longer sentence stretching over
+several lines.
+.text .
+etc.
 .fi
 .
 .P
-Besides Emacs, some other editors provide nroff style files too, e.g.
-.BR vim ,
+Besides Emacs, some other editors provide nroff style files too, e.g.\&
+.BR vim (1),
 an extension of the
-.B vi
+.BR vi (1)
 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
-macro files, see
-.BR groff_tmac (@MAN5EXT@).
-.TP
-.SM
-.B GROFF_TYPESETTER
-Default device.
-.TP
-.SM
-.B GROFF_FONT_PATH
-A colon-separated list of directories in which to search for the
-.BI dev name
-directory.
-.B troff
-will first search in directories given with the
-.option \-F
-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
-.I @FONTDIR@
-and in
-.I @MACRODIR@
-(except wrapper files for system-specific macro packages which will be
-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
-.IR <groff_macro_dir> .
-.TP
-.IB <groff_macro_dir> /troffrc
-Initialization file for troff.
-.TP
-.IB <groff_macro_dir> / name .tmac
-.TP+
-.IB <groff_macro_dir> /tmac. name
-Macro files.
-.TP
-.IB <groff_font_dir> /dev name /DESC
-Device description file for device
-.IR name .
-.TP
-.IB <groff_font_dir> /dev name / F
-Font file for font
-.I F
-of device
-.IR name .
-.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
 .\" --------------------------------------------------------------------
 .
-UNIX\(rg is a registered trademark of the Open Group.
-.
-.P
-The sections FILES and ENVIRONMENT should go to a different man-page.
+.I UNIX\[rg]
+is a registered trademark of the Open Group.
 .
 .
 .\" --------------------------------------------------------------------
@@ -1041,51 +922,31 @@ 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)
-command.
-.
-.
-.\" --------------------------------------------------------------------
 .SS "Manual Pages"
 .\" --------------------------------------------------------------------
 .
 The
 .I manual pages
 or shortly
-.I man-pages
+.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,
+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:
+A reference to a man page looks like this:
 .BR groff (@MAN7EXT@).
 .
-This refers to a manual page
+This refers to the manual page on
 .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
+To read the example, call from the shell prompt
 .
-.IP
-#
-.B man @MAN7EXT@ groff
+.P
+.ShellCommand man @MAN7EXT@ groff
 .
 .P
 For more details, see the documentation of the
@@ -1094,92 +955,26 @@ 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 \%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).
+For the different roff implementations, there is no general naming
+scheme for its documentation.
 .
+In
+.IR groff ,
+the man page
+.BR groff (@MAN1EXT@)
+contains a survey of all documentation available in groff.
 .
-.\" --------------------------------------------------------------------
-.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.
-.
-This also gives details on how to contact or join the
-.I groff
-developer group.
+On other systems, you are on your own, but
+.BR troff (1)
+might be a good starting point.
 .
 .
 .\" --------------------------------------------------------------------
 .SH AUTHORS
 .\" --------------------------------------------------------------------
 .
-Copyright (C) 1989, 2001 Free Software Foundation, Inc.
+Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc.
+.
 .P
 This document is distributed under the terms of the FDL (GNU Free
 Documentation License) version 1.1 or later.
@@ -1194,15 +989,15 @@ This document is part of
 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 .
+.MAILTO bwarken@mayn.de  "Bernd Warken" ;
+it is maintained by
+.MAILTO wl@gnu.org "Werner Lemberg" .
+.
 .
 .\" --------------------------------------------------------------------
 .\" Emacs setup
 .\" --------------------------------------------------------------------
+.
 .\" Local Variables:
 .\" mode: nroff
 .\" End: