Extension:PGFTikZ

**MediaWiki extensions manual**
PGFTikZ; Release status: unmaintained
Implementation	Tag
Description	Parse PGF/TikZ input, generate and compile LaTeX file and upload resulting image
Author(s)	Thibault Marin, Markus Bürkler
Latest version	0.3.0 (2015-01-13)
MediaWiki	1.20+
PHP	5.3+
Database changes	No
License	GNU Lesser General Public License 2.1
Download	Download extension ; Git [?]: Download Git master; browse repository (GitHub); commit history; repository contributors (GitHub); code review;
	Parameters $wgPGFTikZdvipsPath; $wgPGFTikZLaTeXStandalone; $wgPGFTikZDefaultDPI; $wgPGFTikZLaTeXPath; $wgPGFTikZghostScriptPath; $wgPGFTikZLaTeXOpts; $wgPGFTikZepstoolPath; $wgPGFTikZuseghostscript;
	Hooks used ParserAfterTidy; ParserFirstCallInit;
Quarterly downloads	1 (Ranked 130th)
	Translate the PGFTikZ extension if it is available at translatewiki.net
Issues	Open tasks · Report a bug

The PGFTikZ extension generates images from PGF/TikZ input. See pgf project on SourceForge.

Usage

Enter PGF/TikZ code between <PGFTikZ> ... </PGFTikZ> tags.
The first line must be an image link line (see Help:Images) e.g. [[File:SampleImage.png|Sample image]]. Currently 'Image'/'Media' cannot be used instead of 'File' in the image link line. Once the image is uploaded, it will be rendered as if only the image link line was passed.
Within the <PGFTikZ> ... </PGFTikZ> block, the preamble necessary to compile the LateX file should be added between <PGFTikZPreamble> ... </PGFTikZPreamble> tags.
After the preamble, the PGF/TikZ input can be entered as it would be after the \begin{document} entry of a LaTeX document (note that the \begin{document} and \end{document} markups should not be added in the PGFTikZ block).
Example (based on wikipedia:File:Neighbourhood_definition2.svg):

<PGFTikZ>
[[File:My_image_1.png|400px|test image]]

<PGFTikZPreamble>

\usepackage{tikz}
\usetikzlibrary{arrows}
\usetikzlibrary{intersections}
\usetikzlibrary{calc}

</PGFTikZPreamble>
\begin{tikzpicture}[scale=.8,every node/.style={minimum size=1cm}]
%
   \begin{scope}[
           yshift=-83,every node/.append style={
           yslant=0.5,xslant=-1},yslant=0.5,xslant=-1
           ]
       \draw[step=4mm, black] (0,0) grid (5,5); 
       \draw[black,thick] (0,0) rectangle (5,5);%borders
       \fill[green] (2.05,2.05) rectangle (2.35,2.35); % center pixel
       \fill[green] (1.65,2.05) rectangle (1.95,2.35); %left
       \fill[green] (2.45,2.05) rectangle (2.75,2.35); %right
       \fill[green] (2.05,2.45) rectangle (2.35,2.75); %top
       \fill[green] (2.05,1.95) rectangle (2.35,1.65); %bottom

   \end{scope}
%
% draw annotations
%
   \draw[-latex,thick,green](-3,-2)node[left]{1 patch}
       to[out=0,in=200] (-1,-.9);
\end{tikzpicture}
</PGFTikZ>

DO NOT modify the content of the [[File:SampleImage.png]] wikipage directly. The image is regenerated when a wikipage requires it.
Parameters can be added to the tag line <PGFTikZ param=value>:
- <PGFTikZ dpi=250> sets the resolution to 250 dots per inch.
- <PGFTikZ update=1> forces an update of the image and its page (should rarely be used).

How it works

The extension works as follows:

The filename of the image to upload is extracted from the first line of the block ([[File:SomeImageFile.png]]).

If an image with the desired filename exists and was generated by this extension, the current input source is compared to the existing file's. If they are identical, no compilation is required and the image is rendered. If the file exists but differs (or if it does not exist), a new image is uploaded. Note that if the desired image filename already exists and was not generated by this extension, upload will be cancelled.

The PGF/TikZ code (preamble and body) is extracted from the block, and stored in a temporary LaTeX file similar to the following one:

\documentclass{article}
\def\pgfsysdriver{pgfsys-dvips.def}
\usepackage[usenames]{color}

[... Content of PGFTikZPreamble block...]

\begin{document}
\thispagestyle{empty}


[... Main content of PGFTikZ block...]

\end{document}

The generated LaTeX file is compiled and an image (with extension passed in the image link) is generated using the following sequence of commands:

Ghostsript way: default (and recommended for portability) from v0.3
- latex (generates a .dvi file from the input .tex)
- dvips (.dvi to .ps)
- ghostscript (converts the .ps file to the final image file)
Old way: (pre v0.3) using epstool
- latex (generates a .dvi file from the input .tex)
- dvips (.dvi to .eps)
- epstool (to extract a minimal bounding box from the .eps file)
- convert (converts the .eps file to the final image file)

The compiled image file is uploaded to the wiki, and the source used to generate it is stored in the file description.
Note that starting from v0.3, the LaTeX compilation uses the standalone package to produce a minimal page. This can be disabled (reverting to the pre v0.3 behavior) by setting $wgPGFTikZLaTeXStandalone to false in LocalSettings.php (see the Configuration parameter section).

Installation

Download and move the extracted PGFTikZ folder to your extensions/ directory.
Developers and code contributors should install the extension from Git instead, using:cd extensions/ git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/PGFTikZ
Add the following code at the bottom of your LocalSettings.php file:
```
wfLoadExtension( 'PGFTikZ' );
```
Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Configuration parameters

The following parameters can be set in the LocalSettings.php page after loading the extension (the values given here are the default values):

// Default resolution for generated images
$wgPGFTikZDefaultDPI  = 300;

// Full path to LaTeX executable
$wgPGFTikZLaTeXPath = 'latex';

// Command line options to LaTeX command
$wgPGFTikZLaTeXOpts = 'no-shell-escape'

// Full path to dvips executable
$wgPGFTikZdvipsPath = 'dvips';

// Either use epstool+imagemagick or ghostscript to generate image
$wgPGFTikZuseghostscript = true;

// Full path to 'epstool' executable
$wgPGFTikZepstoolPath = 'epstool';

// Full path to 'ghostscript' executable
$wgPGFTikZghostScriptPath = 'gs';

// Use standalone LaTeX package
$wgPGFTikZLaTeXStandalone = true;

Requirements

Programs

latex with the PGF/TikZ package.
dvips
ghostscript if $wgPGFTikZuseghostscript is set to true (default from v0.3)
epstool if $wgPGFTikZuseghostscript is set to false or if using a pre v0.3 version
Enable file uploads (see Manual:Image administration)
ImageMagick must be installed and enabled if using the epstool+convert way (see $wgUseImageMagick ). The $wgImageMagickConvertCommand variable should point to the convert executable.

Troubleshooting

You may have to increase the amount of memory available for shell programs by modifying the $wgMaxShellMemory variable in LocalSettings.php .

$wgMaxShellMemory = 202400;

If experiencing problems compiling with LaTeX see the Manual:$wgUseTeX and Manual:Enable_TeX pages.

Security

Since the extension internally compiles LaTeX documents from user input, security must be considered before deploying the extension on public wikis.

Some of the possible attacks that must be considered when deploying a web-based LaTeX compilation system are described in the TUG article: "A web-based TeX previewer: The ecstasy and the agony" ([[1]]):
- Execution of the system commands via wfShellExec offers control on resource limits given to the system call using $wgMaxShellMemory and $wgMaxShellTime variables.
- The source stored in the LaTeX file can also compromise security. The texmf.cnf file can be used to block access to files from within the generated LaTeX file. See [[2]] for a discussion on the matter.

Download

Please download the code found below and place it in $IP/extensions/PGFTikZ/. Note: $IP stands for the root directory of your MediaWiki installation, the same directory that holds LocalSettings.php .

Note that the bitbucket links will be closed once the latest version is merged in the mediawiki repository.

version 0.3.0

The latest version (with fixes to work on Windows hosted wikis) (v0.3.0, waiting for mediawiki review) is available at: https://bitbucket.org/thibaultmarin/pgftikz_public/get/v0.3.0.zip

Mediawiki repository

The extension can be retrieved directly from Git ^[?]:

Browse code
Some extensions have tags for stable releases.
- Browse tags
- Select the tag
- Click "snapshot"
Each branch is associated with a past MediaWiki release. There is also a "master" branch containing the latest alpha version (might require an alpha version of MediaWiki).
- Browse branches
- Select a branch name
- Click "Continue"

Extract the snapshot and place it in the extensions/PGFTikZ/ directory of your MediaWiki installation.

If you are familiar with Git and have shell access to your server, you can also obtain the extension as follows:

cd extensions/ git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/PGFTikZ.git

Known problems

This is an early stage, expect rough edges. Known bugs/limitations include:

When using preview and save repeatedly, edit conflicts might occur in some cases. The edit conflict redirects to a resolution page where the input PGF/TikZ code is mixed up with the image automatically generated description page. Cancelling the conflict (maybe even deleting the image) and regenerating the page should fix the problem.
If two pages link to the same file with different content, the image will be re-compiled each time either page is displayed.
Probably many more, please report them.

PGFTikZ Release status: unmaintained
Implementation	Tag
Description	Parse PGF/TikZ input, generate and compile LaTeX file and upload resulting image
Author(s)	Thibault Marin, Markus Bürkler
Latest version	0.3.0 (2015-01-13)
MediaWiki	1.20+
PHP	5.3+
Database changes	No
License	GNU Lesser General Public License 2.1
Download	Download extension Git ^[?]: Download Git master browse repository (GitHub) commit history repository contributors (GitHub) code review
Parameters $wgPGFTikZdvipsPath $wgPGFTikZLaTeXStandalone $wgPGFTikZDefaultDPI $wgPGFTikZLaTeXPath $wgPGFTikZghostScriptPath $wgPGFTikZLaTeXOpts $wgPGFTikZepstoolPath $wgPGFTikZuseghostscript
Hooks used ParserAfterTidy ParserFirstCallInit
Quarterly downloads	1 (Ranked 130^th)
Translate the PGFTikZ extension if it is available at translatewiki.net
Issues	Open tasks · Report a bug