• View
• Edit
• Upload
• History
• Print

UsingTikZ-PGF

This page documents some special settings needed if you work with specific features of TikZ/PGF

PGF is a macro package for creating graphics with LaTeX. It allows you to define simple or complex graphics which embed nicely into your documents, as they take up the document's fonts and scale elegantly (cf. this collection of examples). PGF comes with a user-friendly syntax layer called TikZ.

TikZ/PGF files can be included in LyX documents like normal sub-documents (via Insert→File→Child Document...→Input) or directly via TeX Mode. This page documents cases where a bit more effort is needed to make PGF features work with LyX.

1.  Using the external library

The PGF external library is nice particularly if you have many PGF graphics in your document. Generating these graphics (which is done each time you compile your document) can be time-consuming and thus slows down the compilation process of your documents. The external library greatly optimizes this process in that it produces PDF versions of the graphics which are used rather than producing them on the fly each time. Only if PGF code is changed, the graphics are re-created; new graphics are automatically added. See the TikZ/PGF manual, chapter Externalization Library, for details.

You can use this feature with LyX, but some efforts are needed, as described in what follows.

1.1  Enabling "shell escape" mode

In order to do its work, the external library needs to call some external programs (that create and write the new graphics). LaTeX allows such execution through its "shell escape" mode, which is however disabled by default for security reasons (since any kind of commands, also destructive ones, can be launched through it). In order to enable this mode in LyX for a given document, go to Document→Settings...→Formats and check Allow running external programs. If you compile your document now, LyX will ask you whether your trust this document and agree that it runs external programs. Never do this if you don't trust a document, but since this is your own, you can safely click "Trust always", and you won't be asked again for this document. Note, however, that for security reasons, Allow running external programs is only active for the current computer. If you send the document to somebody else or use it on a different machine, you need to re-enable it as described in this section.

After you have done this, the external mode will already work. However, since LyX uses a temporary directory for file compilation, which is deleted when the document is closed, all graphics will be re-created if the document is re-opened, which somehow defeats the purpose of the external feature. For a better experience, you need to use the prefix mode and again add some extras.

1.2  Using file prefix

The external library has an option prefix which makes the generated graphics be stored in a subdirectory. Especially with many graphics, this is useful to prevent cluttering of the directory where the main document resides. If you use LyX, the prefix mode is also the precondition to use externalization feature properly at all. In what follows, we assume this subdirectory is named pics, and your document resides in /home/paula/thesis/ (so the graphics end up im /home/paula/thesis/pics/). Adapt this to your needs.

The prefix is activated in Document→Settings...→ Preamble via

Now this does not work as is with LyX, as LyX uses the temporary directory to compile files. While LyX will see and read your graphics in /home/paula/thesis/pics/, it cannot write new or updated graphics to that directory. Again, this is for security reasons. LaTeX disallows writing of files outside the current working directory (for good reasons, consider a document that can execute arbitrary commands on your whole computer!).

In order to make things work, add the following to Document→Settings...→ Preamble (but read the next section if you are using Windows):

This make use of two packages: shellesc is a package that enables easy execution of commands via the shell escape channel, atveryend executes its content after the LaTeX document has been completely typeset. What the code does is this (again adapt the paths and folder names to your needs here):

1. It creates a symbolic link from the temporary directory to the pics/ subdirectory (via the Unix command ln -s /home/paula/thesis/pics pics). The part before the ; (rm -f pics) removes an existing link before creating a new one. If this is missing, a link inside the target directory will be created if the link already exists (this is how the ln command works, but it is not what you will want here).
2. After the document has been processed, this symbolic link is removed (again via the Unix command rm -f pics). This is necessary since otherwise LyX won't delete the temporary directory when the file is closed.

This method assures that:

1. PGF files are only (re-)created if they do not exist yet or if the code has been changed
2. All created files are stored in the pics/ subfolder in your working directory (in the example: /home/paula/thesis/pics/)

1.3  Adaptations for Windows

The code given above works for Linux and macos. On Windows, you need the following commands instead (untested!):

• mklink /d pics C:\Users\Paula\Documents\Thesis\pics to generate the symbolic link
• rmdir pics to delete at link at the end

2.  Categories

Category: PGF