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

[Deri James]

On Mon 02 Apr 2018 12:14:03 Ralph Corderoy wrote:
> Good afternoon Bernhard,
> 
> > > So pdfpic is an extension of pspic. By that you can now even replace
> > > all PSPIC by PDFPIC, nothing gets lost by that.
> > 
> > I read this as suggesting that results with -Tps and -Tpdf should be
> > equivalent.
> 
> Strongly agree.
> 
> > Would it hence be sensible to change PDFPIC to fit the description
> 
> +1.  Even though it may cause some existing documents to change if
> reproduced.  I don't think PDFPIC is old or widespread enough, to try
> and preserve its (broken) behaviour.

To avoid making existing documents render incorrectly I propose to allow the 
existing behaviour to be selected. Adding this to the NEWS file:-

============================================================================
PDFPIC has now been corrected, so the behaviour is the same whether you use 
the postscript or pdf drivers. However, this means that any documents which 
were written using the old behaviour will not be rendered correctly if using 
the pdf driver with the new version.

The change would mean that documents which relied on the previous behaviour 
are likely to have a gap underneath the image which was not there before. If 
you see this effect there are three ways you can restore the previous 
behaviour (listed in order of priority):-

A) Add the line ".nr PDFPIC_LEGACY 1" to the document before the first call to 
.PDFPIC.

B) If it is just a single document which exhibits this behaviour you can run 
groff adding "-rPDFPIC_LEGACY=1" to the command-line.

C) If you have many documents which rely on the previous behaviour you can set 
an environment variable "export PDFPIC_LEGACY=1" which will restore the 
previous behaviour for all runs.

Note that this change has no effect it you were using .PDFPIC with the 
postscript driver, only if you used it with the pdf driver.
=============================================================================

Does this sound sensible?

Cheers

Deri