[groff] 07/09: [pspic]: Add error hook.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 1635c57d1290a4f0b840a74b2c7cb31a1fd8a5c5
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Mar 30 14:54:32 2022 +1100

    [pspic]: Add error hook.
    
    * tmac/pspic.tmac (pspic*error-hook): Define (as empty).
    * man/groff_tmac.5.man (Auxiliary packages) <pspic>: Document.
    * NEWS: Add item.
---
 ChangeLog            |  6 ++++++
 NEWS                 |  7 +++++++
 man/groff_tmac.5.man | 29 +++++++++++++++++++++++++++--
 tmac/pspic.tmac      | 11 ++++++++++-
 4 files changed, 50 insertions(+), 3 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 51db794d..25376a09 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2022-03-30  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       * tmac/pspic.tmac (pspic*error-hook): Define (as empty).
+       * man/groff_tmac.5.man (Auxiliary packages) <pspic>: Document.
+       * NEWS: Add item.
+
 2022-03-29  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * tmac/tests/pdfpic_does-not-choke-on-bad-pdfinfo-output.sh:
diff --git a/NEWS b/NEWS
index a035b4f2..33085833 100644
--- a/NEWS
+++ b/NEWS
@@ -137,6 +137,13 @@ o The `PDPFPIC` macro (provided by the `pdfpic` package), 
no longer
     .  ab
     ..
 
+o The pspic package now also has an error hook macro, which you can use
+  to make failed image loads fatal (or attempt fallback or recovery).
+
+    .am pspic@error-hook
+    .  ab
+    ..
+
 o The new rfc1345 macro package, contributed by Dorai Sitaram, defines
   special character glyph names implementing RFC 1345 mnemonics (plus
   some additions from Vim, which itself uses RFC 1345 for its digraphs).
diff --git a/man/groff_tmac.5.man b/man/groff_tmac.5.man
index dec41c04..f78050c4 100644
--- a/man/groff_tmac.5.man
+++ b/man/groff_tmac.5.man
@@ -635,9 +635,9 @@ for a different purpose).
 .
 .TP
 .I pspic
-provides a single macro,
+provides a macro,
 .BR PSPIC ,
-to include a PostScript graphic in a document.
+that includes a PostScript graphic in a document.
 .
 The
 .BR ps ,
@@ -741,6 +741,31 @@ assuring that the diversion's width completely covers the 
image's width.
 .RE
 .
 .
+.IP
+Failure to load
+.BR PSPIC 's
+image argument is not an error.
+.
+(The
+.B psbb
+request does issue an error diagnostic.)
+.
+To make such a failure fatal,
+append to the
+.B pspic*error\-hook
+macro.
+.
+.
+.RS
+.IP
+.EX
+\&.am pspic*error\-hook
+\&.\~\~ab
+\&..
+.EE
+.RE
+.
+.
 .TP
 .I ptx
 provides a single macro,
diff --git a/tmac/pspic.tmac b/tmac/pspic.tmac
index 4e321d0e..98f9ba4f 100644
--- a/tmac/pspic.tmac
+++ b/tmac/pspic.tmac
@@ -12,6 +12,13 @@
 .do nr *groff_pspic_tmac_C \n[.cp]
 .cp 0
 .
+.\" This is called if the `psbb` request returned a bounding box of all
+.\" zeroes.  It already issues a diagnostic; one can append `ab` to this
+.\" macro if that should be a fatal error, or redefine it for some other
+.\" purpose.
+.de pspic*error-hook
+..
+.
 .de PSPIC
 .  nr ps-offset-mode 0
 .  \" left-aligned?
@@ -48,7 +55,7 @@
 .
 .  \" get bounding box
 .  psbb \\$1
-.  if (\\n[llx] : \\n[lly] : \\n[urx] : \\n[ury]) \{\
+.  ie (\\n[llx] : \\n[lly] : \\n[urx] : \\n[ury]) \{\
 .    nr ps-wid (\\n[urx] - \\n[llx])
 .    nr ps-ht (\\n[ury] - \\n[lly])
 .    if (\\n[ps-wid] < 0) \
@@ -156,6 +163,8 @@
 .    br
 .    sp \\n[ps-desht]u
 .  \}
+.  el \
+.    pspic*error-hook \\$@
 .  HTML-IMAGE-END
 ..
 .