Skip to main content

Section 4.15 Programs and Consoles

Subsection 4.15.1 Content and Placement of Programs and Consoles

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: <prompt>, <input>, and <output>. The <output> is optional, and a <prompt> is only displayed when there is an immediately subsequent <input> (which could be empty). The content is treated as verbatim text (see Section 3.16), subject to all the exceptions for exceptional characters (see Section 3.14).

A <program> or <console> may be wrapped in a <listing>, see Section 4.18. 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.

Subsection 4.15.2 Interactive Programs, CodeLens

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 31). 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.

Subsection 4.15.3 Interactive Programs, ActiveCode

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 31) where a Jobe Server 1  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.

Note that a Python ActiveCode automatically is enabled with a CodeLens button and requires no preparation of any trace data. So a reader can form any type of Python program and closely examine its behavior.

Subsection 4.15.4 Interactive Program Capabilities

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.

Table 4.15.1. Interactive Programs
Language @language Server
Generic Runestone
Python python AC + CL AC + CL
Python 3 python3 AC
Java java CL AC + CL
C c CL AC + CL
C++ cpp CL AC + CL
JavaScript javascript AC AC
HTML html AC AC
SQL sql AC AC
Octave octave AC
AC = ActiveCode, CL = CodeLens
github.com/trampgeek/jobe