While LaTeX is really strong in text processing and also in formula processing, in itself it is weak in its graphical abilities. Graphics in some formats can be included directly in a LaTeX document, but all need loading of according packages. For an overview of the graphic formats and the packages needed for their support see Section 4.1. The set of available graphic formats is extended by preprocessing, i.e. by processing prior to the LaTeX engine. Preprocessing mainly consists in converting graphic formats not supported by LaTeX packages into graphic formats supported by some LaTeX packages. Section 4.2 provide vital information on the target formats.
This software uses preprocessing for graphics only. Note that preprocessing is a design decision on the build tool and e.g. latexmk has no preprocessing at all. For details see Section 3.6.2.0.
Table 4.1 gives an overview over the formats supported via preprocessing. The first column lists the formats, the second one at least one editor for the format, and the last row contains the parameter to configure the preprocessing tool and give the default tool as an example. Sections 4.3, 4.4, 4.5, 4.6 and 4.7 treat each format separately. For all but png and jpg considered in Section 4.7, preprocessing is just conversion of the format into another format directly supported as described in Section 4.1. Historically the latter two required preprocessing to determine the bounding box was needed. We still support this to support historical techniques and to be sure to be able to reconstruct historical documents. Support for further formats can be easily added. If there is some need, please write an email to the author.
Of course, to support a format, the preprocessing tools must be installed. It is advisable to have also an editor installed. Sometimes the editor is used also as converter as for inkscape. For human-readable formats like fig, it often makes sense, to use both the graphical editor and the textual one. Note that vscode supports the given formats more properly, if the extensions described in Section 3.5.5 are installed also.
| Graphic format | editor | preprocessing tool |
| fig | xfig, vscode | fig2devCommand, e.g. fig2dev |
| gnuplot (gp) | vscode | gnuplotCommand, e.g. gnuplot |
| MetaPost (mp) | vscode | metapostCommand, e.g. mpost |
| svg | inkscape, vscode | svg2devCommand, e.g. inkscape |
| jpg, png | gimp | ebbCommand, e.g. ebb |
Find below a list of packages either allowing to include directly certain graphic formats, or helping with graphics indirectly. Although strictly speaking these techniques do not need special treatment of a build tool, this software supports these techniques by providing header files by injection loading the needed packages.
We also describe in which sense these packages support graphical preprocessing.
is the basic graphics package which provides the command \includegraphics which allows including graphics natively in the formats PDF, EPS, JPG and PNG at least. For details see [Car16]. Note that PDF and EPS are target formats for graphical preprocessing, where PDF is embedded into PDF and EPS is embedded into DVI/XDV. As described in Section 4.5, also mps, the target format for metapost is included using graphicx.
allows specifying transparency in graphics. Even if you do not use the feature, some source formats do (in fact only svg) does and so the according converters create according information and so the LaTeX engine must get along with it. Note that this applies only for output format PDF and in particular not for xelatex. For details see [Obe16b].
is needed for bitmap formats like jpg and png only. Used to extract resolution and bounding box. FIXME: needed more information. For details see [Obe16a].
The TikZ code described in [Tan23] is just in LaTeX format. Thus, it can be included directly and does not require any preprocessing. Still what is needed is a good graphical editor like tikzedt with online manual [TW12]. In later versions of this software, 3.x or so, it is planned that TikZ is used as new target format for graphical preprocessing, replacing the current combination of LaTeX for texts and PDF/EPS for proper graphic.
is strictly speaking no graphics package. According to its documentation [Ars09], it allows an imported file to find its own inputs (using “\input”, “\includegraphics” etc.) in that directory. This is vital for the graphic formats for which a TEX file is imported which itself imports a PDF/EPS file located in the same folder but not in the folder of the importing file. It is advisable to combine the import package with other graphic packages to include graphics in separate graphic files.
allows using colors in graphics. Even if the author does not use colors in graphics, several formats, like fig, gp and svg offer it and so the according converters transforming them into the native formats create color information which can be rendered only via xcolor. In this sense its role is comparable to that of transparent. On the other hand, the use of xcolor is not specific to graphics. For details see [Ker16].
is strictly speaking no graphics package either but more general a way to include and run code within a LaTeX document as described in [Poo21]. Note that not only Python but also other languages can be used. Most of them offer graphic capabilities and so graphics can be included also via pythontex. Nevertheless, we do not treat this technique in this chapter, but separately in Section 5.5. This is because graphics is a side aspect of pythontex and also because strictly speaking there is no preprocessing. First a latex processor is run, and the package extracts the code into a separate file which is then further processed by an external tool. This is more like running \bibtex to extract a bibliography.
If using the package pythontex a special processing interacting with the LaTeX engine is required also, but it is not preprocessing.
Section 3.5 is on injection of files and in particular header files:
treated in Section 3.5.2, is a general header file intended to be included into all LaTeX files. Since the packages import and xcolor are generally useful, not only in the context of graphics, they are among those loaded in header.tex.
described in Section 3.5.3 in contrast, is a header file loading graphic specific packages related with graphicx, loading also transparent and bmpsize.
The header files adapt the loading of the packages to the context, in particular to the target format. Note that headerGrp.tex must follow header.tex.
The package tikz, although a pure graphic package is very specific and not related to graphicx. Thus, it must be loaded separately. The same holds for pythontex.
Besides the converter external to LaTeX, also several LaTeX-packages are required to use graphics.
This section describes the conversions of graphical source files into target files in detail.
But PDF also occurs as an intermediate format for pictures. For historical reasons, still eps is used. Section 4.3 shows how fig2dev converts fig-files into LaTeX-files containing text and including graphics in as PDF files. Likewise, Section 4.4 describes how gnuplot converts gnuplot-files into PDF files. An interesting alternative to gnuplot for computing pictures is MetaPost described in Section 4.5. A more elaborate alternative to fig-pictures are SVG pictures described in Section 4.6 Also several formats collected in Section 4.7 may be included as is.
At a first sight, PDF seems the ideal target format for any kind of preprocessing: It is really mighty enough to display pictures in any source format without loss of information and even without change in appearance, and for modern LaTeX implementations directly creating PDF files, the LaTeX-package graphicx allows including graphics as PDF files in LaTeX-files.
At a second sight, the source formats under consideration offer pictures mixing vector graphics and texts and in particular formulae set in LaTeX style. Preprocessing is based on on-the-shelf converters and if targeting PDF, the texts originally in LaTeX style change their appearance. To keep up LaTeX style, they provide mixed export consisting of a PDF file containing proper graphics without texts and a TEX file containing the texts in proper location and an \includegraphics command including the created PDF file. This mixed conversion is used for all kind of preprocessing.
Note that we could have used the ending TEX for the texts, but we opted for a specific ending ptx signifying that the file is created and thus does not slow down search of LaTeX main files.
But still there is another problem with PDF as target format: Traditionally LaTeX produced output in the dvi/xdv-format which is still used to create html-output. For LaTeX engines pdflatex and lualatex, DVI output is specified with option –output-format=dvi. It turns out, that with this setting, PDF files cannot be incorporated with \includegraphics command. Instead, one must use eps files. Fortunately, the graphic converters used also support combined TEX/ptx and EPS formats. We ensured that \includegraphics in the ptx file specifies the file without ending so that the ptx file is the same, whether it encloses a PDF file or an EPS file, and we provide both, a PDF file and an EPS file1 . That way, both, pdflatex and lualatex choose the EPS file or the PDF file depending on whether the output format is –output-format=dvi or –output-format=pdf which is the default. Note that xelatex, which always creates an intermediate XDV file (which is a special kind of DVI file), acts differently: If present, it prefers including the PDF file, if absent, but there is an EPS file instead, it uses this without making any difference.
Although this is beyond necessity, let me state that pdflatex and lualatex, while not accepting inclusion of PDF files in DVI mode, EPS files are accepted in PDF mode for more modern versions of the LaTeX engines, but this leads to creation of intermediate files xxx-eps-converted-to.pdf, which are not cleaned up in target clr.
Whereas PDF and EPS files both are offered, only one of them is included for a specific configuration. This is in contrast to other formats described in Section 4.7.
Although ptx is just a TEX format, it is special in that it presupposes that some packages are loaded before being included. The packages which are not specific for graphics like xcolor are loaded in header.tex described in Section 3.5.2, whereas the ones specific for graphics, above all graphicx, are loaded in headerGrp.tex as described in Section 3.5.3. The packages actually to be loaded and their respective options depend on the configuration.
Note that PDF and EPS file may be created by preprocessing but also as proper sources not created at all, even in a single document. Goal clr deletes the according files xxx.pdf or xxx.eps only, if an according source like xxx.fig exists. Else it is treated as proper source and is not deleted.
In the future, the combination of PDF/EPS and PTX files may be replaced, at least partially, or supplemented by TikZ files. It turned out, that the converters under consideration support more and more conversion into the TikZ format which can represent both, proper vector graphic and also LaTeX texts like formulae. Using TikZ as intermediate format has the advantage, that the working space is polluted less with generated files, preprocessing is speeded up because fewer files are created and in some cases, less processing steps are needed. Another advantage is, that the internal dependency recording of LaTeX engines made available through the fls file is accessible. As in the current technique using PTX files instead of TEX files, we could put the TikZ into TEX files, but we opt against it for the same reasons.
Note that PS is not supported because it misses the bounding box. If adding it, one arrives at the EPS format.
A simple but still useful tool to draw figures is xfig which stores graphics in a native format described in [Rei16] with file extension .fig. The file extension .fig is also used by MATLAB to store plots, but this is something different. Graphics in xfig format cannot be directly included in latex files but must be exported into a LaTeX-readable format.
To export a file xxx.fig residing in directory yyy into several external formats, xfig uses fig2dev. A look in [Rei16], Section 3.4 shows that texts with set “special”-flag are interpreted as latex-code. For these texts the appropriate export language would be latex. On the other hand, latex is weak in graphics and pdf would be the ideal export format for all kinds of objects, except for texts with set “special”-flag. In pdf format, texts are interpreted literally, independent of the “special”-flag. Thus, fig2dev offers a mixed solution: export xxx.fig in format pdftex which yields a pdf-file xxx.pdf containing all but text with set “special”-flag and complementary pdftex_t which yields a tex-file xxx.ptx including the pdf-file and the texts with set “special”-flag. The exported files are in the same directory yyy as the original file xxx.fig.
For example, the fig-file F4_01fig2dev.fig defining Figure 4.1, is transformed into a file F4_01fig2dev.ptx in format pdftex_t which starts as given by Listing 4.1.
\begin{picture}(0,0)% \includegraphics{F4_01fig2dev}% \end{picture}% % % Conversion of xxx.fig into xxx.ptx, xxx.pdf and xxx.eps % \setlength{\unitlength}{2072sp}% \begin{picture}(8492,4797)(1114,-4621) \put(1351,-2311){\makebox(0,0)[lb]{\smash{\fontsize{10}{12}\usefont{T1}{ptm}{m}{n}{\color[rgb]{0,0,0}\texttt{xxx.fig}}% }}} \put(6976,-286){\makebox(0,0)[lb]{\smash{\fontsize{10}{12}\usefont{T1}{ptm}{m}{n}{\color[rgb]{0,0,0}\texttt{xxx.pdf}}% }}} \put(6976,-2311){\makebox(0,0)[lb]{\smash{\fontsize{10}{12}\usefont{T1}{ptm}{m}{n}{\color[rgb]{0,0,0}\texttt{xxx.ptx}}% }}} \put(6976,-4336){\makebox(0,0)[lb]{\smash{\fontsize{10}{12}\usefont{T1}{ptm}{m}{n}{\color[rgb]{0,0,0}\texttt{xxx.eps}}% }}} \put(4726,-1636){\makebox(0,0)[b]{\smash{\fontsize{10}{12}\usefont{T1}{ptm}{m}{n}{\color[rgb]{0,0,0}\texttt{fig2dev -L pdftex\_t}}% }}} \put(4726,-2311){\makebox(0,0)[b]{\smash{\fontsize{10}{12}\usefont{T1}{ptm}{m}{n}{\color[rgb]{0,0,0}\texttt{fig2dev -L pstex\_t}}% }}} \put(3826,-61){\makebox(0,0)[rb]{\smash{\fontsize{10}{12}\usefont{T1}{ptm}{m}{n}{\color[rgb]{0,0,0}\texttt{fig2dev -L pdftex}}% }}} \put(3826,-4561){\makebox(0,0)[rb]{\smash{\fontsize{10}{12}\usefont{T1}{ptm}{m}{n}{\color[rgb]{0,0,0}\texttt{fig2dev -L pstex}}% }}} \put(7426,-1186){\makebox(0,0)[lb]{\smash{\fontsize{10}{12}\usefont{T1}{ptm}{m}{n}{\color[rgb]{0,0,0}\texttt{\textbackslash includegraphics\{xxx\}}}%Listing 4.1: The ptx-file for a fig-file
The file xxx.ptx is “imported” into the tex-file of this manual by the command
\import{yyy}{xxx.ptx}
and includes xxx.pdf automatically the file xxx.pdf via \includegraphics{xxx} (line 2). Note the following remarkable details:
Observe that we can drop the suffix of the included file xxx.pdf which is expressed as “xxx” because LaTeX chooses the right suffix: If instead of xxx.pdf there is a file xxx.eps, the latter is chosen if no suffix is specified. As we will see below, omitting the suffix is crucial to make xxx.ptx work for both LaTeX-output formats: the pdf-format can include pdf-files, whereas the dvi-format which is required to create html- and odt-files can include eps-files.
If xxx.pdf is included in xxx.ptx with the full path name, we may use \input{xxx.ptx} instead of \import{yyy}{xxx.ptx}.
If in contrast, xxx.pdf is included in xxx.ptx with the short name only, xxx.pdf is assumed to be in the same directory as the file inputting xxx.ptx. So in general, i.e. if this is not yyy, we need import \import{yyy}{xxx.ptx}. If the directories coincide, in the import the string yyy may be empty. If the string yyy is not empty, it must end with the path delimiter, i.e. / for Unix like systems and \ for win-like systems.
As indicated in Section 4.1, the commands in xxx.ptx require the packages graphicx and xcolor. Also, the \import command requires the import package.
To export xxx.fig into xxx.ptx and xxx.pdf this software invokes two commands:
fig2dev -L pdftex <fig2devGenOptions> <fig2devPdfEpsOptions> xxx.fig xxx.pdf fig2dev -L pdftex_t <fig2devGenOptions> <fig2devPtxOptions> -p xxx xxx.fig xxx.ptx
Both commands specify the input file xxx.fig, both use the options given by the parameter fig2devGenOptions while each invocation allows to specify also specific options, fig2devPdfEpsOptions and fig2devPtxOptions, respectively, and both use the option -L to specify the output format (“language”).
The parameters specific for pdftex are called fig2devPdfEpsOptions because the options available are the same as for output format pstex creating eps-files. An example for a common option would be -b width which shall specify the same boundary for both formats; otherwise they do not fit.
For the output format pdftex_t, the option -p xxx says, that the string xxx must be included in xxx.ptx as \includegraphics{xxx}. Note that the option -p shall not be specified in fig2devPtxOptions, because it is automatically added.
Equivalent to mixed export with formats pdftex and pdftex_t which is appropriate for LaTeX-output format pdf, is the mixed export with the according formats pstex and pstex_t appropriate for LaTeX-output format dvi. The difference is that pstex creates an eps-file instead of a pdf-file with the same content and pstex_t creates a tex-file which looks like that created by pdftex_t except including the eps-file instead of the pdf-file. If the suffix is not given, pstex_t and pdftex_t create identical files. Thus exporting xxx.fig via
fig2dev -L pstex <fig2devGenOptions> <fig2devPdfEpsOptions> xxx.fig xxx.eps fig2dev -L pdftex <fig2devGenOptions> <fig2devPdfEpsOptions> xxx.fig xxx.pdf fig2dev -L pdftex_t <fig2devGenOptions> <fig2devPtxOptions> -p xxx xxx.fig xxx.ptx
and “inputting” xxx.ptx works for both LaTeX output formats.
Table 4.2 relates the language specified with the -L option with the suffix of the output file chosen canonically, the suffix we choose and the actual file format. In contrast to fig2dev, we choose the actual file format, except if this is TEX. We opted for the quite unusual suffix .ptx instead of .tex to avoid that TEX-files may be both, source files and created files, but this is not compulsory, since the same holds and is accepted for pdf-files.
| Output format (language) | xfig suffix | our suffix | format |
| pstex | pstex | eps | eps |
| pstex_t | pstex_t | ptx | tex |
| pdftex | |||
| pdftex_t | pdf_t | ||
Maybe xfig is intended to export from within the export dialog and not directly via a script like fig2dev. This may be the reason why the magnification must be set in the export dialog, but it is stored in the fig-file nevertheless.
Figure 4.1 shows the transformation of figures with fig2dev and the inclusion of the eps-file and of the pdf-file in the ptx-file. Note that the fig2dev-command is configurable via the parameter fig2devCommand, but there will be hardly any command with the same command line interface performing exactly the transformations given in Figure 4.1, except fig2dev itself.
At the same time, Figure 4.1 is an example for a LaTeX-file xxx.ptx created from a fig-file and embedded in this LaTeX-file with the \input-command. More than that, Figure 4.1 describes the way it has been created. Note that all text labels are specified with set “special”-flag, and are thus included as LaTeX-text, except the text postscript which is typeset with a postscript font to make the difference visible.
should be a picture
The term “gnuplot” refers to a file format and to a program gnuplot which can read this format, both described in [WK23].
Note that there seems no official file extension to identify gnuplot files. From the most common extensions .plt, .gpi and .gp we have chosen the one with the least collision and supported by Emacs, vscode and by my file browser: .gp.
The gnuplot format is a textual command language you can even program with and may thus be created with any editor but for sake of reproducibility it is recommended to use only files created by gnuplot. To ensure that a handwritten gnuplot file xxx.gp, e.g. with a single line like
plot [-10:10] sin(x), atan(x), cos(atan(x))
really works with the current gnuplot and to see how it is interpreted, it is recommended to convert it via
gnuplot -persist -e "load 'xxx.gp'; save 'xxx.gp'"
If you have a look inside the resulting file F4_03someGnuplot.gp, you can see, that in a comment line the current version of gnuplot is documented and also all the settings implicitly used. The original line is the last but one. Pasting the into VS Code, one can see the highlighting, of course provided the extensions described in Section 3.5.5 are installed.
Also, if a gnuplot file is created with an old version of gnuplot, it is recommended to update version with the same command. Note that gnuplot does not offer full backward compatibility.
This software supports including figures stored in .gp-files created by gnuplot. To export a file xxx.gp into several external formats, it uses gnuplot itself. According to the manual [WK23], Part IV, gnuplot supports output formats through so-called terminals. Among those are several ones intended for inclusion into LaTeX-files, like Cairolatex, Epscairo, Epslatex, Latex, Lua (tikz), Postscript, Ps(la)tex, Pstricks, Texdraw and Tikz which is in fact equivalent with Lua (tikz). Comparison with the manual [WK16] for older versions of gnuplot shows that support of Eepic, Mp and Tpic ended. Note that also export into the fig-format via the terminal Fig is supported which in turn may be included in latex as described in Section 4.3. Also, gnuplot pictures may be exported in MetaPost format which in turn may be included in latex as described in Section 4.5.
This software supports the export of a file xxx.gp only via the terminal Cairolatex which offers export to mixed PDF and LaTeX: graphics in PDF and text in LaTeX which yields the fonts typical for LaTeX. This is as described for fig-files in Section 4.3, except that text is generally converted in LaTeX-format, and not selectively those text marked with special flag.
Accordingly, the export yields two files xxx.ptx and xxx.pdf, both in the directory yyy in which xxx.gp resides. The file xxx.ptx must be imported via
\import{yyy}{xxx.ptx}
It contains the texts and includes xxx.pdf via \includegraphics{xxx} without specifying a suffix.
Unlike for fig-files, xxx.ptx and xxx.pdf are created with a single command:
gnuplot -e "set terminal cairolatex pdf <gnuplotOptions>; set output 'xxx.ptx'; load 'xxx.gp'"
Accordingly, xxx.ptx and xxx.eps are created with a single command:
gnuplot -e "set terminal cairolatex eps <gnuplotOptions>; set output 'xxx.ptx'; load 'xxx.gp'"
Note that this writes another but identical file xxx.ptx as no file endings are written and so xxx.ptx can include both, pdf and eps. When creating both performance is not optimal, but gnuplot offers no way to avoid this. If being strict, xxx.ptx is perfectly correct only for output eps, if comments and error messages are taken into account but as long as no error occurs, the result is perfectly ok also for pdf.
As for inclusion of fig-files, packages graphicx and color are needed.
Figure 4.2 shows the transformation of the plots and the inclusion of graphic files. In addition, Figure 4.3 shows an example of a LaTeX-file created from a gnuplot file and embedded in this LaTeX-file.
should be a picture
A vector graphic format, very native to TeX is MetaPost, a derivative of Metafont originally used to describe shape of fonts. Although seemingly supported by TeX only, MetaPost is interesting in its own right, as it is a graphical programming language, Turing complete, much like postscript, and allows also declarative programming. The manual describing the language is [Hob24], seemingly complete, but it is not. Thus, one can be thankful for [HH13] which offers some introduction and for the really helpful tutorial [Hec05].
Files containing MetaPost have the ending .mp. Note that there are other graphic formats like monochrome pictures in TIFF-format which are identified with the same extension but the MetaPost format has nothing to do with this.
Since MetaPost is a programming language, MetaPost files are created with an editor. Since MetaPost is very versatile, it is impossible to give an impression by a single example. We decided to choose an example using a MetaPost library, MetaUML, described in [Ghe19] for some reasons apparent later. The example file is given in Listing 4.2 and also on the web as F4_05someMetapost.mp. It is the source file of Figure 4.5. Pasting the into VS Code, one can see the highlighting, of course provided the extensions described in Section 3.5.5 are installed.
%prologues := 0;% default %%prologues := 3; %outputtemplate:="%{jobname}.%{charcode}";% default 4%outputtemplate:="%{jobname}%{charcode}.mps";% for latex %outputformat:="eps";% default input metauml; beginfig(1); % states 9 Begin.beginAll; %End.endAll; % State Standby State.Stopped("STOPPED")(); Stopped.w = beginAll.e + (20, 0); 14 State.Playing("PLAYING")(); %Playing.w = Stopped.e + (60, 0); State.Paused("PAUSED")(); Stopped.n = 0.5[Paused.n, Playing.n] + (0, 70); Playing.w = Paused.e + (120, 0); 19 %endAll.w = Standby.e + (20,0); Note.A("This is my aleph", btex $\aleph$ etex); A.e = beginAll.w + (-20, 0); 24 drawObjects(beginAll, Stopped, Playing, Paused, A); % feedback; links after draw: bad % links between states 29 link(transition)(beginAll.e -- Stopped.w); link(transition)(Stopped.e -- Playing.n); item.play(iAssoc)("[play()]") (play.sw = 0.5[Stopped.e, Playing.n]); link(transition)(Playing.nw -- Stopped.se); 34 item.stopPlaying(iAssoc)("[stop()]") (stopPlaying.ne = 0.5[Playing.nw, Stopped.se]); link(transition)(Playing.w + (0, +10) -- Paused.e + (0, +10)); item.pause(iAssoc)("[pause()]") (pause.s = 0.5[Playing.w, Paused.e] + (0, 10)); 39 link(transition)(Paused.e + (0, -10) -- Playing.w + (0, -10)); item.playPaused(iAssoc)("[play()]") (playPaused.n = 0.5[Paused.e, Playing.w] + (0, -10)); link(transition)(Paused.ne -- Stopped.sw); item.stopPaused(iAssoc)("[stop()]") 44 (stopPaused.nw = 0.5[Paused.ne, Stopped.sw]); endfig; endListing 4.2: An example file in MetaPost
Listing 4.2 illustrates some structure of MetaPost. As in TeX, comments start with % and end with the line or with the file. The proper figures are enclosed between beginfig(n) and endfig, where n is the number of the figure, the so called charcode2 , and the file ends with end. This software relies on specifying a single figure per file; the charcode is irrelevant.
Code outside figures is possible, but does not belong to a figure and is thus not displayed. In our example, besides end commands outside the figure are just input xxx, where xxx names a so-called library defined by the file xxx.mp and a sequence of settings of internal variables of the MetaPost compiler controlling how the following figure is compiled. Most of them even in comments.
The compiler for MetaPost is given by the parameter metapostCommand which defaults to mpost, occasionally just mp.
Each internal variable which can be set in the MP file can also be set when invoking mpost using the option -s 〈variable⟩=〈value⟩ as described in [Hob24], Section B.2.1. There it is stated that the option is read just before the file is read, which implies that the setting in the file overrides the command line setting. Caution: in the manual, the variable is referred to as “key”.
The most basic setting is outputformat:="eps" which is the only setting appropriate for latex. So don’t change3 . Note the strange default setting for the names of the output files, outputtemplate, which reflects the charcode of the individual figures as file ending. For inclusion in latex, the file ending mps is required and so frequently outputtemplate is set to reflect the ending. It seems more appropriate to make the setting in the command line which yields the following invocation
mpost -s 'outputtemplate="%{jobname}%{charcode}.mps"' xxx.mp
As we agreed that a MetaPost file shall contain a single figure only, we also ignore the charcode which unifies MetaPost with other formats supported. This yields
mpost -s 'outputtemplate="%{jobname}.mps"' xxx.mp
The MetaPost file shall not overwrite the command line settings.
The setting of prologues controls where fonts come from and becomes relevant when using TeX for typesetting. Listing 4.2, line 21 includes a label via a note implicitly, and for the material between btex and etex uses TeX. The manual [Hob24], Section 8.1 is on typesetting labels and specifies the meaning of prologues. If we stick to including in LaTeX and creating PDF out of that only, the default setting 0 is appropriate always but since this software uses DVI as intermediate format, e.g. to create HTML, or because for debugging one wants to view the MPS files standalone in a viewer things are not so easy. For details see [Hob24], Section 14.2. Setting prologues:=1 is deprecated. The only save way to get the correct display is to include fonts in the MPS file, setting prologues:=3, but this makes the MPS file quite big. So a good compromise is to set prologues:=2 as a command line option resulting in
mpost -s prologues=2 -s 'outputtemplate="%{jobname}.mps"' xxx.mp
and overwriting by need as in Listing 4.2, line 2.
As mentioned above, input xxx includes a library making the program dependent on a file xxx.mp. As for latex processors, also mpost records dependencies recursively in an FLS file if invoked with option -recorder. Also like latex processors, an error shall not cause break or interaction so adding the option -interaction=nonstopmode. Thus, we arrive finally at the default invocation
mpost -interaction=nonstopmode -recorder \
-s prologues=2 -s 'outputtemplate="%{jobname}.mps"' xxx.mp
Figure 4.4 illustrates how mpost converts an mp-file xxx.mp with the given settings into various result files:
an mps-file or with setting
outputtemplate="\%{jobname}\%{charcode}.mps"
more mps-files xxx1.mps…xxxn.mps,
a log-file xxx.log and a fls-file xxx.fls much like LaTeX does
and an mpx-file xxx.mpx containing the LaTeX text of the figure; this is not created if there is no such text.
Figure 4.5 gives an example of a MetaPost file included in this LaTeX-file as ab mps-file created from the MetaPost file and embedded in this LaTeX-file with the \includegraphics-command. Normally, \includegraphics is invoked with the filename without extension, but for mps-files, the extension is needed. As for inclusion of fig-files, the package graphicx is needed.
One of the descendants of MetaPost is TikZ (see introductory text [Cré11]) and one of the deficiencies resolved is that it allows passing information from the main document to the proper figure.
With lualatex this can be reached for MetaPost also using package luamplib. The package itself provides an environment mplibcode. Essentially, lualatex interprets all code enclosed in the mplibcode environment as MetaPost. As described in Section 3.5.2, this software can inject a header which loads the header and enhances it providing the additional command \inputmpcode which allows also load MetaPost from a file. The latter is preferred to direct inclusion with the mplibcode environment, e.g. for sake of proper code highlighting. Note that the package declaration is enclosed in an if construct, ensuring that the package is loaded only if lualatex or that like is run.
That this allows better integration within the enclosing latex document is illustrated by redefining the letter ℵ as α which is really related.
{% make redefine local \renewcommand{\aleph}{\alpha} \inputmpcode{F4_05someMetapost} }% to recover from redefine {manualC4graphics.tex}
Figure 4.6 Documents, that the redefinition really influences rendering in the MetaPost file.
Comparable with the xfig-format described in Section 4.3 but much more elaborate and widely used is the svg-format. There is a huge up-to-date official SVG 1.1 specification, [Da11] and a specification [Aa08] for SVG Tiny 1.2, which is itself quite short and more readable and gives also a good overview on “SVG Big”. For a tutorial, see [DHH02]. As stated in [Aa08], Section 1.1, SVG-files may contain vector graphics, raster images and text. It may also contain video and audio elements and may be interactive and dynamic, which goes beyond what can be included in LaTeX-files.
Figure 4.8 shows a picture in svg-format. As PDF-files are included directly via the \includegraphics-command, using the LaTeX-packages xcolor and graphicx, virtually, xxx.svg can be included directly via
%\includesvg[width=0.5\textwidth]{xxx}%
using the LaTeX-packages svg described in [Ilt12]. Note that the suffix of the file name shall be omitted.
A closer look shows, that graphic preprocessing is done behind the scenes in the course of a LaTeX-run creating files xxx.pdf and xxx.pdf_tex. As described for fig-files in Section 4.3 and for gnuplot-files in Section 4.4: The latter is a LaTeX-file containing text and including the former. To include xxx.pdf of course the LaTeX-packages xcolor and graphicx are required. Moreover, it may happen that the LaTeX-package transparent is required also, depending on the features used in xxx.svg.
As indicated in [Ilt12], Section 1, the svg-package delegates the transformation of xxx.svg xxx.pdf and xxx.pdf_tex to inkscape. This is a graphical editor with export functions which can be invoked in batch-mode also. Of course using the svg-package has the advantage that no explicit preprocessing is required, the created files updated by need. It is worth thinking about whether it is worthwhile writing according packages fig and gnuplot.
On the other hand, this breaks the workflow this software normally applies to graphic files. In particular, the package creates LaTeX main files which are not removed after the latex run if parametrized accordingly or if something goes wrong. Also, the svg-package does not provide the full flexibility of a standard solution. Since this software is still under construction and more than that, is in an experimental phase, we provide explicit preprocessing of SVG-files using inkscape. Another problem with the svg-package is, that according to [Ilt12], Section 1, it does not work on Windows platforms.
Some research shows, that inkscape in the version current at time of this writing exports mixed PDF and latex: If invoked as
inkscape --export-filename=xxx.pdf --export-area-drawing --export-latex xxx.svg
inkscape creates a file xxx.pdf containing all graphics but text and another file xxx.pdf_tex containing text and including xxx.pdf. The file xxx.pdf_tex can be integrated into the latex document as
\def\svgwidth{0.5\textwidth} \import{yyy}{xxx.pdf\_tex}%
Unlike fig2dev and gnuplot, specifying the files with their full path, has no effect, i.e. inclusion uses the file name only. Thus, \import cannot be replaced by \input and so the LaTeX-package import is required.
This is essentially the same technique as applied for fig-files and for gnuplot-files as described in Sections 4.3 and 4.4.
Analogously,
inkscape --export-filename=xxx.eps --export-area-drawing --export-latex xxx.svg
exports files xxx.eps_tex and xxx.eps.
In older versions of inkscape, there was a configuration allowing xxx.eps_tex to include uniformly both xxx.pdf and xxx.eps. Thus, xxx.pdf_tex could be deleted and xxx.eps_tex moved to xxx.ptx which in turn could be included into the main document.
As shown in Figure 4.7, for the current version of inkscape, this software filters xxx.eps_tex into xxx.ptx “manually” so that both xxx.pdf and xxx.eps are included in xxx.ptx. Then it deletes the original files xxx.pdf_tex and xxx.eps_tex.
The author has filed a bug report to the inkscape team, to avoid this workaround in the future.
should be a picture
In contrast to the FIG format, SVG pictures can be created by several programs. Among those, is also inkscape which can be used like xfig as a graphical editor with export functionality. In contrast to FIG format, SVG is essentially human-readable, in fact an XML derivative. The author calls it “essentially”, referring to the fact, that the format is quite wordy as is illustrated by the source code F4_07someSvg.svg for the above picture. Nevertheless, it can be an advantage to go into internals and manipulate with a text editor. Pasting the into VS Code, one can see the highlighting and a preview, of course provided the extensions described in Section 3.5.5 are installed.
Figure 4.9 shows some picture included as JPG. This is done as usual with the command \includegraphics provided by the package graphicx. According to the documentation [Car16], page 13, the bounding box must be provided somehow.
This may be done via the package bmpsize but alternatively also using the command ebb. There is some hint, that bmpsize does not work with xelatex. So maybe ebb is the better alternative. Note that both techniques are available in distribution TeX Live, but not in MiKTeX.
Research shows, that inclusion is seamlessly if PDF files are created. So the problem addressed is specific for creating DVI files. Also, at time of this writing, it seems that also in DVI mode, no problems occur. Nevertheless, the author experienced errors on missing bounding box and to be safe, provides a way to invoke ebb on the file xxx.jpg.
With parameter -m, this creates a file xxx.bb containing the bounding box for dvipdfm, and with parameter -x a file xxx.xbb containing an extended bounding box for dvipdfmx. The current implementation seems not to make any difference, whether the bounding boxes are created or not.
Sizes seem to differ in DVI/XDV output after conversion to PDF, depending on whether dvipdfm or dvipdfmx is used. Only the latter yields the same size as direct conversion to PDF creates.
Since bounding boxes seem superfluous, we control their creation with a parameter createBoundingBoxes whether to invoke ebb, which is false by default. Nevertheless, if we invoke, then we do twice, creating bounded boxes and extended bounding boxes.
FIXME: further research and further documentation is required.
Note that both for pdflatex and siblings creating PDF-output and for htlatex in conjunction with dvipdfmx files in the format pdf, png, jpg are supported. This list may be incomplete.
As an example, Figure 4.10 shows the same picture as PNG-file.
FIXME: At the moment, htlatex does not work with pictures at all.
Note that in DVI/XDV mode all usual LaTeX engines can include BMP-pictures, whereas in PDF mode only xelatex can do that, maybe because it creates XDV internally in any case. In contrast, lualatex and pdflatex can not.
