* src/preproc/html/pre-html.cpp (usage): Don't describe options but

mention that it should never be called stand-alone.

* tmac/groff_www.man, doc/groff.texinfo, man/groff_font.man,
man/groff_tmac.man, man/groff_out.man, README, README.MinGW,
src/roff/groff/groff.man: Mention -Txhtml.

* man/groff_font.man, man/groff_tmac.man, man/roff.man: Revised.

4 files changed, 268 insertions, 250 deletions

diff --git a/man/groff_font.man b/man/groff_font.man
index 679bf7ab..2d93c333 100644
--- a/man/groff_font.man
+++ b/man/groff_font.man
@@ -1,5 +1,5 @@
 .ig
-Copyright (C) 1989-1995, 2001, 2002, 2003, 2004, 2006, 2007
+Copyright (C) 1989-1995, 2001, 2002, 2003, 2004, 2006, 2007, 2008
   Free Software Foundation, Inc.
 
 Permission is granted to make and distribute verbatim copies of
@@ -21,11 +21,6 @@ the original English.
 .do nr groff_font_C \n[.C]
 .cp 0
 .
-.de TQ
-.  br
-.  ns
-.  TP \\$1
-..
 .
 .\" Like TP, but if specified indent is more than half
 .\" the current line-length - indent, use the default indent.
@@ -55,9 +50,9 @@ are stored in a directory
 There are two types of file: a
 device description file called
 .B DESC
-and for each font
+and for each font\~\c
 .I F
-a font file called
+a font file called\~\c
 .IR F .
 .
 These are text files;
@@ -89,22 +84,22 @@ The default font family is
 .BI fonts\  n\ F1\ F2\ F3\ \|.\|.\|.\|\ Fn
 Fonts
 .IR F1 ,\ \|.\|.\|.,\  Fn
-are mounted in the font positions 
-.IR m +1,\ \|.\|.\|.,\  m + n
+are mounted in the font positions
+.IR m \|+\|1,\ \|.\|.\|.,\  m \|+\| n
 where
 .I m
 is the number of styles.
 .
 This command may extend over more than one line.
 .
-A font name of
+A font name of\~\c
 .B 0
 causes no font to be mounted on the corresponding font position.
 .
 .TP
 .BI hor\  n
 The horizontal resolution is
-.I n
+.IR n \~\c
 machine units.
 .
 .TP
@@ -200,7 +195,7 @@ itself but by output devices.
 Make troff tell the driver the source file name being processed.
 .
 This is achieved by another tcommand:
-.B F
+.BR F \~\c
 .IR filename .
 .
 .TP
@@ -236,7 +231,7 @@ There are
 machine units per inch.
 .
 .TP
-.BI sizes\  s1\ s2\ \|.\|.\|.\|\  sn\  0
+.BI sizes\  s1\ s2\ \|.\|.\|.\|\ sn\  0
 This means that the device has fonts at
 .IR s1 ,
 .IR s2 ,\ \|.\|.\|.,\  sn
@@ -254,7 +249,7 @@ The list can extend over more than one line.
 .
 .TP
 .BI sizescale\  n
-The scale factor for pointsizes.
+The scale factor for point sizes.
 .
 By default this has a value of 1.
 .
@@ -263,7 +258,7 @@ One
 scaled point
 is equal to
 one
-.RI point/ n .
+.RI point\|/\| n .
 .
 The arguments to the
 .B unitwidth
@@ -282,7 +277,7 @@ font positions are associated with styles
 .B tcommand
 This means that the postprocessor can handle the
 .B t
-and
+and\~\c
 .B u
 output commands.
 .
@@ -313,20 +308,21 @@ characters).
 .
 .IP
 This is used for
-.B \-Tutf8
+.BR \-Tutf8 ,
+.BR \-Thtml ,
 and
-.BR \-Thtml .
+.BR \-Txhtml .
 .
 .TP
 .BI unitwidth\  n
 Quantities in the font files are given in machine units
 for fonts whose point size is
-.I n 
+.IR n \~\c
 scaled points.
 .
 .TP
 .B unscaled_charwidths
-Make the font handling module always return unscaled character widths.
+Make the font handling module always return unscaled glyph widths.
 .
 Needed for the
 .B \%grohtml
@@ -334,13 +330,13 @@ device.
 .
 .TP
 .B use_charnames_in_special
-This command indicates that troff should encode named characters inside
+This command indicates that troff should encode named glyphs inside
 special commands.
 .
 .TP
 .BI vert\  n
 The vertical resolution is
-.I n
+.IR n \~\c
 machine units.
 .
 .LP
@@ -379,47 +375,48 @@ words give a value for that key.
 .
 .TP
 .BI ligatures\  lig1\ lig2\ \|.\|.\|.\|\ lign\ \fR[ 0 \fR]
-Characters
+Glyphs
 .IR lig1 ,
 .IR lig2 ,\ \|.\|.\|.,\  lign
 are ligatures; possible ligatures are
 .BR ff ,
 .BR fi ,
 .BR fl ,
-.B ffi
+.BR ffi ,
 and
 .BR ffl .
 .
 For backwards compatibility, the list of ligatures may be terminated
-with a
+with a\~\c
 .BR 0.
 .
 The list of ligatures may not extend over more than one line.
 .
 .TP
 .BI name\  F
-The name of the font is
+The name of the font is\~\c
 .IR F .
 .
 .TP
 .BI slant\  n
-The characters of the font have a slant of
-.I n
+The glyphs of the font have a slant of
+.IR n \~\c
 degrees.
 .
 (Positive means forward.)
 .
 .TP
 .BI spacewidth\  n
-The normal width of a space is
+The normal width of a space is\~\c
 .IR n .
 .
 .TP
 .B special
 The font is
 .IR special ;
-this means that when a character is requested that is not present in
-the current font, it is searched for in any special fonts that are mounted.
+this means that when a glyph is requested that is not present in
+the current font, it is searched for in any special fonts that are
+mounted.
 .
 .LP
 Other commands are ignored by
@@ -455,7 +452,7 @@ The
 .B charset
 line is followed by a sequence of lines.
 .
-Each line gives information for one character.
+Each line gives information for one glyph.
 .
 A line comprises a number of fields separated
 by blanks or tabs.
@@ -463,17 +460,17 @@ by blanks or tabs.
 The format is
 .
 .IP
-.I name metrics type code 
+.I name metrics type code
 .RI [ entity_name ]
-.RB [ --
+.RB [ \-\-
 .IR comment ]
 .
 .LP
 .I name
-identifies the character:
+identifies the glyph:
 if
 .I name
-is a single character
+is a single glyph
 .I c
 then it corresponds to the groff input character
 .IR c ;
@@ -492,60 +489,46 @@ it can be entered as
 .
 Note that single-letter special characters can't be accessed as
 .BI \[rs] c\fR;
-the only exception is `\[rs]-' which is identical to `\[rs][-]'.
+the only exception is `\[rs]\-' which is identical to `\[rs][\-]'.
 .
 The name
 .B \-\-\-
-is special and indicates that the character is unnamed;
-such characters can only be used by means of the
+is special and indicates that the glyph is unnamed;
+such glyphs can only be used by means of the
 .B \[rs]N
 escape sequence in
 .BR troff .
 .
 .LP
-Groff supports eight-bit characters; however some utilities
-have difficulties with eight-bit characters.
-.
-For this reason, there is a convention that the name
-.BI char n
-is equivalent to the single character whose code is
-.IR n .
-.
-For example,
-.B char163
-would be equivalent to the character with code 163
-which is the pounds sterling sign in ISO Latin-1.
-.
-.LP
 The
 .I type
-field gives the character type:
+field gives the glyph type:
 .
 .TP
 1
-means the character has a descender, for example, p;
+means the glyph has a descender, for example, `p';
 .
 .TP
 2
-means the character has an ascender, for example, b;
+means the glyph has an ascender, for example, `b';
 .
 .TP
 3
-means the character has both an ascender and a descender, for example,
-(.
+means the glyph has both an ascender and a descender, for example,
+`('.
 .
 .LP
 The
 .I code
-field gives the code which the postprocessor uses to print the character.
+field gives the code which the postprocessor uses to print the glyph.
 .
-The character can also be input to groff using this code by means of the
+The glyph can also be input to groff using this code by means of the
 .B \[rs]N
 escape sequence.
 .
 The code can be any integer.
 .
-If it starts with a
+If it starts with a\~\c
 .B 0
 it is interpreted as octal;
 if it starts with
@@ -561,8 +544,8 @@ escape sequence only accepts a decimal integer.
 .LP
 The
 .I entity_name
-field gives an ascii string identifying the glyph which the postprocessor
-uses to print the character.
+field gives an ASCII string identifying the glyph which the postprocessor
+uses to print that glyph.
 .
 This field is optional and is currently used by
 .B grops
@@ -575,7 +558,7 @@ into
 .BR \%grohtml .)
 .
 .LP
-Anything on the line after the encoding field or `-\&-' are ignored.
+Anything on the line after the encoding field or `\-\-' are ignored.
 .
 .LP
 The
@@ -595,7 +578,7 @@ readability):
 .LP
 There must not be any spaces between these subfields.
 .
-Missing subfields are assumed to be 0.
+Missing subfields are assumed to be\~0.
 .
 The subfields are all decimal integers.
 .
@@ -606,37 +589,37 @@ as they are in ditroff.
 .
 The
 .I width
-subfields gives the width of the character.
+subfields gives the width of the glyph.
 .
 The
 .I height
-subfield gives the height of the character (upwards is positive);
-if a character does not extend above the baseline, it should be
+subfield gives the height of the glyph (upwards is positive);
+if a glyph does not extend above the baseline, it should be
 given a zero height, rather than a negative height.
 .
 The
 .I depth
-subfield gives the depth of the character, that is, the distance
+subfield gives the depth of the glyph, that is, the distance
 below the lowest point below the baseline to which the
-character extends (downwards is positive);
-if a character does not extend below above the baseline, it should be
+glyph extends (downwards is positive);
+if a glyph does not extend below above the baseline, it should be
 given a zero depth, rather than a negative depth.
 .
 The
 .I italic-correction
 subfield gives the amount of space that should be added after the
-character when it is immediately to be followed by a character
+glyph when it is immediately to be followed by a glyph
 from a roman font.
 .
 The
 .I left-italic-correction
 subfield gives the amount of space that should be added before the
-character when it is immediately to be preceded by a character
+glyph when it is immediately to be preceded by a glyph
 from a roman font.
 .
 The
 .I subscript-correction
-gives the amount of space that should be added after a character
+gives the amount of space that should be added after a glyph
 before adding a subscript.
 .
 This should be less than the italic correction.
@@ -651,7 +634,7 @@ name \fB"
 .LP
 This indicates that
 .I name
-is just another name for the character mentioned in the
+is just another name for the glyph mentioned in the
 preceding line.
 .
 .LP
@@ -665,14 +648,14 @@ This contains a sequence of lines of the form:
 .I c1 c2 n
 .
 .LP
-This means that when character
+This means that when glyph
 .I c1
-appears next to character
+appears next to glyph
 .I c2
-the space between them should be increased by
+the space between them should be increased by\~\c
 .IR n .
 .
-Most entries in kernpairs section have a negative value for
+Most entries in kernpairs section have a negative value for\~\c
 .IR n .
 .
 .
@@ -685,7 +668,7 @@ Device description file for device
 .
 .TP
 .BI @FONTDIR@/dev name / F
-Font file for font
+Font file for font\~\c
 .I F
 of device
 .IR name .
diff --git a/man/groff_out.man b/man/groff_out.man
index 4b517892..94e832d1 100644
--- a/man/groff_out.man
+++ b/man/groff_out.man
@@ -41,7 +41,7 @@ after these commands, otherwise the position is not changed.
 .
 .nr @maxcolor 65536
 .ds @backslash \[rs]\"
-.ds @linebreak \fR\[la]line_break\[ra]\fP\"
+.ds @linebreak \fR\[la]line-break\[ra]\fP\"
 .
 .\" Begin of macro definitions
 .
@@ -73,7 +73,7 @@ after these commands, otherwise the position is not changed.
 .\" graphics command .D with a variable number of arguments
 .\" format: .D-multiarg <subcommand>
 .de D-multiarg
-\fBD\\$1\fP\ \*[hv1] \*[hv2] ... \*[hvn]\|\*[@linebreak]
+\fBD\\$1\fP\ \*[hv1] \*[hv2] .\|.\|. \*[hvn]\|\*[@linebreak]
 ..
 .\" format: .x-command <subname> "<arguments>"
 .de x-command
@@ -213,7 +213,7 @@ format can be quite small.
 .
 Its only elements are commands with or without arguments.
 .
-In this document, the term "command" always refers to the
+In this document, the term \[lq]command\[rq] always refers to the
 .I intermediate output
 language, never to the
 .I roff
@@ -350,11 +350,11 @@ file; see
 .
 .P
 Note that single characters can have the eighth bit set, as can the
-names of fonts and special characters.
+names of fonts and special characters (this is, glyphs).
 .
-The names of characters and fonts can be of arbitrary length.
+The names of glyphs and fonts can be of arbitrary length.
 .
-A character that is to be printed will always be in the current font.
+A glyph that is to be printed will always be in the current font.
 .
 .
 .P
@@ -402,7 +402,7 @@ is guaranteed to consist of the following three lines (in that order):
 with the arguments set as outlined in the section
 .BR "Device Control Commands" .
 .
-But the parser for the
+However, the parser for the
 .I intermediate output
 format is able to swallow additional whitespace and comments as well.
 .
@@ -459,7 +459,7 @@ extensions.
 .\" --------------------------------------------------------------------
 .
 .TP
-.BI # anything \[la]end_of_line\[ra]
+.BI # anything \[la]end-of-line\[ra]
 A comment.
 .
 Ignore any characters from the
@@ -524,28 +524,28 @@ stack as the actual device configuration data.
 .
 .
 .TP
-.command C xxx \[la]white_space\[ra]
-Print a special groff character named
+.command C xxx \[la]white-space\[ra]
+Print a glyph (special character) named
 .IR xxx .
 .
 The trailing
 .I syntactical space
 or
 .I line break
-is necessary to allow character names of arbitrary length.
+is necessary to allow glyph names of arbitrary length.
 .
-The character is printed at the current print position; the
-character's size is read from the font file.
+The glyph is printed at the current print position; the
+glyph's size is read from the font file.
 .
 The print position is not changed.
 .
 .
 .TP
 .command c c
-Print character\~\c
-.IR c
+Print glyph with single-letter name\~\c
+.I c
 at the current print position;
-the character's size is read from the font file.
+the glyph's size is read from the font file.
 .
 The print position is not changed.
 .
@@ -553,14 +553,14 @@ The print position is not changed.
 .TP
 .command f n
 Set font to font number\~\c
-.IR n
+.I n
 (a non-negative integer).
 .
 .
 .TP
 .command H n
 Move right to the absolute vertical position\~\c
-.IR n
+.I n
 (a non-negative integer in basic units\~\c
 .BR u )
 relative to left edge of current page.
@@ -569,9 +569,9 @@ relative to left edge of current page.
 .TP
 .command h n
 Move
-.IR n
+.I n
 (a non-negative integer) basic units\~\c
-.BR u
+.B u
 horizontally to the right.
 .
 .I [CSTR\~#54]
@@ -583,7 +583,7 @@ doesn't use this.
 .
 .
 .TP
-.command m "color_scheme \fR[\fPcomponent .\|.\|.\fR]\fP"
+.command m "color-scheme \fR[\fPcomponent .\|.\|.\fR]\fP"
 Set the color for text (glyphs), line drawing, and the outline of
 graphic objects using different color schemes; the analoguous command
 for the filling color of graphic objects is
@@ -644,20 +644,22 @@ red, green, and blue.
 .
 .TP
 .command N n
-Print character with index\~\c
-.IR n
+Print glyph with index\~\c
+.I n
 (an integer, normally non-negative) of the current font.
 .
 The print position is not changed.
 .
 If
 .B \-T\~html
+or
+.B \-T\~xhtml
 is used, negative values are emitted also to indicate an unbreakable space
 with given width.
 .
 For example,
-.B N\~-193
-represents an unbreakable space which has a width of 193u.
+.B N\~\-193
+represents an unbreakable space which has a width of 193\|u.
 .
 This command is a
 .I groff
@@ -673,9 +675,9 @@ In
 .I classical
 .IR troff ,
 the integer arguments
-.IR b
+.I b
 and\~\c
-.IR a
+.I a
 informed about the space before and after the current line to
 make the
 .I intermediate output
@@ -708,10 +710,10 @@ must be issued before any of these commands.
 .TP
 .command s n
 Set point size to
-.IR n
+.I n
 scaled points
 (this is unit\~\c
-.BR z
+.B z
 in GNU
 .BR @g@troff ).
 .
@@ -725,26 +727,29 @@ instead; see section
 .
 .
 .TP
-.command t xxx \[la]white_space\[ra]
+.command t xyz\|.\|.\|. \[la]white-space\[ra]
 .TQ
-.command t "xxx dummy_arg" \[la]white_space\[ra]
-Print a word, i.e., a sequence of characters
-.IR xxx
-terminated by a space character or a line break; an optional second
-integer argument is ignored (this allows the formatter to generate
-an even number of arguments).
-.
-The first character should be printed at the current position, the
+.command t "xyz\|.\|.\|.\& dummy-arg" \[la]white-space\[ra]
+Print a word, i.e., a sequence of glyphs with single-letter names
+.IR x ,
+.IR y ,
+.IR z ,
+etc., terminated by a space character or a line break; an optional
+second integer argument is ignored (this allows the formatter to
+generate an even number of arguments).
+.
+The first glyph should be printed at the current position, the
 current horizontal position should then be increased by the width of
-the first character, and so on for each character.
+the first glyph, and so on for each glyph.
 .
-The widths of the characters are read from the font file, scaled for the
+The widths of the glyph are read from the font file, scaled for the
 current point size, and rounded to a multiple of the horizontal
 resolution.
 .
-Special characters cannot be printed using this command (use the
+Special characters (glyphs with names longer than a single letter)
+cannot be printed using this command; use the
 .B C
-command for named characters).
+command for those glyphs.
 .
 This command is a
 .I groff
@@ -757,15 +762,15 @@ keyword; see
 .
 .
 .TP
-.command u "n xxx" \[la]white_space\[ra]
+.command u "n xyz\|.\|.\|." \[la]white-space\[ra]
 Print word with track kerning.
 .
 This is the same as the
 .B t
-command except that after printing each character, the current
+command except that after printing each glyph, the current
 horizontal position is increased by the sum of the width of that
-character and\~\c
-.IR n
+glyph and\~\c
+.I n
 (an integer in
 basic units\~\c
 .BR u ).
@@ -782,7 +787,7 @@ keyword; see
 .TP
 .command V n
 Move down to the absolute vertical position\~\c
-.IR n
+.I n
 (a non-negative integer in basic units\~\c
 .BR u )
 relative to upper edge of current page.
@@ -791,9 +796,9 @@ relative to upper edge of current page.
 .TP
 .command v n
 Move
-.IR n
+.I n
 basic units\~\c
-.BR u
+.B u
 down
 .RI ( n
 is a non-negative integer).
@@ -855,13 +860,13 @@ units\~\c
 .BR u .
 .
 The 
-.I h 
+.I h
 arguments
 stand for horizontal distances where positive means right, negative
 left.
 .
 The 
-.I v 
+.I v
 arguments
 stand for vertical distances where positive means down, negative up.
 .
@@ -888,7 +893,7 @@ sent to the postprocessor.
 .
 .P
 In the following command reference, the syntax element
-.I \[la]line_break\[ra]
+.I \[la]line-break\[ra]
 means a
 .I syntactical line break
 as defined in section
@@ -901,7 +906,7 @@ Draw B-spline from current position to offset
 .indexed_offset h 1 v 1 ,
 then to offset
 .indexed_offset h 2 v 2
-if given, etc.\& up to
+if given, etc., up to
 .indexed_offset h n v n .
 This command takes a variable number of argument pairs; the current
 position is moved to the terminal point of the drawn curve.
@@ -920,9 +925,9 @@ then move the current position to the final point of the arc.
 .TP
 .D-command C d
 .TQ
-.D-command C "d dummy_arg"
+.D-command C "d dummy-arg"
 Draw a solid circle using the current fill color with diameter\~\c
-.IR d
+.I d
 (integer in basic units\~\c
 .BR u )
 with leftmost point at the current position; then move the current
@@ -939,7 +944,7 @@ extension.
 .TP
 .D-command c d
 Draw circle line with diameter\~\c
-.IR d
+.I d
 (integer in basic units\~\c
 .BR u )
 with leftmost point at the current position; then move the current
@@ -950,9 +955,9 @@ position to the rightmost point of the circle.
 .D-command E "h v"
 Draw a solid ellipse in the current fill color with a horizontal
 diameter of\~\c
-.IR h
+.I h
 and a vertical diameter of\~\c
-.IR v
+.I v
 (both integers in basic units\~\c
 .BR u )
 with the leftmost point at the current position; then move to the
@@ -966,9 +971,9 @@ extension.
 .TP
 .D-command e "h v"
 Draw an outlined ellipse with a horizontal diameter of\~\c
-.IR h
+.I h
 and a vertical diameter of\~\c
-.IR v
+.I v
 (both integers in basic units\~\c
 .BR u )
 with the leftmost point at current position; then move to the
@@ -976,7 +981,7 @@ rightmost point of the ellipse.
 .
 .
 .TP
-.D-command F "color_scheme \fR[\fPcomponent .\|.\|.\fR]\fP"
+.D-command F "color-scheme \fR[\fPcomponent .\|.\|.\fR]\fP"
 Set fill color for solid drawing objects using different color
 schemes; the analoguous command for setting the color of text, line
 graphics, and the outline of graphic objects is
@@ -991,7 +996,7 @@ different color schemes.
 These commands are generated by the
 .I groff
 escape sequences
-.B \*[@backslash]D'F\ .\|.\|.'
+.BR \*[@backslash]D'F\  .\|.\|. '
 and
 .B \*[@backslash]M
 (with no other corresponding graphics commands).
@@ -1041,38 +1046,35 @@ having the 3\~color components red, green, and blue.
 .TP
 .D-command f n
 The argument
-.IR n
+.I n
 must be an integer in the range -32767 to 32767.
 .
 .RS
 .TP
-.RI "0 \[<=] " n " \[<=] 1000"
+.RI 0\|\[<=]\| n \|\[<=]\|1000
 Set the color for filling solid drawing objects to a shade of gray,
 where 0 corresponds to solid white, 1000 (the default) to solid black,
-and values in between to intermediate shades of gray; this is
+and values inbetween to intermediate shades of gray; this is
 obsoleted by command
 .BR DFg .
 .
 .TP
-.IR n " < 0 or " n " > 1000"
+.IR n "\|<\|0 or " n \|>\|1000
 Set the filling color to the color that is currently being used for
 the text and the outline, see command
 .BR m .
 For example, the command sequence
 .
-.nf
-.ft CB
-.RS
 .RS
+.IP
+.EX
 mg 0 0 \n[@maxcolor]
 Df -1
+.EE
 .RE
-.ft
-.fi
 .
+.IP
 sets all colors to blue.
-.RE
-.
 .
 .P
 No position changing.
@@ -1096,11 +1098,11 @@ then set current position to the end of the drawn line.
 .TP
 .D-multiarg p
 Draw a polygon line from current position to offset
-.offset h1 v1 ,
+.indexed_offset h 1 v 1 ,
 from there to offset
-.offset h2 v2 ,
-etc.\& up to offset
-.offset hn vn ,
+.indexed_offset h 2 v 2 ,
+etc., up to offset
+.indexed_offset h n v n ,
 and from there back to the starting position.
 .
 .ie \n[@STUPID_DRAWING_POSITIONING]=1 \{\
@@ -1143,15 +1145,15 @@ extension.
 .TP
 .D-command t n
 Set the current line thickness to\~\c
-.IR n
+.I n
 (an integer in basic units\~\c
 .BR u )
 if
-.IR n >0;
+.IR n \|>\|0;
 if
-.IR n =0
+.IR n \|=\|0
 select the smallest available line thickness; if
-.IR n <0
+.IR n \|<\|0
 set the line thickness proportional to the point size (this is the
 default before the first
 .B Dt
@@ -1215,11 +1217,11 @@ But writings like
 .B x\ i_like_groff
 and
 .B x\ roff_is_groff
-resp.\& are accepted as well to mean the same commands.
+are accepted as well to mean the same commands.
 .
 .P
 In the following, the syntax element
-.I \[la]line_break\[ra]
+.I \[la]line-break\[ra]
 means a
 .I syntactical line break
 as defined in section
@@ -1229,7 +1231,7 @@ as defined in section
 .x-command F name
 .xsub Filename
 Use
-.IR name
+.I name
 as the intended name for the current file in error reports.
 .
 This is useful for remembering the original file name when
@@ -1247,9 +1249,9 @@ extension.
 .x-command f "n\ s"
 .xsub font
 Mount font position\~\c
-.IR n
+.I n
 (a non-negative integer) with font named\~\c
-.IR s
+.I s
 (a text word),
 cf.
 .BR groff_font (@MAN5EXT@).
@@ -1259,7 +1261,7 @@ cf.
 .x-command H n
 .xsub Height
 Set character height to\~\c
-.IR n
+.I n
 (a positive integer in scaled points\~\c
 .BR z ).
 .
@@ -1295,12 +1297,12 @@ The classical documentation reads
 Resolution is\~\c
 .IR n ,
 while
-.IR h
+.I h
 is the minimal horizontal motion, and
-.IR v
+.I v
 the minimal vertical motion possible with this device; all arguments
 are positive integers in basic units\~\c
-.BR u
+.B u
 per inch.
 .
 This is the second command of the
@@ -1311,7 +1313,7 @@ This is the second command of the
 .x-command S n
 .xsub Slant
 Set slant to\~\c
-.IR n
+.I n
 degrees (an integer in basic units\~\c
 .BR u ).
 .
@@ -1343,7 +1345,7 @@ Set name of device to word
 a sequence of characters ended by the next whitespace character.
 .
 The possible device names coincide with those from the groff
-.B -T
+.B \-T
 option.
 .
 This is the first command of the
@@ -1356,10 +1358,10 @@ This is the first command of the
 Configure underlining of spaces.
 .
 If
-.IR n
+.I n
 is\~1, start underlining of spaces;
 if
-.IR n
+.I n
 is\~0, stop underlining of spaces.
 .
 This is needed for the
@@ -1377,7 +1379,7 @@ extension.
 .x-command X anything
 .xsub X-escape
 Send string
-.IR anything
+.I anything
 uninterpreted to the device.
 .
 If the line following this command starts with a
@@ -1411,20 +1413,20 @@ extension.
 .
 In
 .I classical troff
-output, the writing of a single character was mostly done by a very
+output, emitting a single glyph was mostly done by a very
 strange command that combined a horizontal move and the printing of a
-character.
+glyph.
 .
 It didn't have a command code, but is represented by a 3-character
 argument consisting of exactly 2\~digits and a character.
 .
 .TP
-.IR ddc
+.I ddc
 Move right
-.IR dd
+.I dd
 (exactly two decimal digits) basic units\~\c
 .BR u ,
-then print character\~\c
+then print glyph with single-letter name\~\c
 .IR c .
 .
 .
@@ -1450,7 +1452,7 @@ spaces; this made such output almost unreadable.
 .
 .P
 For modern high-resolution devices, this command does not make sense
-because the width of the characters can become much larger than two
+because the width of the glyphs can become much larger than two
 decimal digits.
 .
 In
@@ -1744,7 +1746,7 @@ The argument of the commands
 and
 .B x H
 has the implicit unit scaled point\~\c
-.BR z
+.B z
 in
 .IR groff ,
 while
@@ -1822,15 +1824,14 @@ Device description file for device
 .IR name .
 .
 .TP
-.IB \[la]groff_source_dir\[ra] /src/libs/libdriver/input.cpp
+.IB \[la]groff-source-dir\[ra] /src/libs/libdriver/input.cpp
 Defines the parser and postprocessor for the
 .I intermediate
 .IR output .
 .
 It is located relative to the top directory of the
 .I groff
-source tree, e.g.
-.IR @GROFFSRCDIR@ .
+source tree.
 .
 This parser is the definitive specification of the
 .I groff intermediate output
@@ -1981,7 +1982,7 @@ CSTR\~#54
 .SH "AUTHORS"
 .\" --------------------------------------------------------------------
 .
-Copyright (C) 1989, 2001, 2002, 2003, 2004, 2005, 2006, 2007
+Copyright (C) 1989, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
 Free Software Foundation, Inc.
 .
 .
diff --git a/man/groff_tmac.man b/man/groff_tmac.man
index b93a7894..9f6e5a62 100644
--- a/man/groff_tmac.man
+++ b/man/groff_tmac.man
@@ -334,6 +334,7 @@ orientation:
 .
 .IP
 .EX
+.SM
 \fIsh#\fP groff \-Tps \-dpaper=a4l \-P\-pa4 \-P\-l \-ms foo.ms > foo.ps
 .EE
 .
@@ -363,8 +364,9 @@ to include a PostScript graphic in a document.
 The following output devices support inclusion of PS images:
 .BR \-Tps ,
 .BR \-Tdvi ,
+.BR \-Thtml ,
 and
-.BR \-Thtml ;
+.BR \-Txhtml ;
 for all other devices the image is replaced with a hollow rectangle
 of the same size.
 .
@@ -376,7 +378,7 @@ so it isn't necessary to call it explicitly.
 Syntax:
 .RS
 .IP
-\&\fB.PSPIC\fP [\fB\-L\fP\||\|\fB-R\fP\||\|\fB\-I\fP\ \fIn\fP] \
+\&\fB.PSPIC\fP [\fB\-L\fP\||\|\fB\-R\fP\||\|\fB\-I\fP\ \fIn\fP] \
 \fI\|file\fP [\fIwidth\fP [\fIheight\fP]]
 .RE
 .
@@ -440,7 +442,7 @@ covers the image's width.
 .EX
 \&.am PSPIC
 \&.\ \ vpt 0
-\&\eh'(\e\en[ps-offset]u + \e\en[ps-deswid]u)'
+\&\[rs]h'(\[rs]\[rs]n[ps-offset]u + \[rs]\[rs]n[ps-deswid]u)'
 \&.\ \ sp -1
 \&.\ \ vpt 1
 \&..
@@ -461,15 +463,15 @@ See
 .TP
 .B tty-char
 Overrides the definition of standard troff characters and some groff
-characters for tty devices.
+characters for TTY devices.
 .
 The optical appearance is intentionally inferior compared to that of
-normal tty formatting to allow processing with critical equipment.
+normal TTY formatting to allow processing with critical equipment.
 .
 .
 .TP
 .B www
-Additions of elements known from the html format, as used in the
+Additions of elements known from the HTML format, as used in the
 internet (World Wide Web) pages; this includes URL links and mail
 addresses; see
 .BR groff_www (@MAN7EXT@).
@@ -568,7 +570,7 @@ would not make much sense.
 .
 .P
 A second strange feature of classical troff was to name macro files
-in the form \fBtmac.\fIname\fR.
+in the form \f[B]tmac.\f[]\f[I]name\f[].
 In modern operating systems, the type of a file is specified as a
 postfix, the file name extension.
 .
@@ -654,7 +656,11 @@ calls soelim automatically.
 .
 .P
 For example, suppose a macro file is stored as
+.
+.IP
 .I @MACRODIR@/macros.tmac
+.
+.P
 and is used in some document called
 .IR docu.roff .
 .
@@ -664,7 +670,7 @@ At run-time, the formatter call for this is
 .
 .IP
 .EX
-\fIsh#\fP groff\ \-m\ \fImacrofile\ document.roff\fP
+\fIsh#\fP groff \-m macros docu.roff
 .EE
 .
 .
@@ -673,7 +679,7 @@ To include the macro file directly in the document either
 .
 .IP
 .EX
-\&.mso macrofile.tmac
+\&.mso macros.tmac
 .EE
 .
 .P
@@ -686,10 +692,13 @@ is used or
 .
 .
 .P
-In both cases, the formatter is called with
+In both cases, the formatter should be called with option
+.B \-s
+to invoke
+.BR soelim .
 .IP
 .EX
-\fIsh#\fP groff\ \-s\ \fIdocu.roff\fP
+\fIsh#\fP groff \-s docu.roff
 .EE
 .
 .
@@ -796,17 +805,17 @@ macro call.
 .
 Within the macro definition, the arguments are available as the escape
 sequences
-.BR $1 ,
+.BR \[rs]$1 ,
 \*[Ellipsis],
-.BR $9 ,
-.BR $[ \*[Ellipsis] ] ,
-.BR $* ,
+.BR \[rs]$9 ,
+.BR \[rs]$[ \*[Ellipsis] ] ,
+.BR \[rs]$* ,
 and
-.BR $@ ,
+.BR \[rs]$@ ,
 the name under which the macro was called is in
-.BR $0 ,
+.BR \[rs]$0 ,
 and the number of arguments is in register
-.BR \en[.$] ;
+.BR \[rs]n[.$] ;
 see
 .BR groff (@MAN7EXT@).
 .
@@ -817,6 +826,8 @@ see
 .
 The phase when groff reads a macro is called
 .I "copy-in mode"
+or
+.I "copy mode"
 in roff-talk.
 .
 This is comparable to the C\~preprocessing phase during the development
@@ -828,7 +839,7 @@ In this phase, groff interprets all backslashes; that means that all
 escape sequences in the macro body are interpreted and replaced by
 their value.
 .
-For constant expression, this is wanted, but strings and registers
+For constant expressions, this is wanted, but strings and registers
 that might change between calls of the macro must be protected from
 being evaluated.
 .
@@ -843,13 +854,13 @@ say.
 .
 .
 .IP
-.ds @1 \ef[I]\e\e$0\ef[]\"
+.ds @1 \[rs]f[I]\[rs]\[rs]$0\[rs]f[]\"
 .ds @2 arguments:\"
 .EX
 \&.ds midpart was called with
 \&.de print_args
-\&.\ \ tm\ \*[@1]\ \e\e*[midpart]\ \e\en[.$]\ \*[@2]
-\&.\ \ tm\ \e\e$*
+\&.\ \ tm\ \*[@1]\ \[rs]*[midpart]\ \[rs]\[rs]n[.$]\ \*[@2]
+\&.\ \ tm\ \[rs]\[rs]$*
 \&..
 .EE
 .rm @1
@@ -880,28 +891,28 @@ Let's analyze each backslash in the macro definition.
 As the positional parameters and the number of arguments change
 with each call of the macro their leading backslash must be doubled,
 which results in
-.I \e\e$*
+.I \[rs]\[rs]$*
 and
-.IR \e\e[.$] .
+.IR \[rs]\[rs][.$] .
 The same applies to the macro name because it could be called with an
 alias name, so
-.IR \e\e$0 .
+.IR \[rs]\[rs]$0 .
 .
 .
 .P
 On the other hand,
 .I midpart
 is a constant string, it does not change, so no doubling for
-.IR \e*[midpart] .
+.IR \[rs]*[midpart] .
 The
-.I \ef
+.I \[rs]f
 escape sequences are predefined groff elements for setting the font
 within the text.
 .
 Of course, this behavior does not change, so no doubling with
-.I \ef[I]
+.I \[rs]f[I]
 and
-.IR \ef[] .
+.IR \[rs]f[] .
 .
 .
 .\" --------------------------------------------------------------------
@@ -926,14 +937,14 @@ For example, the code above can be written in a simpler way by
 .
 .
 .IP
-.ds @1 \ef[I]\e$0\ef[]\"
+.ds @1 \[rs]f[I]\[rs]$0\[rs]f[]\"
 .ds @2 arguments:\"
 .EX
 \&.eo
 \&.ds midpart was called with
 \&.de print_args
-\&.\ \ tm\ \*[@1]\ \e*[midpart]\ \en[.$]\ \*[@2]
-\&.\ \ tm\ \e$*
+\&.\ \ tm\ \*[@1]\ \[rs]*[midpart]\ \[rs]n[.$]\ \*[@2]
+\&.\ \ tm\ \[rs]$*
 \&..
 \&.ec
 .EE
@@ -968,9 +979,9 @@ with a leading dot.
 .IP
 .EX
 \&.de Text
-\&.\ \ if (\e\en[.$] == 0)\ \e
+\&.\ \ if (\[rs]\[rs]n[.$] == 0)\ \[rs]
 \&.\ \ \ \ return
-\&.\ \ nop\ \e)\e\e$*[rs]\)
+\&.\ \ nop\ \[rs])\[rs]\[rs]$*\[rs])
 \&..
 .EE
 .RE
@@ -993,8 +1004,9 @@ acts like a comment line:
 .RE
 .
 .IP \(bu
-In long macro definitions, make ample use of comment lines or empty
-lines for a better structuring.
+In long macro definitions, make ample use of comment lines or
+almost-empty lines (this is, lines which have a leading dot
+and nothing else) for a better structuring.
 .
 .IP \(bu
 To increase readability, use groff's indentation facility for requests
@@ -1016,8 +1028,8 @@ C\~programming language, but their usage is quite different.
 In their simplest form, diversions are multi-line strings, but
 they get their power when diversions are used dynamically within macros.
 .
-The information stored in a diversion can be retrieved by calling the
-diversion just like a macro.
+The (formatted) information stored in a diversion can be retrieved by
+calling the diversion just like a macro.
 .
 .
 .P
@@ -1099,17 +1111,35 @@ the home directory
 .
 .IP \(bu
 a platform-specific directory, being
+.
+.RS
+.IP
 .B @SYSTEMMACRODIR@
+.RE
+.
+.IP
 in this installation
 .
 .IP \(bu
 a site-specific (platform-independent) directory, being
+.
+.RS
+.IP
 .B @LOCALMACRODIR@
+.RE
+.
+.IP
 in this installation
 .
 .IP \(bu
 the main tmac directory, being
+.
+.RS
+.IP
 .B @MACRODIR@
+.RE
+.
+.IP
 in this installation
 .
 .
@@ -1129,7 +1159,7 @@ See the previous section for a detailed description.
 .SH AUTHOR
 .\" --------------------------------------------------------------------
 .
-Copyright (C) 2000, 2001, 2002, 2003, 2004, 2006, 2007
+Copyright (C) 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008
 Free Software Foundation, Inc.
 .
 .P
diff --git a/man/roff.man b/man/roff.man
index 44413469..68fd021a 100644
--- a/man/roff.man
+++ b/man/roff.man
@@ -98,6 +98,7 @@ of the
 .I Multics
 operating system, cf.\& section
 .BR HISTORY .
+.
 The functionality of this program was very restricted even in
 comparison to ancient
 .IR troff ;
@@ -223,7 +224,9 @@ perform the typesetting manually later on.
 The runoff program was written in the
 .I MAD
 language first, later on in
-.IR BCPL ,
+.I BCPL
+(by
+.IR "Doug McIlroy" ),
 the grandmother of the
 .IR C \~\c
 programming language.
@@ -251,17 +254,24 @@ 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. Ossanna" ,
+.I Ken Thompson
+rewrote runoff for the PDP-11; however, as runoff was too limited for
+the CAT it was further developed into the more powerful
+.I nroff and
+.I troff
+programs by
+.IR "Joseph F.\& Ossanna" ,
 who already programmed several runoff ports.
 .
+On the hardware side, Ossanna wired the nominal paper-tape reader of
+the CAT straight into the PDP-11.
+.
 .P
 The name
 .I runoff
 was shortened to
 .IR roff .
+.
 The greatly enlarged language of Ossanna's concept included already all
 elements of a full
 .IR "roff system" .
@@ -324,6 +334,7 @@ Kernighan.
 .
 This document is the specification of the
 .IR "classical troff" .
+.
 All later
 .I roff
 systems tried to establish compatibility with this specification.
@@ -345,6 +356,7 @@ as it is still in use today; see section
 .
 In 1979, these novelties were described in the paper
 .IR "[CSTR\~#97]" .
+.
 This new
 .I troff
 version is the basis for all existing newer
@@ -386,12 +398,10 @@ minor additions.
 .P
 The source code of both the ancient Unix and classical
 .I troff
-weren't available for two decades.
-.
-Fortunately, Caldera bought SCO UNIX in 2001.
+wasn't available for two decades.
 .
-In the following, Caldera made the ancient source code accessible
-on-line for non-commercial use, cf. section
+Meanwhile, it is accessible again (on-line) for non-commercial use,
+cf.\& section
 .BR "SEE ALSO" .
 .
 .
@@ -412,6 +422,7 @@ It was called
 .I groff
 (\f[CR]GNU\f[]
 .IR roff ).
+.
 See
 .BR groff (@MAN1EXT@)
 for an overview.
@@ -651,6 +662,7 @@ 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 \f[CR]GNU\f[] extension is documented in
@@ -729,7 +741,7 @@ For example, the Postscript device
 .I post
 in classical
 .I troff
-had a resolution of 720, while
+had a resolution of 720 units per inch, while
 .IR groff 's
 .I ps
 device has 72000, a refinement of factor 100.
@@ -859,6 +871,7 @@ are
 .I roff
 elements starting with a backslash
 .QuotedChar \[rs] .
+.
 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
@@ -943,6 +956,7 @@ pager.
 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:
 .
 .RS
@@ -966,6 +980,7 @@ The best program for editing a
 .I roff
 document is Emacs (or Xemacs), see
 .BR emacs (1).
+.
 It provides an
 .I nroff
 mode that is suitable for all kinds of
@@ -1044,7 +1059,7 @@ document.
 .
 Instead, use the empty request (a line consisting of a dot only) or a
 line comment
-.B .\e"
+.B .\[rs]"
 if a structuring element is needed.
 .
 .IP \(bu
@@ -1103,17 +1118,6 @@ program.
 .
 .
 .\" --------------------------------------------------------------------
-.SH BUGS
-.\" --------------------------------------------------------------------
-.
-.I UNIX\[rg]
-is a registered trademark of the Open Group.
-.
-But things have improved considerably after Caldera had bought SCO
-UNIX in 2001.
-.
-.
-.\" --------------------------------------------------------------------
 .SH "SEE ALSO"
 .\" --------------------------------------------------------------------
 .
@@ -1310,7 +1314,7 @@ might be a good starting point.
 .SH AUTHORS
 .\" --------------------------------------------------------------------
 .
-Copyright (C) 2000, 2001, 2002, 2003, 2004, 2006, 2007
+Copyright (C) 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008
 Free Software Foundation, Inc.
 .
 .P