Re: terminal API: Intent of multiplot suspend/resume?

[Hans-Bernhard B. <br...@ph...>]

Ethan Merritt wrote:
> While I was trying to use the term->suspend() and term->resume()
> API to implement Harald Harders' treatment of front/back text labels
> in epslatex, I discovered that it is pretty much useless.

I strongly suspect that to be a premature conclusion.

> The suspend() and resume() functions are only called if you are
> in interactive mode.  

Not so.

Here's the relevant snippet from term.c:term_check_multiplot_ok(), 
reindented for legibility.

     if (!f_interactive
	|| (term->flags & TERM_CAN_MULTIPLOT)
	|| ((gpoutfile != stdout)
	    && !(term->flags & TERM_CANNOT_MULTIPLOT)
	   )
        ) {
         /* it's okay to use multiplot here, but suspend first */
         term_suspend();
         return;
     }

So term->suspend, if it exists, will be called on entering multiplot
mode, in each of the following cases:

*) if non-interactive
*) if the terminal driver says it wants it to be called (even in 
interactive mode), by setting the "TERM_CAN_MULTIPLOT" mode.
*) if the terminal driver supports multiplot at all.

> On terminals that actually need use routines (amiga svga pm vgagl),

That list appears to be missing aquaterm, ggi, linux, mac, windows and 
x11.  Now, ggi and linux could perhaps be subsumed under "svga", but the 
others are for real: they actually do something in term->suspend(): they 
update the partially finished multi-plot to the canvas.

> has mulitplot never worked in scripts or via load commands?

It has worked.

> I had never imagined this was meant to imply that a terminal could
> *not* multiplot if the output *is* redirected.

That's not what it implies.  It only implies that such a terminal
driver needs special attention to implement interactive multiplot in a
sensible manner.

In a nutshell, the terminals that strictly need these functions are 
those where the interactive command prompt and the graph must not be 
output to the default device simultaneously: the full-screen terminals 
that alternate between text and graphic modes, and possibly some others 
that output graphic as a metafile to stdout by default (unixplot and GNU 
libplot output).

The calls are also useful for interactive GUI terminals where people
would naturally expect to see the first plot in the graph window while
they compose the second.  These calls may not be wanted in 
non-interactive mode on such terminals, though, because they slow down 
operation by causing redundant re-draws (i.e. time for a multiplot of N 
individual plots becomes O(N^2)).