Changes were made to the requirements after the document itself had been approved by the company. They are noted here, and follow the same order as the original versions in the Requirements Document.
AUTHOR ERRORS
These were not explained in detail in the original document. Basically, they are messages which appear on screen at runtime, if an author has tried to do something that is not allowed by a function. For example, with an 80 column screen an author should not use putcursor(10,150).
If an author error occurs, then the program will first search for other author errors, and then terminate. Note that there will not be any typing errors, these will all have been found at compilation time.
The screen is to be divided into three areas; header (one line), main display area (23 lines if a 25 line screen is used), message (1 line). This change was made at the company's request.
The formerly undefined "don't know" key is now the Fl function key that should be found on all IBM PC compatibles, and now, rather than indicating that a student is unable to answer a question, it is a request for help. This change was made at the request of the company.
One general change that is not repeated further concerns the results that are returned by the matching functions. The original document specified characters should be returned; an enumerated type is to be used instead. The full set of values that can be returned by the matching functions is:
{ HELPREQ, MATCH, NOANS, NOMATCH, OPT1, OPT2, OPT3, OPT4, OPT5, OPT6, PM1, PM2, PM3, PM4, PM5, PM6, PM7, PM8 }
Not all functions return values from the full set, so for each of the matching functions, there is a list of the values that can be returned, along with an explanation of what each value means, if that value has not been described previously.
The following match results are common to all match functions (except getanswer):
| HELPREQ | the Fl help key was pressed. |
| MATCH | the answer was judged as correct. |
| NOANS | no attempt was made to answer, Enter key only was pressed. |
| NOMATCH | the answer could not be matched to the model. |
getanswer
The format of this was changed due to implementation limitations (explained in the design section), and is now:
getanswer( variable_name, length )
The line which is drawn to indicate the length and location of the answer is erased as the answer is written, and replaced if the answer is erased with the back arrow key.
The Fl HELP key can be used with this function, but nevertheless, the function still returns a character string. (In the current system this is '?' which is analysed by the match test functions as a request for help. This means that authors cannot use a single question mark as a model answer. However, this should pose no practical problem.)
multiple choice function
Originally, this was to be: mc(stem, optionlist) --> result
There are now five multiple choice functions:
mc2(stem, optl, opt2) --> result
mc3(stem, optl, opt2, opt3) --> result
mc4(stem, optl, opt2, opt3, opt4) --> result
mc5(stem, optl, opt2, opt3, opt4, opt5) --> result
mc6(stem, optl, opt2, opt3, opt4, opt5, opt6) --> result
They all take a stem which can be any number of lines (as long as all the options can also fit on the screen), followed by a number of options corresponding to the name of the function.
Optionlist in the original equates to optl, opt2, etc. There is no change in the way the optionlist is used, the change is merely one of nomenclature.
The results set is:
{ HELPREQ, OPT1, OPT2, OPT3, OPT4, OPT5, OPT6 }
In general, mcn returns one of HELPREQ, OPT1, ..., OPTn
If there are more or less options in the parameter list than the function expects, an author error message will be shown on screen.
On exit from the function, the cursor is set to the row following the last option, at column one.
Although the change from the original requirements was made because the implementation language does not allow (as far as I have been able to ascertain) a function to take a variable number of parameters without a terminator, the company's project supervisor preferred the new requirements, since they show explicitly how many options are to be used.
One general change concerns the match parameter list, which is no longer optional, due to the limitation of not being able to use a variable number of parameters without a sentinel to mark the end of the list.
The match parameter list for the match functions is now:
" [ [B] [C] [P] [S] ] " | ALL | NONE | DEF
[] indicates any combination, or none, may be chosen.
| indicates that any one option may be chosen.
Spaces are not important.
Opening and closing quotes must be used with B, C, P, S.
ALL corresponds to "BCPS", that is, blanks, case, punctuation, and spaces in the model and the answer should match exactly. In the original Requirements Document it was called E (everything).
NONE is the least restrictive match, and is equivalent to an empty match parameter list, ie "". Blanks, case, and spaces in the answer are not important, and in addition, the spelling assistant will be on, thus allowing typographical errors in an answer.
DEF means that the function should use the default, which is either the system default (= NONE), or the default which was set with the function set_match_params, if this function has been used.
In the original Requirements Document no details were given of the requirements for acceptance of spelling errors. These have now been selected as transposition, omission, insertion, and substitution, and an intelligent spelling assistant incorporated into the match functions will be used to identify these errors. (See 3.4 for a full explanation of terms, and a discussion of the spelling assistant.)
All the matching functions are to allow one error in each word, and additionally, if the model contains wildcards or wildcharacters, each section of the answer that corresponds to a section of the model contained within a wildcard/character is allowed to have one of the aforementioned errors.
A wildcharacter represents one character, and a wildcard represents any number (including zero) of characters. Refer to section 2.3.3 for details of how these are used. Within the constraints set by the getanswer function, there is no limit to the number of wildcards or wildcharacters that may be used in a model.
alphamatch(model, answer, match_params) --> result
No change, apart from result, which is one of:
{ HELPREQ, MATCH, NOANS, NOMATCH }
findword(model, answer, match_params) --> result
No change, apart from result, which is one of:
{ HELPREQ, MATCH, NOANS, NOMATCH }
Note that spaces in a model are irrelevant, and if the S match parameter is specified in the parameter list, or if it was set using the set_match_params function, it will have no effect on the result.
match_any(n, model, answer, match_params) --> result
If the model contains more than 9 words, an author error will be generated.
Results can be one of:
{ HELPREQ, MATCH, NOANS, NOMATCH, PM1, PM2, PM3, PM4, PM5, PM6, PM7, PM8 }
In this context MATCH means that all of (or more than) the required number of words have been found.
NOMATCH is total failure, not even one word was matched
PMm indicates that m words have been matched. Note that at most, m corresponds to the integer value (n - 1).
Note that spaces in a model are irrelevant, and if the S match parameter is specified in the parameter list, or if it was set using the set_match_params function, it will have no effect on the result.
match_ordered(n, model, answer, match_params) --> result
Changes as for match_any.
Similar changes to those mentioned above should be made to the number match functions.
Additionally, one of the user requirements was that the number match functions should deal with symbols (such as Cr., $, E, etc), so provision for this should be made in the number match functions.
However, since the development of these functions was curtailed at an early stage, detailed investigation of the changes necessary was not done.
Since branching commands in the C implementation are available in a suitable format (ie IF condition THEN goto), the analyse match results functions were redundant, as the only reason for their existence was to reduce the workload so that effort could be put into development of the matching functions. If the analyse functions were to have been developed, then the original requirements would have to be altered to fit in with the new requirements of the matching functions (most notably the use of an enumerated type to return match results).
As an aside, in spite of the general principle of not using goto statements, which has been impressed on the minds of programmers since the days of Dijkstra's famous article entitled "Use of goto considered harmful" onwards, for small-scale CBT authoring, it is the most convenient method of branching to use. Therefore, it is used.
clear(row-n, row m) has been renamed clearbetween for the simple reason that this new name is more expressive.
Due to the changes made to the screen, n and m must be between one and 23 (for a twenty-five line screen). n must be less than or equal to m.
header( text )
This is a new function, which erases any existing text in the header area, and then writes the new text. If the text is longer than the screen (or window) width, or if it contains any characters which would cause a new line to be written, an author error message will be generated.
set_match_params( parameter_list )
The parameter list is now defined as:
" [ [B] [C] [P] [S] ] " | ALL | NONE
[] indicates any combination, or none, may be chosen.
| indicates that any one option may be chosen.
Spaces are not important.
Opening and closing quotes must be used with B, C, P, S.
See section 4B.2, under Test for Match, for the meaning of the parameters.
Preface | Contents | 1 Introduction | 2 Review | 3 Req. analysis | 4 Req. documents (4A, 4B) | 5 Specification | 6 Design | 7 Verification | 8 Discussion | 9 PAL manual | Appendix A | Appendix B | Appendix C | Glossary | References | Index