Theorema Tutorial

Programmers Guidelines

System Development

Recommended Development Tools

Write packages in plain .m-files, no programming in .nb notebook-files. m-files can be edited as package files in the Mathematica FrontEnd, still providing some of the convenient notebook features (e.g. sectioning, collapsing cell groups, etc.).

As the preferred development environment, however, we recommend the Wolfram Workbench.

Running Theorema through the Workbench

Importing the project

The directory obtained from the git-repository is the base directory of a Workbench-project. You can import it into the workspace through the menu "File - Import ... - Existing Projects into Workspace" and then just follow the instructions. The project will be configured automatically, no settings need to be adjusted.

Deactivate auto workspace refresh in the workbench preferences

In the Workbench preferences - General - Workspace uncheck "Refresh automatically" (checked by default). Otherwise, in case you have Theorema notebooks in the workspace (e.g. as part of the documentation) the workbench will permanently refresh when Theorema creates new files in a notebooks's auxiliary directory e.g. during a computation, which in turn will always reload the Theorema system.

Running Theorema from within the Workbench

The best way to run Theorema from within the Workbench is to simply choose "Run ..." from the Run-menu. Theorema will load and a test notebook will appear, which you can ignore for most of the time. The Theorema commander starts and you can open any Theorema notebook or create a new one from there.

We do not recommend to open existing Theorema notebooks or to create new notebooks using the native Mathematica commands for opening and creating notebooks because this may lead to troubles with the stylesheets. For the same reason we do not recommend to launch Theorema using "Run As ..." or "Debug As ..." on an existing notebook.

Language Dependency

Language dependent strings (help messages, button labels, menu entries, etc.) should be defined in the corresponding "LanguageData" packages. Use the Theorema-function translate accordingly. It will use the language chosen in $TmaLanguage, which is set in the Preferences-activity in the Theorema commander.

For the Programmer

When you add a new entry in one of the "LanguageData" packages (typically in one of the "English.m"), then please

note that the entries are sorted and insert the new entries in the appropriate order

copy the line to all other language files present even if you cannot provide the proper translation (in which case you just leave it in the original language, e.g. English). Collect the untranslated stuff near the end of the file. There should be a block of already translated entries (sorted) near the beginning of the file and clearly seperated from that a block of still to be translated entries (unsorted) near the end of the file. Otherwise it will be tedious for a translator to find out, which translations are still missing.

For the Translator

Suppose you are able to translate language "A" (e.g. English) to language "B". When you provide translations for your language "B", then walk through all "LanguageData" directories and do the following:

If "B.m" does not yet exist, copy the package "A.m" to "B.m".

If a directory "A" exists but no directory "B", then create a directory "B" and copy the content of "A" into "B".

If a directory "B" already exists, then just make sure it contains the same files as "A".

Provide the missing translations in all language dependent files and move the translated entries from the unsorted block at the end of the file into the sorted block at the beginning of the file.

Programming

Naming Conventions

Function names: lower case, no special characters except $, upper case on word boundaries, e.g. openComputation.
Global variables: start with $.
Data structures: short names, all upper case, ending in $, e.g. VAR$.
Unevaluated fresh names (in order to avoid evaluation by Mathematica): upper case, ending in $TM, e.g. Plus$TM.

Spacing and Indentation

In general, opening brackets "[" and commas "," are followed by a blank. Rare exceptions allowed, e.g. f[1], Module[{x, y}, ...].

Multiline expressions indented as follows:

multiline[
    body1,
    body2
]

If several brackets or braces appear in a row, we prefer

multiline[{
    body1,
    body2
}]

over

multiline[
    {
        body1,
        body2
    }
]

Package Dependencies

Usually, if package A depends on package B, package A is set up using

so that symbols exported by B are visible in A. In order to keep the ContextPath "clean", we use so-called "private package import"

which also makes symbols exported by B visible in A, but will not leave "B`" in the ContextPath after loading package A.
Moreover, we use one central package Theorema`Common` for shared symbols. All symbols that need to be used across packages should be defined there, and all packages that need symbols from other packages just use

This gives a flat package hierarchy that can easily be maintained.

Default Case for Pattern Definitions

For functions that are defined through various patterns, provide a default case that will match if all (intended) cases fail.

This will interrupt program execution and tell that 'f' has been called with unexpected arguments 'args'. This will facilitate debugging.

Use Assert

Assert is a new feature in Mathematica 8, which allows to test assumptions that interrupt program execution in case it is detected that the test fails.

Organization

Theorema editor

Every file names a Theorema editor (TE) in the file's header. The TE is the person through which modifications to that file can go into the common repository. Technically, this means that changes to a file, which is not edited by yourself, should be made in a separate branch in the revision control system, from which the TE can pull the changes and forward them into the common repository.