¶ Common Syntax Errors
An error check can be requested any time, and will be automatically performed when a checklist is generated. If there is a problem in the list, it will be described in a detailed error message in the bottom pane of the editor page. These messages were written with the objective of describing each possible problem in detail. This page was created to help in understanding some of the common problems that can arise, and to provide suggestions.
¶ Indentation
The 2-space indent rule might cause some confusion. When normal text is indented by 2 spaces, it means that the line above it is a header line. Any content in a bracketed case has an indent that increases by 2 spaces. A line may have at most 2 additional spaces of indentation than the line before it. A line may have any number fewer spaces of indentation (as long as it is at least 2 spaces greater than the brackets that enclose it). In the generated checklist, the contents of the bracketed case are automatically unindented to match the indentation of the brackets (which themselves will not be visible).
¶ Brackets
Brackets signify the beginning and ending of markup tag cases such as prompts, branches, and list link headers. There must always be a closing bracket for each opening bracket at the same indentation level. Some markup tags require one or more middle brackets (e.g. a select branch). Square [ brackets ] are used for prompts that will be displayed to the user during generation. Curly { brackets } contain list lines that may be used in the generated checklist, depending on the variable.
In the case of a select prompt, there must be proper ] [ lines to divide the options. When a select variable is used in a branch, the number of cases must match that of the prompt, and be separated by } { lines at the proper indentation.
¶ Markup Tag Header Line Problems
In a markup tag header line, the spacing is permissive, but certain elements must always be present. If the line does not start with the correct symbol, it will be treated as a normal line, even though the rest of it may be correct. There must always be opening and closing parentheses, with the proper keyword contained. The final part of the line must either be a valid variable of a list path (in the link case). When a number prompt is used, there must be min:max values provided in a proper range.
¶ Text Reference
A variable can be referenced in a string using the $ operator. A valid variable must be given after the operator, and at least one space must come after that variable and before any other text that comes afterward. Using $$ will create a single dollar sign in the output.
¶ List Links
A proper path must be provided at the end of the list links markup tag header line. This path starts at the user home directory, and includes every folder leading from there to the linked list, each folder separated by a / character. An error will occur if any part of the path is incorrect. In addition, a list cannot link to itself.
¶ Variable Referencing Errors
It is possible to have an “out-of-order” situation where in the current path, there is a reference for a variable that was defined in a path not taken. Such an error message will look like the following:
Failed to guarantee that question variable reference 'variable_name' at line 15 of folder/list_name will be defined in all possible user input cases
and will be followed by at least one line that describes where a potential definition was found (or if none were found). This section discusses ways to fix problems of this type. For more information on variable ordering, read this section.
¶ Base Level Definitions
The base conditional level can be thought of as the “trunk” of a tree before any branches (conditionals) extend from it. Any variable definition that is at the base conditional level will never have a problem with out-of-order referencing. Problems can occur when a variable definition only exists inside of one or more conditional branches. It might sound like the solution is to only define variables at the base/trunk level, but there is a reason not to do this. One of the design philosophies of the language is to ask a user as few questions as possible when generating a checklist. It is not acceptable to ask the user which car they are going to drive on a trip when they already selected the option to travel by train. Variable definition prompts that are inside of other conditional branches make for a smoother, more natural checklist generation process. This is because the user is only prompted for details that relate to the previous decisions they have made. But this can also create the potential out-of-order problems that are discussed in more detail below.
¶ Definitions not Sharing Similar Branches
It is common for a particular variable's definition and reference to exist on separate branches. As long as the reference branch(es) contains all of the same conditional variable values as the definition branch(es), then there will be no out-of-order error. For example, if the true branch of useWrench is where toolQuantity is defined with a prompt, then later-on in another linked list, toolQuantity can be used in a text reference as long as that takes places in a branch where useWrench is true.
Figure 1 shows a diagram of a list as it flows from top to bottom. A line of normal text is represented by a circle. Orange diamonds represent conditional branches where one path is taken based on its variable value. A ? prompt is where the user provides that value. In this figure, the bottom reference of variable C is valid only because it exists in the false case of B, which is the same (but separate) case where C is defined by the green prompt.
¶ Definitions That Don't Cover All Branches
A variable reference does not need to be in the same branch where it was defined if all possible previous branches had a definition. Consider an alternative scenario with the above example, where the true branch of useWrench has a prompt for toolQuantity, and the false branch has another set definition for toolQuantity. In that case, the variable toolQuantity could be referenced anywhere in the list, because it has a definition regardless of which value the user might pick (all branch path possibilities are covered) for the variable useWrench.
In Figure 2, the branch reference for B at the bottom will cause an error, because it is possible the user selects A = 3, which results in a pth without a definition for B.
¶ Predefined Definitions
Assignments can be used to fix variable values so that there is no uncertainty with regard to what a user might pick. In the first example above, if there were an assignment that set useWrench to true (with or without a prompt for it), then toolQuantity could be referenced anywhere in the list because it would be impossible for it to be undefined.
¶ Reset for a Re-Prompt
The language is designed to not prompt a user if they've already provided an answer for that variable. If necessary, however, the list author can force a re-prompt by using a reset. There are some advantages to doing this, but it can also cause a variable ordering problem in certain situations. The presence of this reset prompt can interfere with the initial definition if it takes place inside a conditional branch(es). In such a case, even though definition and reference are on the same branch(es), the path might have been changed by the user at the reset prompt. Such a case can also happen with a variable assignment occurring between definition and reference.
In Figure 3, the bottom branch reference for C will cause an error, because if B = true was selected in the first B prompt, but false in the second reset prompt, then C would have never been defined.
¶ Using Authoring Tools for Troubleshooting
¶ List all of the Definitions and References for a Variable
If there is an out-of-order problem with a specific variable, select it in the Details of variable drop-down menu, and then click All Locations. Every definition and reference will be listed with its list name and line number location, as in the example below:
It is also possible to see the defs/refs shown inside a summary of all the list links, as shown below. Here, the hierarchy of list links from the main to each list containing the def/ref is shown. The . . . abbreviation signifies the presence of other linked lists that aren't shown because they do not contain the variable in question.
¶ List all of the Variable Definitions and References Within the Conditional Branches
Showing a variable's definitions and references in a flowchart view is perhaps the most useful tool for troubleshooting an out-of-order variable problem. Here, the full chain of branches from the trunk to the def/ref are shown:
¶ Text Search in All List Files
The Search All button is useful for understanding all the places where a variable exists, including wording in a normal list line that might help with a search, but would not appear in one of the tools discussed above. The case-sensitive, word-only, and folder limit features can be used to refine the search results.
¶ Text Substitution
The most basic form of software debugging is probably to print variable values as a program runs. It is possible to replicate that kind of troubleshooting with the text substitution feature, which can display a variable value at any location. This is not a preferred method of troubleshooting, but there might be situations where it is helpful.
¶ Stuck? Here's a Backup Plan
If a difficult out-of-order variable problem is encountered, and troubleshooting methods are getting too confusing, then a fallback plan is available. You can always add a user prompt or assignment prior to the variable reference that is giving you the out-of-order error. This might lead to other unwanted user prompts in multiple locations, or a less-streamlined list, but it will solve the problem.