# tutorial for making tikz/pgf library

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?

-
As one of the authors, I can say that there was no rhyme or reason in their design (at least of my parts)! I made it up as I went along. I would actually like it if they could be reverse engineered so one strategy would be to have a public conversation in which you tried to reverse engineer one of mine. This could start in the "From answers to packages" chat room and morph into a blog post if it works. How would that sound? –  Andrew Stacey Sep 29 '11 at 17:13
@AndrewStacey, that sounds very good. I'll head over to the chat room later this week. I would also love to know about some other tutorials/howtos, but I guess you are offering to write one in real time! Thank you. –  Sam Lisi Oct 4 '11 at 16:50
From the deafening silence in the "answers" section here, I would guess that the answer is "None". So maybe you could alter your question to something like "I want to write a tikz-based package; what TikZ/PGF-specific things should I be aware of? For those who've written such packages, what do you wish you'd known when you started out?" (probably CW). Then the answers could become the missing guide. –  Andrew Stacey Oct 20 '11 at 8:51
Sorry because I have some difficulties to understand some subtleties in english but a tikz-based package is not exactly a tikz/pgf library. I'm not a great expert like Martin, Andrew, Stephan and some others but I create a little example named tikzrput with surely some defaults. You cand find it here tex.stackexchange.com/questions/45351/… . It's a tikz-based package but not a library. –  Alain Matthes Feb 23 '12 at 11:36
@AndrewStacey: I think all your comments can be switched to an answer ;-) –  Marco Daniel Mar 3 '12 at 23:54

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}}
\DeclareOption{#1}{\edef\tcb@optionlist{\tcb@optionlist,#1}}%
}


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.

-
Wow! Thank you so much! –  Sam Lisi Mar 21 '12 at 22:13
@SamLisi Thanks! Looking forward to your first package;) –  Yiannis Lazarides Mar 21 '12 at 22:14