Tutorial

Once installed, Sysquake for LaTeX is a LaTeX package which you can use as easily as any other package. In this tutorial, we will create a technical report which analyzes some of the properties of a rational function.

Sysquake for LaTeX works at the level of the TeX program, which, with LaTeX definitions, is usually called latex for creating DVI files, or pdflatex for creating PDF files. You can also choose among different applications which hide the details of running latex and displaying the result, such as emacs on unix platforms, TeXShop on macOS, or Texmaker on Windows and other platforms. Sysquake for LaTeX is perfectly compatible with them; actually it just ignores them. So you can keep your favorite editing environment.

And now, let us begin!

Remark: the complete source file of another example comes with Sysquake for LaTeX.

Creating a LaTeX file

Use your usual method to create a LaTeX file and write a few things to check that everything runs correctly. For this tutorial, we will make a report. The LaTeX file, named for example sq-tutorial.tex, contains something like

\documentclass[11pt]{report}
\begin{document}

\title{Sysquake for \LaTeX{} tutorial}
\author{Calerga}
\date{13 August 2007}
\maketitle

\end{document}

Add the Sysquake package

Packages are sets of definitions which add new commands to LaTeX. They are listed in the preamble of LaTeX files, between \documentclass and \begin{document}. The Sysquake package is added like any other package:

\documentclass[11pt]{report}
\usepackage{sysquake}
\begin{document}
...

If there is an error when you typeset this file, the file sysquake.sty is probably not found. Please refer to section Sysquake for LaTeX Installation for more informations.

Assuming there is no error, we can now use LaTeX commands for invoking Sysquake.

Your first Sysquake computation

Since we are anxious to get a result, let us begin with something really simple. We will insert the result of 5+2 as an equation. Add the following line between \maketitle and \end{document}:

We all know that $5+2=\sqexpr{5+2}$, don't we?

Running LaTeX twice will produce the result you expect. Why twice? Like other features of LaTeX, the Sysquake package needs two phases to do its magic. During the first phase, commands create a file named sq-tutorial.lme (the name is built after the .tex file) which contains Sysquake code, or more exactly code written in the programming language of Sysquake, LME. During the second phase, loading the sysquake package runs the command-line tool sysquakelatextool to interpret this file. The result is written to a file named sq-tutorial.lmeout and, if there are graphics, to EPS files. This file contains the result as LaTeX definitions; for instance, \sqexpr{5+2} above creates the following definition:

\def\lmefragi{%
7}

Here, the name is \lmefrag followed by the expression number in lowercase roman notation (this might change in future versions). Sysquake commands, in addition to producing sq-tutorial.lme, also invoke the corresponding definition to insert the result in the final typeset document.

Note that typesetting documents is often already performed by running latex twice, or even more times, to resolve cross-references and update the table of contents and the index. So there is nothing new.

Formatted results

Our first expression could have been computed in plain LaTeX, which gives access to the computation capabilities of TeX. So our next example will use an advanced LME function, magic, which produces a magic square in a matrix. Matrices are displayed in mathematical notation.

Since matrices are too large to fit nicely in a paragraph, we put it in an equation:

Magic square $M_3$ of order 3 is
\begin{equation}
M_3 = \sqexpr{magic(3)}
\end{equation}

Programs

\sqexpr is very convenient for simple expressions. However, it is not suited to more complicated programs, for two reasons: first, only a single expression can be evaluated which gives a single result. Second, LME syntax may interfer with LaTeX syntax: the backslash, for instance, is a normal character used for premultiplying with the inverse of a matrix in LME, while it is an escape character in LaTeX. We can always escape special characters in LaTeX, but Sysquake for LaTeX's aim is to make things simpler, not overly complicated.

The answer to \sqexpr's limitations is the sysquake environment which can contain any kind of code. Let us write another magic square with it:

Magic square $M_4$ of order 4 is
\begin{equation}
M_4 =
\begin{sysquake}
magic(4)
\end{sysquake}
\end{equation}

The sysquake environment can contain any number of lines with any code, unescaped, like verbatim. The only invalid character sequence is \end{sysquake}, which marks the end of Sysquake code. If for an unlikely reason you have to write Sysquake code which contains this sequence of characters, add a space somewhere, or if it is in a string, write a character with an escape sequence, e.g. \end{sysquak\145}.

Code in sysquake environment does not have the restrictions of expressions written with \sqexpr. You can define variables, have conditional executions and loops, use libraries, and more.

Contrary to \sqexpr where a single result is formatted for LaTeX, the sysquake environment only inserts any text produced by the code it contains in the LaTeX source. This text is still processed by LaTeX. To format it, you can either do it yourself, inserting LaTeX commands, or use the Sysquake function sqlxvalue. In the code fragment above, magic(4) without semicolon writes the result as an assignment to variable ans, as raw text:

ans =
    16     2     3    13
     5    11    10     8
     9     7     6    12
     4    14    15     1

In a LaTeX equation, this does not look like a matrix. With sqlxvalue(magic(4)), we obtain

\ensuremath{\left[ \begin{array}{cccc}16
&2
&3
&13\\
5
&11
&10
&8\\
9
&7
&6
&12\\
4
&14
&15
&1\end{array}\right]}

which is rendered more nicely, like with \sqexpr.

Short code fragments, such as variable assignments, can be included with the \sqeval command. Note that its argument is processed by LaTeX, contrary to the contents of sysquake environment.

Graphics

Creating graphics for LaTeX documents is among the most cumbersome tasks an author is facing. Sysquake for LaTeX makes it as easy as in Sysquake itself.

Graphics are created by adding the size of the EPS image to be created after \begin{sysquake}. The result is inserted automatically in a picture environment of the same size. Package graphicx is used, as well as package epstopdf in PDFLaTeX; they should be imported explicitly with \usepackage:

\usepackage{graphicx}
\usepackage{epstopdf}

Here is an example of a function plot:

\begin{sysquake}(300,200)
a = 7.2;
fplot(@(x) (x+0.3)^2+a*exp(-3*x^2), [-2,3], 'r')
\end{sysquake}

In LaTeX, figures are usually floating. This is done with the figure environment:

\begin{figure}
\begin{center}
\begin{sysquake}(300,200)
a = 7.2;
fplot(@(x) (x+0.3)^2+a*exp(-3*x^2), [-2,3], 'r')
\end{sysquake}
\caption{Function plot}
\end{center}
\end{figure}

Functions and libraries

Code fragments may rely on the large set of built-in operators and functions as well as on additional functions stored in libraries. Libraries are text files with a .lml suffix which contain the source code of sets of related functions. You can use those which come with Sysquake for LaTeX or write develop new ones, which you can share with Sysquake.

To make functions defined in a library available to Sysquake, a use statement should be placed before any call, in a sysquake environment or a \sqeval command.

\begin{figure}
\begin{center}
\begin{sysquake}(300,200)
use polyhedra;
smallstellateddodecahedron;
colormap(blue2yellow2redcm);
plotoption nomargin;
plotoption noframe;
plotoption fill3d;
\end{sysquake}
\caption{Great dodecahedron}
\end{center}
\end{figure}