Keyword documentation for TONTO

This chapter describes the current set of keywords used in TONTO.

You must have read the chapter called Using TONTO to do calculations> in order to understand the documentation.

Even though the online documentation is primarily for programmers, there is a short introduction on how to use the online documentation to find keywords and what needs to be entered after those keywords.

For those that prefer a book, the keyword documentation for every module is given. It is comprised of a short synopsis, and then a listing of all valid keyword tokens, a description of the type of data which are required to follow the keyword (if any), as well as explanatory notes and special conditions applying to that keyword.

Not all modules in TONTO have keywords input: only modules which are more complex than a TEXTFILE can have keywords, since a module that uses keywords must use the TEXTFILE module.

The online documentation

The online documentation is intended mainly for programmers, but it can be easily used to find keywords and to find what should be entered after a keyword.

The online documentation is compirised of two parts: the short documentation, and the long documentation. You will need to understand what you are looking at in these two parts before you can find the keywords and what they require as input.

If you have not already made the documentation, refer to the Section called Making the TONTO html documentation in the chapter called Compiling and Installing TONTO>.

The short documentation

The short documentation for a module is obtained by clicking your mouse on the module name in the left frame bar of the TONTO homepage, or the left frame bar when you open the file documentation/index.html.

It consists of

  • a "Synopsis" describing what kind of object the module is intended for

  • a list of the "Used modules" which are required by the module

  • a list (in green) of the "type components" used to store information for this type (if it is not an array or a simple data type). There is an explanation of what each type component represents, and and what type of data is held in the component, following the double colon ::

  • a list of any explicitly constructed "generic interfaces" and the module procedures which make up these generic interface names; this section is not present in many modules

  • a list (in red) of the "procedures components" which comprise the code components of the module, and the arguments that these routines take, together with an explanation of what the procedure does.

You can click your browser on any underlined item to obtain more detailed information---usually, the actual code in the long documentation---for that item.

The long documentation

The long documentation is comprised essentially of the foo code for the module.

Again, you will see green "type components" or red "procedure components" in this code. You can click on these to find out exactly what they are.

Finding keywords in TONTO online

According to the design of TONTO, every module which accepts keywords must have a process_input(word) routine. This will appear in red.

You can get an up-to-date list of keywords used in TONTO by looking in the process_input routine in the long html documentation, as explained below.

As well as being convenient, this is particularly useful when there are undocumented keywords, or keywords which have been incorrectly documented (sorry).

The procedure for finding keyword documentation is as follows:

  • Decide which module the keyword resides. This will invariably be the MOL module.

  • Click on the documentation for that module in framebar on the left.

    For the MOL module, you may have to click on the mol_main module which contains the read routine.

    Do not click the foo part of the module name: that will give you the raw foo code.

  • Find the process_input routine within the short html documentation in the main documentation windo on the right. Click on it.

  • You will now be within the code of a routine. Scroll down until you can see a case statement. Following this case statement there will be many strings involving data keywords such as name= or task keywords like scf. These are the allowed keywords.

  • To see what kind of data might be accepted by this keyword, look to the corresponding code to the right of the case option.

  • In the simple case, a variable may be inputted directly from that line, like this:

       case("name=");   stdin.read(.name)
    which means the variable .name (usually in green) is to be inputted from the input file, stdin. Click on the variable .name to see what data type it is (e.g. a string, STR, or a double precision number, REAL). Since in this case .name is a STR, you know that following the name= keyword you must enter a STR.

  • In the more usual case, a routine may be called, like this:

       case("name=");   .read_name
    where the routine .read_name is in red. Click on this routine to get to the short documentation. Click again to see the code associated with the routine. In this code, which will invariably very short, you may see exactly what is being inputted. For example, there may be a line like this:
       case("name=");   stdin.read(.name)
    exactly as in the case above.

    If a STR variable in being read in, and if there are only a few allowed options for this string variable, there should be a case statement telling you what options are allowed.

    If you do not see a stdin.read(...) line within your routine, keep reading.

  • Sometimes, a read routine, for example the read_name above, may call other read routines to input data. An example might be

       .shell.read
    where .shell is in green and .read is in red. There may be a sequence of these routines. This is particularly true of derived data input. In this case, follow each .read-like routine by clicking on it. Eventually, you will come to code in which simple data such as strings or numbers are inputted. The order that you should enter these data, is the sequential order that you click on the routines, from top to bottom.