BLOP -- Multi-page terminals

Practical Guide: Two terminals are described here:

mpps and mppdf
versatile_pdf

The first two create a multi-page PostScript/PDF output by printing the current canvas into .beps files, including them in a LaTeX document and compiling the LaTeX document. That is, the different pages are in the same context.

versatile_pdf produces a multipage pdf output, which can be assembled from different types of documents (jpg, pdf, etc). In these examples and documentation, mpps can be substituted everywhere by mppdf, in which case a multi-page pdf file is produced instead, and not a postscript file.

 
mpps out("output.ps");
mpps.papersize("a3");      // set larger papersize instead of default a4

plot(...);                 // plot something 
out.print();               // and print this figure to the output terminal

plot(...);                 // plot  something else  
out.print("height=18cm");  // and print this to the file,  also specifying the optional arguments to the \blopeps latex-macro

out.options("height=10cm,width=10cm");  // from  now  on, all  figures will be printed with these options,
                                        // unless explicitely specified by the argument of  the 'print(...)'  function 
plot(...); 
out.print();               // this figure will be printed  in 10x10 cm size 

out.flush();               // flush it (.. compile with latex; file remains open)

out.close();               // flush and close the file (also compile with  latex) 
                           // now you can reuse this variable, via the open("filename")
//---------------------------

versatile_pdf output("output.pdf");

// simple plot, print it as pdf
plot(_1,_1);
output.print<pdf>();

// this plot is quite heavy, it it's printed as a pdf, it will be huge.
// print it as a bitmap (jpg) instead, and include it like that.
plot(_1,_2,sin(_1*_2)).p1range(0,10).p2range(0,10).nsamples(500).ds(cboxes());
output.print<jpg>("-w 10cm -h 8cm");

// add one more page from an existing graphics
output.include("some_file.png");

If you want to put several figures into a multi-page postscript(PDF) file, then the mpps(mppdf) terminal is your right choice. It is nothing else than a .tex file. When a figure is printed to this terminal, a separate blopeps file is created, and automatically included into this LaTeX document (using the \blopeps macro). This way it can accomodate several figures. It is automatically compiled by latex if you call the flush() function of it, or when you call close(), or when its destructor is called.

You can initialize it with a filename (this will be the final postscript/PDF file):
mpps out("output.ps")
or if you want to postpone the specification of the filename, you can use the open member function:
mpps out; out.open("output.ps");

The current canvas can be printed to it using the print member function of mpps. This print(...) function has an optional argument, which specifies the optional arguments to be given to the \blopeps macro when including this figure. In the following example the first figure (containing a sine) is included with the default settings, for the second (containig a cosine) the linewidth and height of the figure is changed.

mpps out("output.ps");

plot(_1,sin(_1)).p1range(0,10);
out.print();

plot(_1,cos(_1)).p1range(0,10);
out.print("linewidth=1pt,height=18cm");

out.flush();
system("gv output.ps &");

The mpps terminal is derived not only from blop::terminal, but also from std::ofstream, so you can also treat it as an output file (which is your LaTeX document source), and write directly to it. It automatically writes a default LaTeX document header (beginning from \documentclass{article} up to \begin{document}, and additionally also a \LARGE macro) into the file, but not before the first output of a figure into this terminal. This has the following consequences:

If you only want to print figures to the terminal with the default header, simply use the following sequences:
```
mpps out("output.ps");
plot(...);
out.print();
plot(...);
out.print();
```
If you want to rely on the default header, but write also some text into the file, you should explicitely request the printing of the header before you write something:
```
mpps out("output.ps");
out.print_header();
out<<"This will be my first figure:"<<endl;
plot(...);
out.print();
```

If you want to provide your own header, and not rely on the default one, proceed the following way:

mpps out("output.ps");
out<<"\\documentclass{foils}"<<endl;
out<<"\\usepackage{blopeps}"<<endl;
out<<"whatever you want to write here"<<endl;
out<<"\\begin{document}}"<<endl;

// and notify the terminal that you have written the header,
// so that it does not print it again
out.header_printed(true);

plot(...);
out.print();

The mpps terminal has 3 verbosity levels (to be set via the verbose(int) member function):

0 - No LaTeX/dvips messages are printed, even if they fail
1 - (default): output of LaTeX/dvips is printed, if they fail
2 - output of LaTeX/dvips is anyway printed