On the importance of syntax coloring for teaching statistics

Abstract

In this article, I underscore the importance of syntax coloring in teaching statistics. I also introduce the statax package, which includes JavaScript and LAT_EX programs for highlighting Stata code in HTML and LAT_EX documents. Furthermore, I provide examples showing how to implement this package for developing educational materials on the web or for a classroom handout.

1 Introduction

Syntax coloring, also called syntax highlighting, provides a visual aid for programmers by altering the appearance of lexical elements (color, font, font style, etc.) in the program. Syntax highlighting is merely secondary notation or a cognitive dimension (Green 1989; Green and Petre 1996) that provides perceptual cues for humans regarding the syntax and thus improves the readability of the code (Hendrix et al. 1998; Cross et al. 1999; Baecker and Marcus 1989). Consequently, it helps one to write syntactically correct programs (Myers, Pane, and Ko 2004) and improves program comprehension (Gilmore and Green 1988; Kankuzi and Ayalew 2008). However, the effect is smaller for experienced programmers (Sarkar 2015; Dimitri 2015), which underscores the importance of syntax highlighting for teaching beginners and developing educational materials.

With regard to educational materials, until now users could not highlight Stata syntax in different document formats such as HTML or LAT_EX. The statax package— which is not an ado-file and cannot be executed from Stata’s Command window—fills this gap by providing JavaScript and LAT_EX programs for highlighting the syntax of Stata code in HTML and LAT_EX documents, respectively. The package is hosted on https://github.com/haghish/statax and can be installed in Stata using the github ¹ (Haghish 2016a) command. The installation will copy the JavaScript and LAT_EX engines to the plus directory.

. github install haghish/statax

Alternatively, the package can be downloaded manually from GitHub; the JavaScript or LAT_EX program can then be linked to the document (see section 2). For HTML documents, you can also link the JavaScript library from the web without requiring a local installation. In this article, I will provide examples on how to use statax. However, you will find more complete examples in the GitHub repository of the package. ²

2 statax engines

2.1 LAT_EX engine

The LAT_EX engine is a single file named Statax.tex. You can include the file in the header of the LAT_EX document using \input{/path/to/Statax.tex}. Any Stata code placed within the statax environment will be highlighted after typesetting the document:

\begin{statax}

…

\end{statax}

JavaScript engine

Much of the tutorials are published on the web. Therefore, a syntax highlighter for HTML documents can be particularly important. To use syntax coloring in an HTML document, add a link to the Statax.js script to the document’s header.

<script src="/path/to/Statax.js"></script>

Alternatively, you can add Statax.js to the HTML document’s header without linking it locally. You can link the script by including the following code in the HTML header:

<script src="http://haghish.com/statax/Statax.js"></script>

Once the JavaScript is linked to the document, Stata code that is placed within the <pre class="sh_stata"> tag is highlighted:

<pre class="sh_stata">

…

</pre>

3 Customization

For altering the default coloring theme of statax, three additional color themes were developed: Sunset, Daring, and Wrangler. These additional themes specify the colors used for the code background, keywords (commands), functions, local and global macros, string characters, numbers, and operator signs. Users can edit one of the theme files to implement their own color theme or learn how to develop new color themes. In LAT_EX documents, the theme should be included in the LAT_EX header after including the Statax.tex file to redefine the default colors. For example, to use the Sunset theme, type

\input{/path/to/Statax.tex}

\input{/path/to/Sunset.tex}

Similarly, to customize statax in an HTML document, source a CSS file in the HTML document after calling the JavaScript engine to redefine the theme. For example, you can add the Sunset theme to an HTML document as follows:

<script src="http://haghish.com/statax/Statax.js"></script>

<link rel="stylesheet" type="text/css" href="http://haghish.com/statax/CSS/Sunset.css">

In the example above, the file Sunset.css is sourced from the web. If the CSS files are stored locally, you should specify the local address of the CSS file, for example, href="/path/to/Sunset.css". Programmers who wish to include the engines in their packages can get the path to the engines using the findfile command and include them in the header of the HTML or LAT_EX document.

4 Discussion

Several Stata packages that produce HTML or LAT_EX files can benefit from the statax syntax highlighter for developing appealing educational materials. For example, the JavaScript and the LAT_EX engines are already implemented in the weaver (Haghish 2016c) and markdoc (Haghish 2016b) packages for developing dynamic analysis documents. Because of its simple installation and customization, statax can be easily added to websites, HTML documents, or LAT_EX documents to facilitate beginners’ code comprehension and make educational materials more appealing for learners. The project is hosted on GitHub, and interested readers can submit additional themes to the repository or collaborate on updating the keyword lists of the programs.