The documentation on the web pages, like Gaul, is divided into three parts.
The Gentle Introduction is a simple guide aimed primarily at users not familiar with a terminal-and-keyboard environment. It walks the reader through downloading the ivi/VINCI software, inspecting some small VINCI language description files, and generating some words and phrases. Those with some experience of this kind of environment may well wish to skip it.
The Overview introduces VINCI and gives a brief portrayal of its wide range of capabilities.
The Manual gives fuller and more precise details. It does not, however, repeat material and examples given in the Overview, and assumes that the reader has read the Overview at least as far as the corresponding topic and sometimes beyond. It is likely that readers will pass back and forth between Overview and Manual, reading about a topic in the former and looking at its expansion in the latter. One note of caution: the Manual was written sequentially and later sections sometimes use concepts, features and terminology defined or discussed in earlier ones. In any event, it is advisable to read the section of the Manual on Preliminaries before looking at the others.
Overview and Manual are intended for a mixed audience, some of whom will have more computing knowledge than others. Both, therefore, have brief insertions or even sections addressed to persons with specific knowledge (for example, those with knowledge of programming or of formal theory). The Manual also adds such notes to mention exceptions, extras, etc., which would over-complicate the main flow of the description. Short "footnotes" or comments of this kind are spaced over to the right-hand side, and can safely be omitted. Added sections are individually identified. (If the Overview and Manual are printed using older versions of Netscape, the side comments are not always shifted.)
Some parts of the Manual, especially those dealing with VINCI commands and operations, assume at least a minimal experience with the ivi Editor, which is described elsewhere in these webpages.
The Manual attempts to be comprehensive and may therefore appear forbidding at first sight. Straightforward applications, however, are likely to use only a few of the features.
Attempting to rewrite the Manual in a comprehensive form after several years has proved to be an interesting experience. Two questions have manifested themselves constantly: Am I really sure? and, Why did we design it that way?
The first typically arises out of the fine details and restrictions of features which the writer has not used recently. There are two ways to check these: to write a test case or to read the code. Both are time-consuming and neither is conclusive. (Even in the best documented code, there are facts and consequences which are obvious when the code is familiar but fade a few weeks later.) In the circumstances, and in the interests of finishing the document within a finite period, the writer has chosen not to second-guess himself. Some errors, mostly minor, may be present. When time permits, they will be fixed. In a few such cases, the notation ### is used to mark these doubts.
The second is inevitable in a system which has evolved over twenty years. Again it is system limitations which often bring the question to light, commonly limitations in regard to the chronologically earlier features. In the early days, we may have designed feature X, but not foreseen the range of variations which might be useful; in a later development, we may have introduced feature Y, which parallels X but embodies a wider range of possibilities. Then we ask why X does not parallel Y more closely, why X is not more general, and so on. These cases have been noted for possible future upgrading. Sometimes they are mentioned in the side comments.