A list is composed of either normal lines or markup tag lines. Normal lines are the “substance” of the resulting output list; the notes, tasks, or details that are written in natural language. These lines are ignored by the parser and simply passed-through to the output. Markup tag lines represent the functionality and customization of the software. These lines are used by the parser and are never included in the output.
Normal lines can be arranged in a hierarchical fashion using indentation. Each level of indentation is 2 spaces. A line cannot have an odd number of indentation spaces. Within a single line, the indent level can only be increased by 1, but may be decreased as much as desired.
Blank lines are permitted, but will be ignored during list generation and won't appear in the checklist output.
Any line that begins with # will be ignored by the parser, and will not appear in the final generated output. Comment lines are useful for annotating a list for the author or editors.
A Variable is defined by a Prompt or Assignment, and referenced by a Branch, Assignment, or Text Substitution. Each variable must have a unique name. A variable name may contain only alphabetic characters, numbers, and an underscore character (_), and cannot start with a number.
In a markup tag line, there are no rules regarding spacing. The line must begin with its corresponding special character, but otherwise spaces may be present or not present between elements in the line. This includes variable assignment lines.
Opening and closing brackets are used to mark the starting and ending of specific sections. Because indentation is important, the brackets must be on their own line and with the correct spacing (as opposed to languages like C/C++ that are more permissive with brackets).
[ Square brackets ] are only used to contain lines that will appear to the user as a prompt; none of the lines contained within these brackets will appear in the generated checklist.
{ Curly brackets } only contain lines that will appear in the final generated checklist.
An individual line can not be longer than 80 characters wide, or it will be truncated with .. added to the end. If a long description is necessary, it is recommended to create a header line, and then add as many lines (with 2 spaces indentation) below it as necessary. In that case, however, they would be treated as individual checklist items in the final output.
When a variable appears in a list, it is either being:
In order to make lists easy to write, there is no requirement for a variable to be “globally” defined for all lists. In order for a user to generate a list as easily as possible, they should only have to answer a prompt when it is necessary. To put it another way, they should only have to answer prompts that are relevant to the current path they have taken through the lists.
The flexibility of the language allows for many different possible paths in collection of linked lists, or routine. This also introduces the potential problem of ending up trying to reference a variable that isn't defined in the current path (it is only defined in some other alternate path).
This problem is addressed by the error checking that happens when a checklist output starts, but before the user is prompted with any questions/decisions. In this checking operation, when a variable reference is encountered, the parser works backward through the current path to make sure that a definition can be found somewhere along the way. Variables do not have to be defined for all possible paths--only for the paths where they are used. Since paths are defined by conditional branching based on variables, there can be “identical” paths in many different places in lists. As long as it is not possible for the user to have traveled down a path where a particular variable is referenced but then another where it hasn't been defined, then the parsing will work. If any possible case is found where this is not true, then an error will be displayed to the user, with a description of the problem and how to potentially fix it.
The nature of multiple conditional branches combined with multiple different lists linking to each other make the language powerful and customizable, but also allows the author of lists to create a confusing situation where the variable reference problem exists. The authoring tools in the editor provide ways to solve a variable ordering problem if one occurs.