TikZ-PGF Package Writing – Tutorial for Making TikZ/PGF Library

package-writingtikz-pgf

I am very impressed with the tikz/pgf libraries created by this community at http://launchpad.net/tex-sx.

I would like to create my own too, but don't know where to start. I have tried to reverse engineer the packages I linked to, but find them too sophisticated to have a clue as to what is going on.

I had previously asked what tutorials/howtos are available to teach novices how to develop a tikz/pgf library, but am editing my question to take in to account Andrew Stacey's suggestion:

I want to write a tikz package. For those of you with some experience, what would you go back in time to tell your novice self about?

Best Answer

As there are no tutorials for exactly what you are asking, I will endeavor to provide a short one here to provide an answer to the question, and with the hope that other more experienced users will provide additional information. To understand properly the development of a tikZ/pgf package/library one has to distinguish between the different aspects of the question.

Writing a LaTeX Package

To write a LaTeX package is a fairly simple procedure. One has to save the file with the extension .sty and include a few lines of mandatory code:

   \NeedsTeXFormat{LaTeX2e}
   \ProvidesPackage{tower}[2012/02/03 v1.0a Draw towers package]
      ....
   \endinput

A more comprehensive guide is provided in the clsguide and there is also a lot of information on this site as well.

Writing your Package in Literate Style

If you browse through the code of most packages or classes, you will observe that the documentation is provided with the code in .dtx files (with the exception of pgf and tikZpackages, but more about this later). What enables this method of writing is the doc/docstrip system developed by Frank Mittelbach, David Carlisle and others. The doc software can automatically generate indexes of definitions, indexes of command use, and change-log lists.

The doc system is very useful for maintaining and documenting large TeX sources, such as the LaTeX2e code. LaTeX classes and packages written using this can be processed in two ways: they can be run through LaTeX, to produce documentation; and they can be processed with docstrip, to produce the .cls or .sty file.

A basic template, where you can just simply type in your code and user manual can be found at tex-sx

PGF/TikZ Libraries

Most of the packages at tex-sx are packages and not libraries. A pgf library is a file with the specific extension tikzlibrary<filename>.code.tex. Instead of being loaded as \usepackage{...}, they are loaded as \usetikzlibrary{...} or similar.

There are two advantages in using such a method. Firstly it organizes the code in a hierarchy which is easier to manage and second the underlying loading mechanism can be used transparently to load the code in LaTeX, TeX Plain or ConTeXt formats.

Other package authors design their own library loading mechanisms following the same style. A great example to study is the tcolorbox package. The extract below shows that a library simply defines the code and when loaded the right paths are set. Some list management code is provided to keep track of options, available libraries for the package and error trapping. 

 \def\tcblibrary@documentation@loaded{}
 \def\tcb@optionlist{}
 \def\tcbuselibrary#1{\tcbset{library/.cd,#1}}
 \def\tcb@add@library#1#2{%
    \tcbset{library/#1/.code={\@ifundefined{tcblibrary@#1@loaded}{\input #2}{}}}%
    \DeclareOption{#1}{\edef\tcb@optionlist{\tcb@optionlist,#1}}%
  }
 \tcb@add@library{listings}{tcblistings.code.tex}
 \tcb@add@library{theorems}{tcbtheorems.code.tex}
 \tcb@add@library{documentation}{tcbdocumentation.code.tex}

Writing a Package for tex-sx

Most of these packages were originally answers to questions, which were later refined and published as packages. There are some very impressive packages on the current list. If you want to contribute it is very easy and the best place to start is to come over to chat and speak to people like Andrew Stacey who was instrumental in kick starting it and either Andrew or one of the other contributors can provide valuable advice.

As a closing remark, most of the pgf family of large packages are not written in .dtx files but rather use variants of the pgfmanual package. This enables examples to be typeset as well as executed in the user documentation and also provide a consistent feel and look with the pgf/tikz style manuals.

Suggestion for a Package

There is a great need for a good TikZ library for Computer Science and enough questions and answers on this site to kick start it.

Related Question