*** DRAFT ***
Requirements consist of excerpts from the documentation. A requirement is usually a one-sentence excerpt but might be a sentence fragment, multiple sentences, a table, or a GIF image of a bubble syntax diagram.
Requirements are written in conversational English and without the modal auxiliary verb "shall". This grows out of the fact that requirements are taken from the documentation. The intended audience for the documentation is application programmers. "Shall" language is appropriate when the audience consist of contract specialists, QA auditors, and lawyers, but it interferes with comprehension when the audience is application programmers. Hence, in order to best serve the intended audience, the "shall" language is omitted.
Requirements are sufficiently detailed and precise to permit a 100% compatible clean-room reimplementation of SQLite.
The word "requirement" in common English usage implies an ordering: that the requirement comes before the implementation. But there is no such ordering with SQLite requirements. What are called "requirements" in SQLite are better described as "testable statements of truth about the behavior of the system".
Every testable statement of truth about SQLite in the documentation becomes a requirement.
Requirement numbers are the MD5 hash of the requirement itself.
Requirements are inherently immutable, since any change to the requirement results in a completely different requirement number.
For text requirements, the text is normalized prior to computing the MD5 hash:
For GIF syntax diagram requirements, the MD5 hash is computed over the entire content of the GIF image file.
The MD5 hash is expressed in human-readable form as follows:
R-N-N-N-N-N-N-N-NWhere each N is a 5-digit number between 00000 and 65536 that represents 16 bits of the 128-bit MD5 hash.
Requirements may be referenced by any unique prefix of their complete requirement number.
Text requirements are automatically extracted from the documentation by scripts that run as part of the documentation build process.
After requirements have been extracted from the documentation, the requirement markers "^", "^(", and ")^" are removed from the documentation text. This is done automatically by the documentation build scripts.
To avoid collisions with these requirements delimiters, "^" characters that are part of the text of a requirement or that are otherwise found in the documentation, should be coded as "^".
<img alt="syntax diagram NAME" src="FILE">Where NAME is the name of the syntax diagram and FILE is the name of the GIF file containing the syntax diagram.
Syntax diagram requirements are automatically extracted from the documentation by scripts that run as part of the documentation build process.
The GIF file is the requirement, not the HTML markup that references the GIF file nor the diagram name.
The documentation that contains the requirement text is generated by scripts that use as input files from both files in the documentation fossil repository and comments in the source code.