The PreTeXt Guide

A <program> will be treated as verbatim text (see Section 3.16), subject to all the exceptions for exceptional characters (see Section 3.14). Indentation will be preserved, though an equal amount of leading whitespace will be stripped from every line, so as to keep the code shifted left as far as possible. So you can indent your code consistently along with your XML indentation. For this reason it is best to indent with spaces, and not tabs. A mix will almost surely end badly, and in some programming languages tabs are discouraged (e.g. Python).

A <console> is a transcript of an interactive session in a terminal or console at a command-line. It is a sequence of the following elements, in this order, possibly repeated many times as a group: <input>, and <output>. The <output> is optional. The content of these two elements is treated as verbatim text (see Section 3.16), subject to all the exceptions for exceptional characters (see Section 3.14). A @prompt attribute on the <input> can be supplied to provide a system prompt distinct from the actual commands. The default prompt is a dollar sign followed by a space. If it is more convenient @prompt may be supplied on the <console>, to be used in each enclosed <input>. If you do not want any prompts at all, just use an empty value for @prompt.

A <program> or <console> may be wrapped in a <listing>, see Section 4.19. This will behave similar to a <figure>, with the <caption> displayed below, and a number assigned. So, in particular, if your program or console is important enough to cross-reference, it is an enclosing <listing> that serves as the target.

The @language attribute may be used to get some degree of language-specific syntax highlighting and/or interactive behavior. We will eventually provide a table of attribute values here. They are always lowercase, and a good first guess is likely to succeed.

In some output formats, notably HTML, the syntax highlighter can add lines or highlight individual lines of code. Highlighting lines is not supported for LaTeX output. To display line numbers, set the @line-numbers attribute to yes. To highlight particular lines, set @highlight-lines to a comma-separated list consisting of individual lines and/or ranges indicated with dashes. Some examples are: 5, 2,5, 2,5-8,10-15,15.

For interactive versions hosted on Runestone servers, the @label attribute is critical, just like for interactive exercises. So be certain to read Best Practice 4.12.1.

CodeLens is an interactive version of a computer program, which can be visualized by stepping through the code one statement at a time, watching output, variables, and other data structures change. So it is similar to a debugger, except the reader does not set breakpoints or modify program data on-the-fly. This is possible automatically for several different languages when your HTML is hosted on a Runestone server (Chapter 32). This may also be accomplished “in browser” when hosted on any old generic web server. The catch is that for a generic server a publisher must generate trace data in advance, typically with the PreTeXt-CLI (Section 5.2). Place the <interactive> attribute on a <program> element with the value codelens to elect this behavior (no is the default value). Also, be sure to specify a language from the supported languages: Python, Java, C, and C++. Consult Table 4.15.1 below for a summary of various combinations. When an output format does not support an interactive CodeLens instance, the fallback is a static program listing.

ActiveCode is an interactive environment where a reader may work on code through repeated edit-compile-test cycles. Code can be provided by an author as a complete program to be modified, a partial program to be completed, or nothing at all. One good example is that maybe header files, import statement, and similar are provided, and a skeleton of a main entry-point procedure is also provided. Then a reader can concentrate on the more conceptual parts of the programming. Some languages will be executable “in browser” on any old generic web server, while others must be on a Runestone server (Chapter 32) where a Jobe Server

¹

github.com/trampgeek/jobe

is running to support the execution.

Place the @interactive attribute on a <program> element with the value activecode to elect this behavior (no is the default value). Also, be sure to specify a language from the supported languages. Consult Table 4.15.1 below for a summary of various combinations. When an output format does not support an interactive ActiveCode instance, the fallback is a static program listing.

For languages that support CodeLens, a button will be created that allows the reader to step through the program. For some programs, especially ones using libraries like turtle graphics or image, CodeLens will not function. To prevent showing the CodeLens button on programs for it will not work, authors can set the @codelens attribute to no.

Note also that a data file may be provided independently for consumption by an ActiveCode program. See Section 4.16.

ActiveCode elements that are language sql can make use of an SQLite database file. This is different than a datafile (which is expected to be text or an image). To include a database file, use the @database on the <program> element and specify the file to load as a string relative to the @@external top-level directory

The <program> element can have two attributes, @compiler-args and @linker-args, which are strings passed verbatim to the compiler and linker (respectively). This is only relevant for programs running on a Runestone server (rather than in a browser).

If you want to include code from one or more preceding <program> elements, use the @include attribute whose value is a list (comma-separated or space-separated) of @xml:ids for the code you want included.

This table lists which types of interactivity are available on various combinations of servers and programming languages. The entry “AC + CL” means that both ActiveCode and CodeLens instances are availble, but the ActiveCode instance will have a CodeLens button enabled.

Note that python is generic Python with the standard libraries (version 3.x). On the other hand python3 is a Runestone server installation (only) with a number of additional popular Python packages available, such as numpy and pandas.