[groff] PSPIC vs PDFPIC: adjust documentation to reality, or the reverse?

[Bernhard Fisseni]

Good evening,

when playing around with PSPIC and PDFPIC, I noticed that they behave
differently:  PDFPIC does not reserve vertical space for a picture, but
PSPIC does.  I had asked Deri James's help on this, he confirmed the
problem and suggested to raise the question here.

The documentation in groff_tmac(7) claims:

> pdfpic
>
> A single macro is provided in this file, PSPIC, to include a PDF
> graphic in a document, i.e. under the output device -Tpdf. For all
> other devices, pspic is used. So pdfpic is an extension of pspic. By
> that you can now even replace all PSPIC by PDFPIC, nothing gets lost by
> that. The options of PDFPIC are identical to the PSDIF options.
                                                     ^^^^ (sic)

I read this as suggesting that results with -Tps and -Tpdf should be
equivalent.  Would it hence be sensible to change PDFPIC to fit the
description, or to adjust the description as in the patch below?

(Getting rid of the typo is probably uncontroversial.)

Best regards,
Bernhard



diff --git a/man/groff_tmac.5.man b/man/groff_tmac.5.man
index 7a18d32d..e8728228 100644
--- a/man/groff_tmac.5.man
+++ b/man/groff_tmac.5.man
@@ -419,8 +419,25 @@ nothing gets lost by that.
 The options of
 .B PDFPIC
 are identical to the
-.B PSDIF
+.B PSPIC
 options.
+.IP
+However, PDFPIC used with
+.B \-Tpdf
+does not reserve vertical space for the picture.  To use it as a
+replacement for
+.B PSPIC
+and obtain equivalent results in PDF and PostScript, you should add
+something like:
+.
+.RS
+.IP
+.EX
+\&.am PDFPIC
+\&.  if '\\*[.T]'pdf' .sp \\n[pdf-desht]u
+\&..
+.EE
+.RE
 .
 .
 .TP