Compiling Documentation and Presentations: LaTeX

If you are not in the academic world, then you might wonder about that ‘LaTeX‘ in the title.  and no, it is not about that latex rubber material ;-), it is about ‘la-tek’ 🙂

In short, it is a programming language and tool set to ‘compile’ documents. Originally, TeX has been designed and mostly written by Donald Knuth and released in 1978. Since then, it has been evolved and TeX (or LaTeX) is widely used in academia.

Compiling Source to create Documents

If you are an engineer and you like compiling source code, then you probably will love LaTeX, because it means compiling source code to generate documentation :-).

The advantage of LaTeX in my view are:

  1. LaTeX cares about all the typesetting (footer, header, title page, formatting, numbering figures, creating a bibliography, index, table of content, glossary and more. So I can concentrate on the content.
  2. It is text source code. This makes it very easy to track, collaborate and have multiple people editing the same source code with a version control system. No need to deal with ‘binary’ word documents.
  3. Because it is text, and because it is possible to use macros, conditional compilation, using different source files and because the content (the text) and the form (how it is put into fonts/pages/etc) is separated, it is possible to create different output from the same material (books, articles, presentations, …).

But as with any new thing: it takes time to learn it. The good thing is that there are tons of tutorials on the internet, and for any question I had I have found an answer in the internet with the help of Google :-).

With LaTeX, I write source code to typeset my documents. For example, this is a LaTeX example source:

\documentclass{article}

\begin{document}

\title{Article Title}
\author{Author}
\date{\today}
\maketitle

\begin{abstract}
This is a dummy abstract text.
\end{abstract}

\section{Introduction}
This is just a dummy introduction text.

\section{Document Class Options}
The typesetting specification selected by this document template
uses the default class options. There are a number of class options
supported by this document class. The available options include
setting the paper size, the point size of the font used in the
document body and others.

\subsection{Customizing Class Options}
Select `Insert', `Document Properties ...', the `Generic' tab
and then modify desired class options in appeared dialog.
Changes will be applied after pressing the 'OK' button.

%+Bibliography
\begin{thebibliography}{99}
\bibitem{Label1} ...
\bibitem{Label2} ...
\end{thebibliography}
%-Bibliography

\end{document}

Compiling it with the LaTeX compiler gives a PDF with:

LaTeX Example Output

LaTeX Example Output

I’m using doxygen in my sources to create documentation from my C/C++ source code, and do doxygen can create LaTeX source code.

And best thing: LaTeX: it is free and Open Source :-).

IDE’s for LaTeX

As with programming languages, all what you need is a text editor and the compiler ;-). But as with any programming languages, there are plenty of IDE’s and tools to make things easier.

TeXnicCenter

I’m using the TeXnicCenter for years, an I’m very happy with it: it is simple, small and fast.

TeXnicCenter IDE

TeXnicCenter IDE

Eclipse and LaTeX: TeXlipse

Eclipse as my favorite framework and IDE of course has a LaTeX plugin available too 🙂 I’m using TeXlipse (http://texlipse.sourceforge.net/). It comes with wizard and nicely integrated in Eclipse. For example I’m using it as plugin in Eclipse based CodeWarrior for MCU10.5:

LaTeX in CodeWarrior for MCU10.5

LaTeX in CodeWarrior for MCU10.5

WYSIWYG and LaTeX

One thing many first time users do not like with the LaTeX way of doing things: you need to compile the code to see the result. So LaTeX is not WYSIWYG (What-You-See-Is-What-You-Get). BaKoMa is an IDE which has ‘real-time’ rendering of the LaTeX files, so you can edit the LaTeX code, and it gets automatically compiled, or you can directly edit in the generated output, and it updates the LaTeX code 🙂 :

BaKoMa WYSIWYG with LaTeX

BaKoMa WYSIWYG with LaTeX

❗ Unlike LaTeX or LaTeX tools I know, BaKoMa is *not* free. But pricing is very reasonable (below 100 Euros).

LaTeX Features

Next, a few examples of what LaTeX can do….

Formulas

Where LaTeX is unbeatable in my view is how it is able to deal with mathematical formulas.

For example

$\frac{n!}{k!(n-k)!} = \binom{n}{k}$

creates

\frac{n!}{k!(n-k)!} = \binom{n}{k}

Or:

\begin{equation}
m = \frac{m_0}{\sqrt{1-\frac{v^2}{c^2}}}
\end{equation}

creates:

LaTexX Example Equation

LaTexX Example Equation

💡 No worries about the syntax: it is easy-going after a learning phase. The $ starts the ‘mathematical mode’, and e.g. \frac{} starts a fraction and so on.

💡 WordPress supports LaTeX too, see http://en.support.wordpress.com/latex/

Figures

Inserting pictures and figures is simple. The default way is to use

\begin{figure}...\end{figure}

The following source

Figure \ref{fig:ZumoBasePCBWithSensors} shows the base PCB with sensors and to communication modules connected.

\begin{figure}[ht]
  \centering
  \includegraphics[width=0.6\textwidth]{ZumoWithModulesMounted.png}
  \caption{Sensor and RF Modules mounted}
  \label{fig:ZumoBasePCBWithSensors}
\end{figure}

gives:

LaTeX Example Figure

LaTeX Example Figure

Drawings

Instead using images/bitmaps, I can draw graphs directly in LaTeX. There are many packages (plugins for LaTeX) available, my favorite is TikZ. With this, drawing a flow diagram is easy:

\begin{figure}[ht]
\begin{center}
\begin{tikzpicture}[node distance = 2cm, auto]
  %place nodes
  \node [block] (start) {start};
  \node [block, below of=start] (flag) {check flag};
  \node [decision, below of=flag] (decide) {ready?};
  \node [block, below of=decide, node distance=3cm] (read) {read};
  % Draw edges
  \path [line] (start) -- (flag);
  \path [line] (flag) -- (decide);
  \path [line] (decide) -- node {yes}(read);
  \path [line] (decide) -- +(3,0) -- +(3,3) -- node {no} (flag);
  %label
\end{tikzpicture}
\caption{Gadfly Loop}
\label{fig:GadflyLoop}
\end{center}
\end{figure}

gives:

LaTeX Example Flow Diagram

LaTeX Example Flow Diagram

Source Code

Source code can be included into the document from a file with

\lstinputlisting{./src/example.c}

or directly placed in the document with:

\begin{lstlisting}
static portTASK_FUNCTION(T3, pvParameters) { /* priority 3 task */
  portTickType xLastTime = xTaskGetTickCount();
  for(;;) { /* task time is 5 ms including overhead */
    DoWorkFor5ms(); /* this needs 5 ms */
    vTaskDelayUntil(&xLastTime, 25/portTICK_RATE_MS);
  } /* loop forever */
}
\end{lstlisting}

This gives (notice the automatic keyword highlighting :-):

LaTeX Example Listing Output

LaTeX Example Listing Output

Teacher Corner: Exams

Students usually do not love exams, and as for myself: writing exams is no fun neither (not to talk about correcting them). But the good thing is that there is an excellent exam class (plugin) for LaTeX which makes writing tests and exams easier.

LaTeX creates tables with the points keeps track of the counting. A question could be written like this:

\question
  \begin{parts}
    \part[2] Determine for the 8bit (binary reflected) Gray code \textbf{0x47}$_{g}$  the corresponding 8bit Binary code$_{b}$:
      \answerline[122/0x7A$_{b}$]
      \begin{solutionordottedlines}[0cm]
        Gray to Binary:\\
        0x47$_{g}$, then use MSB, then add each next bit (ignore carry): \\
        0100'0111 $\rightarrow$ 0111'1010 $\rightarrow$ 0x7A$_{b}$
      \end{solutionordottedlines}

    \part[2] Determine for the 8bit (binary reflected) Gray code \textbf{0x74}$_{g}$ Code the corresponding 8bit Binary code$_{b}$:
      \answerline[88/0x58]
      \begin{solutionordottedlines}[0cm]
        Gray to Binary:\\
        0x74$_{g}$, then use MSB, then add each next bit (ignore carry): \\
        0011'0100 $\rightarrow$ 0101'1000 $\rightarrow$ 0x58$_{b}$
      \end{solutionordottedlines}
  \end{parts}
\droptotalpoints

This gives:

LaTeX Exam Example Questions

LaTeX Exam Example Questions

But the coolest thing is: with an option it creates a version with the solution :-):

LaTeX Exam Question with Solution

LaTeX Exam Question with Solution

Multiple choice question example:

\question[1]
Given the pseudo code for a closed loop control system:
\begin{lstlisting}
esum += e;
s = a*e + b*Ta*esum;
\end{lstlisting}
This software controller implements a
\multipleChoice
\begin{checkboxes}
  \choice PD controller
  \choice ID controller
  \CorrectChoice PI controller
  \choice P Controller
  \choice PID Controller
\end{checkboxes}

gives:

LaTeX Exam Multiple Choice

LaTeX Exam Multiple Choice

with the solution:

LaTeX Exam Multiple Choice Solution

LaTeX Exam Multiple Choice Solution

Presentations: Beamer

The ‘Beamer’ class/plugin is an easy way to create a professionally looking presentation.

\begin{frame}
  \title{INTRO Zumo Robot}
  \begin{figure}[ht]
    \centering
    \includegraphics[width=0.4\textwidth]{Intro_Zumo_Robot.png}
  \end{figure}
  \titlepage
\end{frame}

Is the first slide of the deck created for the Zumo Robot Schematic Presentation (see Zumo Robot assembled).

LaTeX Beamer Intro Zumo Presentation

LaTeX Beamer Intro Zumo Presentation

💡 It is even possible to combine an article text with the presentation slides, using the beamerarticle package.

Summary

Of course this is not a LaTeX tutorial or comprehensive list of all features. Yes, it takes some upfront time to learn it, but it is very rewarding. I hope you have now a taste of why I’m a big fan of LaTeX: it makes my documentation work easier, faster and more productive.

💡 Yes, I’m still using Microsoft Word and PowerPointer. They is great for ‘write and forget’ kind of documentation, or if things needs to be ‘quick and dirty’. But for documents which need to maintained over a long time, or documents which needs to be more sophisticated, I’m using LaTeX :mrgreen:

Happy LaTeXing 🙂

9 thoughts on “Compiling Documentation and Presentations: LaTeX

  1. One more interesting thing worh to mention here is Inkscape. If one does not really like to code graphics using TikZ – which can be very painful if you have a complicated graph – it is possible to use Inkscape with the TexText Extension. Just make your drawing, and using the TexText command from the menu, it is possible to insert Text with the correct LaTeX formatting, even using math mode and so on is no problem. This way you can use a WYSIWYG style editor to make your graphs, but use LaTeX to insert annotations and stuff, which ensures consistency in your document. And of course these are vector graphics which avoids the ugly artifacts when pixel graphics are used.

    Like

    • Hi tobias,
      I had looked and used Inkscape a while back for LaTeX, but it was not really useful for me. Yes, it is useful to draw vector graphics, but what I need is the graphic commands (and not the .eps bitmaps from it). Maybe I have not used it correctly, but I was not able to have it generating the TikZ commands (that’s what I would need). Are you saying that it generates the graphical drawing instructions for you, and you are not using binary/image data with Inkscape and LaTeX? If so, then this would be interesting for sure :-).

      Like

      • Yup, there is some command like export to TiikZ if one wants to use that. However, I would recommend to save the graphic as PDF and then use \includegraphics{} which works very well with PDFs. Why not use the binary image files?

        Like

        • The beauty of LaTeX is that it is text based. Including PDF’s is ok if things are only available in PDF form (e.g. vendor data sheets, etc). But I do not like the additional step of going to export things from Inkscape to PDF: If I need to change the PDF, I need to open Inkscape, change it and expert it again: I rather would like that Inkscape would use TikZ as input/language, so I do not need to workaround it with PDF. But this is maybe just me.

          Like

  2. Just for the record: there is free alternative to BaKoma – LyX. This one is also WYSWIM editor, however is not “real-time”, output document has to be rendered every time.

    Like

    • Thanks for the tip, I should check out LyX then. I have stopped using BaKoma as I have run into too many limitations and problems, and reverted back using the traditional way with TeXnicCenter.

      Like

      • LyX is not perfect for sure, it has some limitations, and if you are already familiar wth LaTeX, using LyX (or any other WYSWIM editor) might be kind of step back. I consider this tool as a way to show peope: “hey, there is a way to use LaTeX like Word, but without pain!”

        Like

What do you think?

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.