* tmac/pspic.tmac: Make .PSPIC work for all devices.

Print image file name for devices which don't support PS image
inclusion.
Handle multiple inclusions.
Add lots of comments.

* tmac/dvi.tmac, tmac/html.tmac, tmac/ps.tmac: Don't load
pspic.tmac.

* tmac/troffrc: Load pspic.tmac.

* man/groff_tmac.man: Update .PSPIC documentation.

* NEWS: Updated.

9 files changed, 120 insertions, 33 deletions

diff --git a/ChangeLog b/ChangeLog
index 97a5a9e82..0715b511b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,20 @@
+2006-07-01  Werner LEMBERG  <wl@gnu.org>
+
+	* tmac/pspic.tmac: Make .PSPIC work for all devices.
+	Print image file name for devices which don't support PS image
+	inclusion.
+	Handle multiple inclusions.
+	Add lots of comments.
+
+	* tmac/dvi.tmac, tmac/html.tmac, tmac/ps.tmac: Don't load
+	pspic.tmac.
+
+	* tmac/troffrc: Load pspic.tmac.
+
+	* man/groff_tmac.man: Update .PSPIC documentation.
+
+	* NEWS: Updated.
+
 2006-06-29  Werner LEMBERG  <wl@gnu.org>
 
 	* src/roff/troff/input.cpp (interpolate_macro):
diff --git a/NEWS b/NEWS
index 55759b509..a1f15486f 100644
--- a/NEWS
+++ b/NEWS
@@ -60,6 +60,10 @@ o A new macro `Dx' has been added which identifies the DragonFly OS.
 
 o -mtrace now shows whether a macro has been called as .foo or as 'foo.
 
+o The PSPIC macro now works with all devices (producing a hollow
+  rectangle on devices which don't support inclusion of PS images) and
+  is loaded in troffrc at start-up.
+
 
 VERSION 1.19.2
 ==============
diff --git a/doc/groff.texinfo b/doc/groff.texinfo
index bfdd8616e..d99f36128 100644
--- a/doc/groff.texinfo
+++ b/doc/groff.texinfo
@@ -4886,6 +4886,8 @@ command line @option{-mec} is used also to load the file @file{ec.tmac}
 @node Measurements, Expressions, Text, gtroff Reference
 @section Measurements
 @cindex measurements
+@cindex scaling indicator
+@cindex indicator, scaling
 
 @cindex units of measurement
 @cindex basic unit (@code{u})
diff --git a/man/groff_tmac.man b/man/groff_tmac.man
index 4fb44b013..b0d86f48a 100644
--- a/man/groff_tmac.man
+++ b/man/groff_tmac.man
@@ -14,7 +14,7 @@ groff_tmac.5
 
 File position: <groff-source>/man/groff_tmac.man
 
-Last update: 07 Feb 2006
+Last update: 01 Jul 2006
 
 This file is part of groff, the GNU roff type-setting system.
 
@@ -330,7 +330,7 @@ or
 .Shell_cmd "groff \-m man foo \-m ms bar"
 .
 .P
-will fail.
+fails.
 .
 .
 .\" --------------------------------------------------------------------
@@ -482,7 +482,7 @@ needed for the
 .BR @g@pic (@MAN1EXT@)
 preprocessor.
 .
-They will center each picture.
+They center each picture.
 .
 Use it only if your macro package doesn't provide proper definitions
 for those two macros (actually, most of them already have).
@@ -494,27 +494,41 @@ A single macro is provided in this file,
 .BR PSPIC ,
 to include a PostScript graphic in a document.
 .
-It makes only sense for output devices which support inclusion of PS
-images:
+The following output devices support inclusion of PS images:
 .BR \-Tps ,
 .BR \-Tdvi ,
 and
 .BR \-Thtml ;
-the file is then loaded automatically.
+for all other devices the image is replaced with a hollow rectangle
+of the same size.
 .
+This macro file is already loaded at start-up by
+.B @g@troff
+so it isn't necessary to call it explicitly.
+.
+.IP
 Syntax:
 .RS
 .IP
-\&\fB.PSPIC\fP [\fB\-L\fP|\fB-R\fP|\fB\-I\fP \fIn\fP]\ \fI\|file\fP [\fIwidth\fP [\fIheight\fP]]
+\&\fB.PSPIC\fP [\fB\-L\fP\||\|\fB-R\fP\||\|\fB\-I\fP\ \fIn\fP] \
+\fI\|file\fP [\fIwidth\fP [\fIheight\fP]]
 .RE
 .
 .IP
 .I file
-is the name of the file containing the illustration;
+is the name of the PostScript file;
 .I width
 and
 .I height
-give the desired width and height of the graphic.
+give the desired width and height of the image.
+.
+If neither a
+.I width
+nor a
+.I height
+argument is specified, the image's natural width (as given in
+the file's bounding box) or the current line length is used
+as the width, whatever is smaller.
 .
 The
 .I width
@@ -524,7 +538,7 @@ arguments may have scaling indicators attached;
 the default scaling indicator is\~\c
 .BR i .
 .
-This macro will scale the graphic uniformly
+This macro scales the graphic uniformly
 in the x and y\~directions so that it is no more than
 .I width
 wide
@@ -532,7 +546,7 @@ and
 .I height
 high.
 .
-By default, the graphic will be horizontally centered.
+By default, the graphic is horizontally centered.
 .
 The
 .BI \-L
@@ -721,7 +735,7 @@ In groff, the file
 .IB name .tmac
 is searched within the tmac path; if not found,
 .BI tmac. name
-will be searched for instead.
+is searched for instead.
 .
 .
 .P
@@ -981,7 +995,7 @@ arg1 arg2
 .P
 Let's analyze each backslash in the macro definition.
 .
-As the positional parameters and the number of arguments will change
+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 \[rs]\[rs]$*
@@ -995,14 +1009,14 @@ alias name, so
 .P
 On the other hand,
 .I midpart
-is a constant string, it will not change, so no doubling for
+is a constant string, it does not change, so no doubling for
 .IR \[rs]*[midpart] .
 The
 .I \[rs]f
 escape sequences are predefined groff elements for setting the font
 within the text.
 .
-Of course, this behavior will not change, so no doubling with
+Of course, this behavior does not change, so no doubling with
 .I \[rs]f[I]
 and
 .IR \[rs]f[] .
@@ -1049,7 +1063,7 @@ For example, the code above can be written in a simpler way by
 Unfortunately, draft mode cannot be used universally.
 .
 Although it is good enough for defining normal macros, draft mode
-will fail with advanced applications, such as indirectly defined
+fails with advanced applications, such as indirectly defined
 strings, registers, etc.
 .
 An optimal way is to define and test all macros in draft mode and then
diff --git a/tmac/dvi.tmac b/tmac/dvi.tmac
index ff5a2a27a..a223b106a 100644
--- a/tmac/dvi.tmac
+++ b/tmac/dvi.tmac
@@ -779,9 +779,6 @@ D\v'-.33m'\s0\v'.33m'
 .
 .cp \n(_C
 .
-.if !\n(.C \
-.  mso pspic.tmac
-.
 .do ie '\[char97]'a' \
 .  do mso latin1.tmac
 .el \
diff --git a/tmac/html.tmac b/tmac/html.tmac
index cd264465c..8c5cacb43 100644
--- a/tmac/html.tmac
+++ b/tmac/html.tmac
@@ -533,10 +533,8 @@
 .
 .cp \n(_C
 .
-.if !\n(_C \{\
-.  mso pspic.tmac
+.if !\n(_C \
 .  mso www.tmac
-.\}
 .
 .do ie '\[char97]'a' \
 .  do mso latin1.tmac
diff --git a/tmac/ps.tmac b/tmac/ps.tmac
index 39d431826..52f9975be 100644
--- a/tmac/ps.tmac
+++ b/tmac/ps.tmac
@@ -681,9 +681,6 @@
 .
 .cp \n[_C]
 .
-.if !\n(.C \
-.  mso pspic.tmac
-.
 .do ie '\[char97]'a' \
 .  do mso latin1.tmac
 .el \
diff --git a/tmac/pspic.tmac b/tmac/pspic.tmac
index 9fe7e3eb1..0fc4f12dd 100644
--- a/tmac/pspic.tmac
+++ b/tmac/pspic.tmac
@@ -2,23 +2,35 @@
 .\"
 .\" Define the PSPIC macro.
 .\"
-.\" When used other than with -Tps, -Tdvi, or -Thtml it will draw a box
+.\" When used other than with -Tps, -Tdvi, or -Thtml it draws a box
 .\" around where the picture would go.
+.\"
+.\" Usage:
+.\"
+.\"   .PSPIC [-L|-R|-I <indent>] <file> [<width> [<height>]]
+.
+.do if d PSPIC .nx
+.
+.nr _C \n(.C
+.cp 0
 .
 .de PSPIC
 .  nr ps-offset-mode 0
+.  \" left-aligned?
 .  ie '\\$1'-L' \{\
 .    nr ps-offset-mode 1
 .    shift
 .    HTML-DO-IMAGE \\$1 l
 .  \}
 .  el \{\
+.    \" right-aligned?
 .    ie '\\$1'-R' \{\
 .      nr ps-offset-mode 2
 .      shift
 .      HTML-DO-IMAGE \\$1 r
 .    \}
 .    el \{\
+.      \" indented?
 .      ie '\\$1'-I' \{\
 .        nr ps-offset-mode 3
 .        nr ps-offset (m;\\$2)
@@ -32,6 +44,7 @@
 .
 .  br
 .
+.  \" get bounding box
 .  psbb \\$1
 .  if (\\n[llx] : \\n[lly] : \\n[urx] : \\n[ury]) \{\
 .    nr ps-wid (\\n[urx] - \\n[llx])
@@ -40,22 +53,37 @@
 .      nr ps-wid (-\\n[ps-wid])
 .    if (\\n[ps-ht] < 0) \
 .      nr ps-ht (-\\n[ps-ht])
+.
+.    \" if we have a <width> parameter, use it as the final
+.    \" image width; otherwise we use the image's natural width
+.    \" or the current line length, whatever is smaller
 .    ie (\\n[.$] >= 2) \
 .      nr ps-deswid (i;\\$2)
 .    el \
 .      nr ps-deswid ((\\n[.l] - \\n[.i]) <? \\n[ps-wid]p)
+.
+.    \" compute the final image height (with proper rounding),
+.    \" based on the image's aspect
 .    nr ps-desht (\\n[ps-deswid] * 1000 + (\\n[ps-wid] / 2) \
                   / \\n[ps-wid] * \\n[ps-ht] \
                   + 500 / 1000)
+.
+.    \" if we have a <height> parameter, use it as the final
+.    \" image height in case it is smaller than the height
+.    \" value we have just computed
 .    if ((\\n[.$] >= 3) & (\\n[ps-desht] > (i;0\\$3))) \{\
 .      nr ps-desht (i;\\$3)
+.      \" recompute the final image width since we always
+.      \" keep the correct image aspect
 .      nr ps-deswid (\\n[ps-desht] * 1000 + (\\n[ps-ht] / 2) \
                      / \\n[ps-ht] * \\n[ps-wid] \
                      + 500 / 1000)
 .    \}
 .
+.    \" reserve vertical space for image
 .    ne (\\n[ps-desht]u + 1v)
 .
+.    \" compute image offset w.r.t. the current left margin
 .    if (\\n[ps-offset-mode] == 0) \
 .      nr ps-offset (\\n[.l] - \\n[.i] - \\n[ps-deswid] / 2)
 .    if (\\n[ps-offset-mode] == 1) \
@@ -64,6 +92,7 @@
 .      nr ps-offset (\\n[.l] - \\n[.i] - \\n[ps-deswid])
 .
 .    ie '\*[.T]'dvi' \{\
+.      \" prepare values for \special{psfile=...} as needed by dvips
 .      ie (\\n[ps-wid]p == \\n[ps-deswid]) \{\
 .        ds ps-scale \" empty
 .        ds ps-hoffset hoffset=-\\n[llx]
@@ -83,18 +112,41 @@
 \X'psfile=\\$1 \\*[ps-hoffset] \\*[ps-voffset] \\*[ps-scale]'
 .    \}
 .    el \{\
+.      ie '\*[.T]'ps' \{\
+.        \" prepare values for grops; the `ps-invis' and `ps-endinvis' escapes
+.        \" are for groff's -X switch to provide a PS preview with xditview:
+.        \" it uses -Tps for formatting but xditview can't handle EPS files,
+.        \" thus alternative code is enclosed between those two escapes
+.        ds ps-invis \X'ps: invis'
+.        ds ps-endinvis \X'ps: endinvis'
+.        ds ps-import \X'ps: import \E$1 \En[llx] \En[lly] \En[urx] \En[ury] \
+                                    \En[ps-deswid] \E*[ps-desht]'
+.      \}
+.      el \{\
+.        ds ps-invis
+.        ds ps-endinvis
+.        ds ps-import
+.      \}
+.
 .      ie (\\n[.$] >= 3) \
 .        ds ps-desht \\n[ps-desht]
 .      el \
 .        ds ps-desht \" empty
 .
 \h'\\n[ps-offset]u'\
-\X'ps: invis'\
-\Z'\D'p 0 \\n[ps-desht]u \\n[ps-deswid]u 0 0 -\\n[ps-desht]u''\
-\X'ps: endinvis'\
+\\*[ps-invis]\
+\# horizontally, the rectangle is slightly smaller than the image
+\# to compensate the line thickness (especially needed for TTY devices)
+\Z'\D'p 0 \\n[ps-desht]u \
+        (\\n[ps-deswid]u - \\n[.H]u) 0 \
+        0 -\\n[ps-desht]u''\
+\# for convenience we also display the image file name (centered vertically);
+\Z'\v'((\\n[ps-desht]u / 2u) \
+       + (\w'\\$1' * 0) \
+       + ((\\n[rst]u + \\n[rsb]u) / 2u))'\h'1m'\\$1'\
+\\*[ps-endinvis]\
 \v'\\n[ps-desht]u'\
-\X'ps: import \
-       \\$1 \\n[llx] \\n[lly] \\n[urx] \\n[ury] \\n[ps-deswid] \\*[ps-desht]'
+\\*[ps-import]
 .    \}
 .
 .    br
@@ -103,4 +155,6 @@
 .  HTML-IMAGE-END
 ..
 .
+.cp \n[_C]
+.
 .\" end of pspic.tmac
diff --git a/tmac/troffrc b/tmac/troffrc
index d73ace35f..470f26279 100644
--- a/tmac/troffrc
+++ b/tmac/troffrc
@@ -27,7 +27,8 @@
 .do rm troffrc!ps troffrc!Xps troffrc!dvi troffrc!X75 troffrc!X75-12 \
 troffrc!X100 troffrc!X100-12 troffrc!lj4 troff!lbp troffrc!html
 .
-.\" test whether we work under EBCDIC
+.\" Test whether we work under EBCDIC and map the no-breakable space
+.\" character accordingly.
 .do ie '\[char97]'a' \
 .	do tr \[char160]\~
 .el \
@@ -40,7 +41,10 @@ troffrc!X100 troffrc!X100-12 troffrc!lj4 troff!lbp troffrc!html
 .do hpf hyphen.us
 .do hpfa hyphenex.us
 .
-.\" Handle paper formats
+.\" Handle paper formats.
 .do mso papersize.tmac
 .
+.\" Handle PS images.
+.do mso pspic.tmac
+.
 .\" Don't let blank lines creep in here.