The end product of this software a checklist that contains a specific, tailored sequence of steps. In order to generate such a checklist, one or more source lists are used. Each of these lists can be thought of as a template. A list is written in the clir markup language, which at its core is simply readable text. Customization is added by using markup tags which are distinguished by the line starting with a special character, without which the line is treated as plain text to be included in the final result.
The work of interpreting the source lists and generating the output checklist is done by the Parser, which is discussed later in this page.
The philosophy of the clir language is to keep a list simple and readable. Customization is enabled by the programming-like features of markup tags. Since only a few of these tags are used, they are easy to remember. A graphical editor uses visual aids and help tips to clearly show where these tags begin and end. Markup tags are not seen in the generated output since they are only used to guide the parsing through the different options. If something is wrong with the way a markup tag is written, the problem will be communicated with a clear error message.
The language allows for a conditional branch to be in a list, like a fork in a road. With a lot of branches, the generated list will contain many different possible paths. A graphical representation (e.g. flowchart) is good for simple conditional branches, but quickly becomes too cluttered as more are added. Since lists are written in plain text, the language's philosophy is to provide the conditionals in that format. Graphical representations can be created in the editor to show the structure of the list as it is written, which is the opposite of other software approaches where a list is created in graphical form.
Aside from the markup tags, the basic formatting rule of a list is that each line must have a proper indentation. Each line has an indent level, where each indent level contains 2 spaces. No tab characters are allowed (pressing tab in the editor will insert 2 spaces instead). The parser treats an indented line as a child of the lesser-indented line above (whether that is one or many lines above it). In this way, a list can have a header line which “contains” a number of lines below it. Header lines can be used to group steps logically. In the checklist form, headers can be used to expand or collapse their child lines. Headers themselves cannot be marked as completed; they automatically become completed when all of their child lines are completed.
There is no limit on the number of indent levels, but the level can only increase by one with each line. In other words, a line cannot have more than 2 additional spaces of indent than the line before it. Decreasing a line's indent by 2 spaces less than the line before it will close the case above. There is no limit to the number of spaces of indent that a line can decrease by, since multiple cases above that line are allowed to be closed in that way.
Markup tags of the language exist in the following categories:
Conditional branches make it possible to include or ignore items based on a particular condition or value. This can range from including a few items to following a completely different path of many items.
Branches typically have the following components:
Other lists can be merged into the current list by linking to them. This merging occurs when a checklist is generated, and can be done in a seamless manner, or with a descriptive header on a line above the linked content.
Linking provides many advantages. Lists are easier to read when things are grouped with links. A descriptive link name or header name shows the related steps that the linked content represents. A list can be re-used by linking to it rather than re-writing the same steps in multiple places in the list(s). In addition to avoiding repetition, links allow the author to change the content in only one place but have it be reflected in multiple linked places. A list can be linked-to any number of times, or it can be restricted so that it is only linked once to avoid duplication.
Variable values can be set or modified using assignment expressions, which support simple math and logical operations. Assignments can also be used to simply set a text string (e.g. a label name to be inserted in the list). Expressions make the language more powerful and flexible, but their use is not required.
A parsing session is started at the time when the user wants to generate a checklist. Such a session starts from a single selected list (the “main” list). A user's home directory can contain many different lists, any one of which may be selected as main.
Before prompting a user, the parser checks through all possible paths and links, looking for any errors in the way they are written. This can be thought of as a syntax check. It also looks for problems with in the order in which variables are defined and then referenced. If any problems are found, the user is presented with a helpful, descriptive error message to help solve the problem.
The parser follows this list from the top down, and presents a prompt to the user when one is encountered. If a branch is encountered, it may fork into two or more possible paths. The parser follows the path chosen by the user's prompt response. The new selected path may lead to another branch or list link, which is a “jump” into another list that is then followed from the top, and so on…
In this documentation, only the web interface is discussed. The web interface is the easiest way to use the software, but it is worth mentioning that the clir parser is written in C++, and is a command line application at its core. Everything discussed here is a web interface front-end for what are essentially command line operations.