Example¶

Here’s a short and basic example showing how the environment looks compiler and how it works:

• PDF document
• Source

Getting it¶

The source code is available at github.

Include ppprog.sty with your LaTeX document or import it into your package directory. Then include it in your document:

\usepackage{ppprog}

The ppprog environment¶

You can then typeset using the ppprog environment, for instance:

\begin{ppprog}[\NewProgram]{insert-unique}
    \Proc{insert}{e, \mathbb{S}}
        \If{e \in \mathbb{S}}
            \pp \Return{\mathbb{S}}
        \Else
            \pp \Return{\mathbb{S} \cup e}
        \Fi
    \EndProc
\end{ppprog}

The environment has one mandatory and one optional parameter. You have to provide a name of the algorithm as the mandatory argument. This will be used to create labels automatically at certain points in the program (see: Procedures and functions). Here, the name of the program is insert-unique. Only use characters here that can be used in labels (so no spaces or underscores, for instance).

The optional argument is used to decide from what number to start counting lines in the program. This argument can be set to \NewProgram (like in the example above) which will start counting the lines from 1. If you omit the argument altogether, ppprog will also start numbering lines from 1.

\begin{ppprog}{some-program}
    ...
\end{ppprog}

You can also set it to start on whatever line number the last program ended on using \ContinueProgram—this is helpful if you want to split your program into smaller chunks but want it to still appear as if it were a continuous thing.

\begin{ppprog}[\NewProgram]{some-program-part-1}
    ...
\end{ppprog}

\begin{ppprog}[\ContinueProgram]{some-program-part-2}
    ...
\end{ppprog}

You can also specify any starting line number you want using \ProgramStartsAtLine{n} where n would be the actual line number. This can be use for explicit exerpts.

\begin{ppprog}[\ProgramStartsAtLine{15}]{exerpt-of-program-from-line-15}
    ...
\end{ppprog}

Once inside the ppprog environment you are basically in LaTeX math mode, so you can use any mathematical symbols you want. You also don’t have to worry about indentation or whitespaces in general.

The ppprog environment can be embedded into a figure environment, a minipage, etc. or just placed alongside your run-of-the-mill text.

The basics¶

To start a new line in the ppprog environment you will (with some exceptions I will describe later) have to use \pp. This creates a new numbered line that you can fill up any way you like. The line is in math mode by default.

\begin{ppprog}{alg}
    \pp \text{Hello world!}
    \pp x = 2^n
\end{ppprog}

If you need to break the line for any reason it is best to use \ppempty or its alias \ppmt. This will create a new line with a continuation symbol instead of a line number.

\begin{ppprog}{alg}
    \pp x = 2^n + a_x, y = 2^m + a_y, \text{ and }
    \ppmt z = 2^k + a_z
\end{ppprog}

You can change the line continuation symbol by reloading the \ppemptylinesymbol command. For example:

\def\ppemptylinesymbol{\Bat}

If you really need to (although I would not recommend it) you can also use some raw low-level commands. \\ will break the line, & will mark the point where line numbering ends and the contents begin, \ppin will bring the indentation of the current line to the level in the preceeding line, and \ppdectabdepth and \ppinctabdepth will respectivelly decrease and increase the depth of the indentation. Do not use these unless you really must.

\begin{ppprog}{alg}
    \pp x_0 = 2^n \\
    \ldots & \ppin x_i = 2^{n + i}
\end{ppprog}

Procedures and functions¶

Typically your algorithm will consist of one or more function or procedure. Commands \Proc and \Func are your friends there. They each take two parameters: the first is the name of the procedure and the second is the list of the procedure’s or function’s parameters. The commands typeset the relevant keyword, the name, and the parameter list in parentheses and the symbol \(\triangleeq\). It also sets the next line to be indented.

Commands \Proc and \Func will use the name to create a label at the line where they are placed. So you can then refer to them by name and the name of the algorithms they are in with the command \pplineref. Details on that are in the Cross-referencing section.

When are finished with your procedure or function insert \EndProc or \EndFunc respectively. This mainly removes the indentation that was present inside the procedure body it also adds spacing between functions. You can add additional space by using \ppbreak after \EndProc or EndFunc—this won’t create a new line but spread the functions out a little bit. If you want to spread the functions out more (or less) then use \ppbreak with a parameter wherein you define the length of the gap.

\begin{ppprog}{procsandfuncs}
    \Proc{dostuff}{a, b}
        ...
    \EndProc

    \Proc{dootherstuff}{}
        ...
    \EndProc
    \ppbreak{1cm}

    \Func{countstuff}{x, y, z}
        ...
    \EndFunc
\end{ppprog}

Since I am interested in distributed algorithms ppprog also has a little variation on the procedures and functions that allows to prepend some sort of site or location information to the procedure. This can also be used to prepend anything else to the procedures and functions however. The variants are \DistProc and \DistFunc and they work just like ordinary \Proc and \Func but have an extra (2nd) argument.

\begin{ppprog}{procsandfuncs}
    \DistProc{dodistributedstuff}{@s_1}{a, b}
        ...
    \EndProc

    \DistFunc{countdistributedstuff}{@s_2}{x, y, z}
        ...
    \EndFunc
\end{ppprog}

There is no special way to refer to functions or procedures after they were defined, but I recommend you use the command \ppfunction for that purpose. It will change the font of the word to normal text.

\begin{ppprog}{procreferenced}
    \Proc{recproc}{x}
        \pp \ppkeyword{recproc}(x + 1)
    \EndProc
\end{ppprog}

Flow control statements¶

Control flow in the form of loops and if-statements and such like is another big part of every algorithm. So there are structures for that sort of thing in ppprog.

\begin{ppprog}{cases}
    \If{x > 5}
        ...
    \Elif{x > 3}
        ...
    \Else
        ...
    \Fi
\end{ppprog}

\begin{ppprog}{nonsensereally}
    \If{x \in S}
        \pp S' = S \setminus \{ x \}
        \pp S' \cap S
    \Else
        \pp S \cap \varnothing
    \Fi
\end{ppprog}

\begin{ppprog}{loops}
    \For{\forall x \in X}
        ...
    \Done

    \Foreach{x \in X}
        ...
    \Done

    \While{x < 10}
        ...
    \Done
\end{ppprog}

\begin{ppprog}{loops}
    \Foreach{x \in X}
        \pp S \leftarrow S \cup \{ x \}
    \Done
\end{ppprog}

Font styles and various keywords¶

Algorithm descriptions often make use of fonts to distinguish certain words from others. There are some common predefined font styles in ppprog that may be handy for that. There is also a (limited) number of useful keywords that are already defined.

\begin{ppproc}{fonts}
    \Proc{something}{\ppvariable{x} \in \pptype{Integer}}
        \pp \ppfunction{sleep} 5
        \If{x \ppkeyword{mod} 2 = 0}
           \pp \ppvariable{y} \leftarrow \ppliteral{"even"}
        \Else
           \pp \ppvariable{y} \leftarrow \ppliteral{"odd"}
        \Fi
    \EndProc
\end{ppproc}

\begin{ppproc}{atomic}
    \Proc{next}{s}
        \pp \Lock{s}
        \pp s \leftarrow s + 1
        \pp r \leftarrow s
        \pp \Unlock{s}
        \pp \Return{r}
    \EndProc
\end{ppproc}

\def\newstyle#1{{\bf #1}}

\def\newkeyword{\ppkeyword{new~keyword}}
\def\newliteral{\ppliteral{new~literal}}

\def\newkeyword#1{\ppkeyword{new~keyword}(#1)}

Cross-referencing¶

If you want to refer to code within your text you can assign labels to certain lines and simply use ref or pplineref a command provided by pprog.

 \begin{ppproc}{atomic}
    \Proc{next}{s}
        \pp \Lock{s}           \pplab{lock}
        \pp s \leftarrow s + 1
        \pp r \leftarrow s
        \pp \Unlock{s}         \pplab{unlock}
        \pp \Return{r}
    \EndProc
\end{ppproc}

The lock is obtained at \pplineref{atomic}{lock}
and released at \pplineref{atomic}{unlock}.

The lock is obtained at line~\ref{line:atomic-lock}
and released at line~\ref{line:atomic-unlock}.

 \begin{ppproc}{atomic}
    \Proc{next}{s}
        \pp \Lock{s}
        \pp s \leftarrow s + 1
        \pp r \leftarrow s
        \pp \Unlock{s}
        \pp \Return{r}
    \EndProc
\end{ppproc}

Atomic incrementation is shown as procedure \emph{next}
(\pplineref{atomic}{next} in the pseudocode).

Atomic incrementation is shown as procedure \emph{next}
(line~\ref{line:atomic-next} in the pseudocode).