* 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.

1 files changed, 60 insertions, 6 deletions

diff --git a/tmac/pspic.tmac b/tmac/pspic.tmac
index 9fe7e3eb..0fc4f12d 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