1

I love the way tikz's (and tizk-cd's) documentation is formatted with clickable links to go to the definition of a style/command, colors, examples with image and code next to each others etc… As mentionned here Package to obtain the style of the TikZ/PGF-Documentation pgfmanual seems to provide such functionalities but has not been documented.

Would it be possible to have quick introduction to how to use pgfmanual, together with pointers to explore more advanced options?

tobiasBora
  • 8,684
  • See 1.5 Authors and Acknowledgements in the packages documentation. Manual use (as well all other similar LaTeX documents with hyper text facility) hyperref package for this. – Zarko Oct 10 '21 at 07:41
  • @Zarko : thanks, but I don't see how this acknowledgement is helping, it is just a list of people. And I huess hyperref is used internally, but I guess other mechanisms are involved to automatically add links to code… It would be way too tedious to do it manually. – tobiasBora Oct 10 '21 at 10:31
  • 1
    In Acknowledgement is clearly stated who add hypertext to manual. Yes, this is demanding manual task. you need to insert ˙hyperref anchoes. In this can be of help editor. Ho to do this, see documentation for hyperref package. – Zarko Oct 10 '21 at 10:41

1 Answers1

3

Here is a minimal example for how to use the PGF manual style. Note the following requirements

  1. You must use the ltxdoc documentclass.
  2. The packages calc, tikz and hyperref are required.
  3. The “optional” argument of codeexample is not really optional. Even if it is empty, there have to be empty brackets [].

I recommend using the hidelinks option for hyperref to hide the red boxes around links in the PDF. In general the hyperref package should be loaded as late as possible (see also Which packages should be loaded after hyperref instead of before?).

Since PGF 3.1.6 the file pgfmanual-en-macros.tex is installed into the TeX search path. Before that version you have to go to the PGF documentation directory and copy the file into your working directory.

\documentclass{ltxdoc}
\usepackage{calc}
\usepackage{tikz}
\input{pgfmanual-en-macros.tex}
\usepackage[hidelinks]{hyperref}
\begin{document}

\begin{command}{\textbf\marg{text}}
  Prints its argument in bold.
  % These empty brackets are NOT optional
  %                |
  %                v
\begin{codeexample}[]
\textbf{This is a test}
\end{codeexample}
  %
\end{command}


\begin{environment}{{center}}
  Center text horizontally on the page.
  %
\begin{codeexample}[vbox]
  \begin{center}
    \textbf{This is a test}
  \end{center}
\end{codeexample}
  %
\end{environment}


\end{document}

enter image description here

If for some reason you want to document starred commands separately with the command environment, see this workaround.

Henri Menke
  • 109,596
  • Thanks a lot! I tried to compile this example but it gives ERROR: Package pgfkeys Error: I do not know the key '/codeexample/prettyprint/comment font', to which you passed '\itshape ', and I am going to ignore it. Perhaps you misspelled it.. Any idea what's wrong? Also, I'm curious, what's the link between pgfmanual-en-macros.tex and pgfmanual? – tobiasBora Oct 10 '21 at 18:27
  • So I managed to make this code work by copying this folder https://github.com/pgf-tikz/pgf/tree/247f1f0445a9e996560c9f5a9b3fb03a4184e6ec/tex/latex/pgf/doc onto the working directory. I'm not sure why because I'm on a quite recent TeX distribution (TexLive 2021, Tikz/pgf version 3.1.8b). Thanks a lot! – tobiasBora Oct 11 '21 at 04:35
  • Also, for example on how to add environments with optional arguments, see https://github.com/astoff/tikz-cd/blob/c1eb4c96291b48a4a7f9f348b2e22473dd48de3d/tikz-cd-doc.tex#L227 – tobiasBora Oct 11 '21 at 04:43
  • Also a question: how can I use environments like \begin{center} \end{center} or itemize inside a codeexample? They all fail. – tobiasBora Oct 11 '21 at 05:02
  • @tobiasBora You can't. pgfmanual-en-macros.tex was designed to only work for the purposes of the PGF manual. There is zero support for any other use-case. – Henri Menke Oct 11 '21 at 07:48
  • Ok thanks. That said, I found an example that was using the pre and post arguments to insert a minipage around the code… it may be enough? Also, any idea how I could force the code to be on a different line that the picture? Sometimes it does it automatically (even if code fits on the right) but sometimes it does not (even if the code goes inside the margin). – tobiasBora Oct 11 '21 at 16:43
  • 1
    @tobiasBora To typeset examples that need a paragraph, use the vbox option (see updated answer). To break all codeexamples use \pgfkeys{/codeexample/every codeexample/.append style={width=0pt}}. As you can see the options get more and more obscure. That's because there is absolutely no support! – Henri Menke Oct 11 '21 at 17:01
  • Thanks a lot! Too bad this library is not supported, it's just great! – tobiasBora Oct 11 '21 at 18:37