* src/devices/grops/grops.man, src/roff/troff/troff.man,

src/preproc/soelim/soelim.man: Correct documentation of -I switch.
Reported by Larry Kollar.
Other minor formatting issues.

5 files changed, 94 insertions, 70 deletions

diff --git a/ChangeLog b/ChangeLog
index 329bc2b8c..e7974fef5 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,4 +1,11 @@
-2008-10-09  Werner LEMBERG  <wl@gnu.org>
+2008-10-03  Werner LEMBERG  <wl@gnu.org>
+
+	* src/devices/grops/grops.man, src/roff/troff/troff.man,
+	src/preproc/soelim/soelim.man: Correct documentation of -I switch. 
+	Reported by Larry Kollar.
+	Other minor formatting issues.
+
+2008-10-02  Werner LEMBERG  <wl@gnu.org>
 
 	* tmac/trace.tmac: Much improved.
 	(trace-full): New register to be set on the command line; it
diff --git a/doc/pic.ms b/doc/pic.ms
index 877c364af..36d3f7cad 100644
--- a/doc/pic.ms
+++ b/doc/pic.ms
@@ -611,8 +611,8 @@ Revert to previous style; only works one level deep, does not stack.
 .PP
 In the \fBpic\fP implementations that are preprocessors for a
 toolchain that include \fB[gtn]roff\fP, text objects may also contain
-\fB[gtn]roff\fP vertical- and horizontal-motion escapes such as \efI, \efB,
-\efR, \efP.  Troff special glyphs are also available.  All \e-escapes will be
+\fB[gtn]roff\fP vertical- and horizontal-motion escapes such as \eh or \ev.
+Troff special glyphs are also available.  All \e-escapes will be
 passed through to the postprocessing stage and have their normal
 effects.  The base font family is set by the \fB[gtn]roff\fP
 environment at the time the picture is rendered.
diff --git a/src/devices/grops/grops.man b/src/devices/grops/grops.man
index ff38f8fc4..b64ec6a6c 100644
--- a/src/devices/grops/grops.man
+++ b/src/devices/grops/grops.man
@@ -18,9 +18,6 @@ translations approved by the Free Software Foundation instead of in
 the original English.
 ..
 .
-.do nr grops_C \n[.C]
-.cp 0
-.
 .
 .\" Like TP, but if specified indent is more than half
 .\" the current line-length - indent, use the default indent.
@@ -29,12 +26,6 @@ the original English.
 .  el .TP "\\$1"
 ..
 .
-.de TQ
-.  br
-.  ns
-.  TP \\$1
-..
-.
 .de FT
 .  if '\\*(.T'ps' .ft \\$1
 ..
@@ -44,22 +35,13 @@ the original English.
 .
 .
 .SH NAME
+.
 grops \- PostScript driver for groff
 .
 .
 .SH SYNOPSIS
-.nr a \n(.j
-.ad l
-.nr i \n(.i
-.in +\w'\fBgrops 'u
-.ti \niu
-.B grops
-.
-.de OP
-.  ie \\n(.$-1 .RI "[\ \fB\\$1\fP" "\%\\$2" "\ ]"
-.  el .RB "[\ " "\\$1" "\ ]"
-..
 .
+.SY grops
 .OP \-glmv
 .OP \-b n
 .OP \-c n
@@ -68,16 +50,17 @@ grops \- PostScript driver for groff
 .OP \-p papersize
 .OP \-P prologue
 .OP \-w n
-.RI "[\ " files\|.\|.\|. "\ ]"
-.br
-.ad \na
+.RI [ files
+.IR .\|.\|. ]
+.YS
 .
-.PP
+.LP
 It is possible to have whitespace between a command line option and its
 parameter.
 .
 .
 .SH DESCRIPTION
+.
 .B grops
 translates the output of GNU
 .B troff
@@ -115,7 +98,7 @@ using
 .B \-P
 option.
 .
-.PP
+.LP
 Note that
 .B grops
 doesn't produce a valid document structure (conforming to the Document
@@ -131,6 +114,7 @@ below for a guide how to install fonts for
 .
 .
 .SH OPTIONS
+.
 .TP
 .BI \-b n
 Provide workarounds for older printers, broken spoolers, and previewers.
@@ -246,19 +230,25 @@ both on letter (8.5\[mu]11) paper and on A4 paper without change.
 .
 .TP
 .BI \-I dir
-This option may be used to specify a directory to search for
+This option may be used to add a directory to the search path for
 files on the command line and files named in
 .B \[rs]X'ps: import'
 and
 .B \[rs]X'ps: file'
 escapes.
 .
-The current directory is always searched first.
+The search path is initialized with the current directory.
 .
-This option may be specified more than once;
-the directories are searched in the order specified.
+This option may be specified more than once; the directories are then
+searched in the order specified (but before the current directory).
 .
-No directory search is performed for files specified using an absolute path.
+If you want to make the current directory be read before other directories,
+add
+.B \-I.\&
+at the appropriate place.
+.
+.IP
+No directory search is performed for files with an absolute file name.
 .
 .TP
 .B \-l
@@ -311,6 +301,7 @@ Print the version number.
 .
 .
 .SH USAGE
+.
 The input to
 .B grops
 must be in the format output by
@@ -1194,6 +1185,7 @@ This font editor can convert most outline font formats.
 .
 .
 .SH FONT INSTALLATION
+.
 This section gives a summary of the above explanations; it can serve
 as a step-by-step font installation guide for
 .BR grops .
@@ -1321,13 +1313,18 @@ field in the `FBB' file), thus the following line should be added to
 .
 .
 .SH OLD FONTS
+.
 groff versions 1.19.2 and earlier contain a slightly different set of
 the 35 Adobe core fonts; the difference is mainly the lack of the `Euro'
 glyph and a reduced set of kerning pairs.
 .
 For backwards compatibility, these old fonts are installed also in the
-directory
-.BR @OLDFONTDIR@/devps .
+.
+.IP
+.BR @OLDFONTDIR@/devps
+.
+.LP
+directory.
 .
 .LP
 To use them, make sure that
@@ -1339,7 +1336,7 @@ to
 .B grops
 .
 .IP
-.B groff \-Tps \-P\-F -P@OLDFONTDIR@ .\|.\|.
+.B groff \-Tps \-P\-F \-P@OLDFONTDIR@ .\|.\|.
 .
 .LP
 or add the directory to groff's font path environment variable
@@ -1349,6 +1346,7 @@ or add the directory to groff's font path environment variable
 .
 .
 .SH ENVIRONMENT
+.
 .TP
 .SM
 .B GROPS_PROLOGUE
@@ -1381,6 +1379,7 @@ for more details.
 .
 .
 .SH FILES
+.
 .Tp \w'\fB@FONTDIR@/devps/download'u+2n
 .B @FONTDIR@/devps/DESC
 Device description file.
@@ -1424,6 +1423,7 @@ Temporary file.
 .
 .
 .SH "SEE ALSO"
+.
 .BR \%afmtodit (@MAN1EXT@),
 .BR groff (@MAN1EXT@),
 .BR @g@troff (@MAN1EXT@),
@@ -1433,12 +1433,11 @@ Temporary file.
 .BR \%groff_char (@MAN7EXT@),
 .BR \%groff_tmac (@MAN5EXT@)
 .
-.PP
+.LP
 .UR http://\:partners.adobe.com/\:public/\:developer/\:en/\:ps/\:5001.DSC_Spec.pdf
 PostScript Language Document Structuring Conventions Specification
 .UE
 .
-.cp \n[grops_C]
 .
 .\" Local Variables:
 .\" mode: nroff
diff --git a/src/preproc/soelim/soelim.man b/src/preproc/soelim/soelim.man
index 340a5b713..7d667d3c6 100644
--- a/src/preproc/soelim/soelim.man
+++ b/src/preproc/soelim/soelim.man
@@ -1,6 +1,6 @@
 '\" p
 .ig
-Copyright (C) 1989-2000, 2001, 2003, 2004, 2006
+Copyright (C) 1989-2000, 2001, 2003, 2004, 2006, 2008
 Free Software Foundation, Inc.
 
 Permission is granted to make and distribute verbatim copies of
@@ -31,16 +31,12 @@ the original English.
 .
 .SH SYNOPSIS
 .
-.B @g@soelim
-[
-.B \-Crtv
-]
-[
-.BI \-I dir
-]
-[
-.IR files \|.\|.\|.\|
-]
+.SY @g@soelim
+.OP \-Crtv
+.OP \-I dir
+.RI [ files
+.IR \|.\|.\|. ]
+.YS
 .
 .PP
 It is possible to have whitespace between the
@@ -55,12 +51,12 @@ reads
 .I files
 and replaces lines of the form
 .IP
-.BI .so\  file
+.BI .so\~ file
 .LP
 by the contents of
 .IR file .
 It is useful if files included with
-.B so
+.B .so
 need to be preprocessed.
 Normally,
 .B @g@soelim
@@ -79,8 +75,9 @@ makes
 ignore the whole line.
 .
 .PP
-Note that there must be no whitespace between the leading dot and
-the two characters `s' and `o'.  Otherwise, only
+Note that there must be no whitespace between the leading dot and the two
+characters `s' and `o'.
+Otherwise, only
 .B groff
 interprets the
 .B .so
@@ -99,23 +96,32 @@ even when followed by a character other than space or newline.
 .
 .TP
 .BI \-I dir
-This option may be used to specify a directory to search for
-files (both those on the command line and those named in
+This option may be used to add a directory to the search path for files
+(both those on the command line and those named in
 .B .so
 requests).
-The current directory is always searched first.
-This option may be specified more than once,
-the directories are searched in the order specified.
-No directory search is performed for files specified using an absolute path.
+The search path is initialized with the current directory.
+This option may be specified more than once; the directories are then
+searched in the order specified (but before the current directory).
+If you want to make the current directory be read before other directories,
+add
+.B \-I.\&
+at the appropriate place.
+.IP
+No directory search is performed for files with an absolute file name.
 .
 .TP
 .B \-r
-Do not add \&.lf requests (for general use, with non-groff files).
+Do not add
+.B .lf
+requests (for general use, with non-groff files).
 .
 .TP
 .B \-t
-Don't emit \&.lf requests but TeX comment lines (starting with `%') giving
-the current file and line number.
+Don't emit
+.B .lf
+requests but TeX comment lines (starting with `%') giving the current file
+and line number.
 .
 .TP
 .B \-v
@@ -129,6 +135,8 @@ The normal processing sequence of groff is this:
 .PP
 .ie t \{\
 .PS
+.ps 10
+.vs 12
 box invisible width 0.5 height 0.4 "input" "file";
 move to last box .bottom;
 down;
@@ -151,6 +159,8 @@ move to last box .bottom;
 down;
 arrow 0.3;
 box invisible width 0.5 height 0.4 "output" "file"
+.ps
+.vs
 .PE
 .\}
 .el \{\
@@ -183,8 +193,7 @@ required for
 to source files.
 .
 .PP
-If a file to be sourced should also be preprocessed, it must
-already be read
+If a file to be sourced should also be preprocessed, it must already be read
 .I before
 the input file passes through the preprocessor.
 This is handled by
@@ -193,6 +202,8 @@ This is handled by
 .PP
 .ie t \{\
 .PS
+.ps 10
+.vs 12
 box invisible width 0.5 height 0.4 "input" "file";
 move to last box .bottom;
 down;
@@ -212,6 +223,8 @@ move to last box .bottom;
 down;
 arrow 0.3;
 box invisible width 0.5 height 0.4 "output" "file"
+.ps
+.vs
 .PE
 .\}
 .el \{\
diff --git a/src/roff/troff/troff.man b/src/roff/troff/troff.man
index 0d6b26ad3..f8819e93a 100644
--- a/src/roff/troff/troff.man
+++ b/src/roff/troff/troff.man
@@ -154,14 +154,19 @@ processed.
 .
 .TP
 .BI \-I dir
-This option may be used to specify a directory to search for
-files (both those on the command line and those named in
+This option may be used to add a directory to the search path for files
+(both those on the command line and those named in
 .B \&.psbb
 requests).
-The current directory is always searched first.
-This option may be specified more than once;
-the directories will be searched in the order specified.
-No directory search is performed for files specified using an absolute path.
+The search path is initialized with the current directory.
+This option may be specified more than once; the directories are then
+searched in the order specified (but before the current directory).
+If you want to make the current directory be read before other directories,
+add
+.B \-I.\&
+at the appropriate place.
+.IP
+No directory search is performed for files with an absolute file name.
 .
 .TP
 .BI \-m name