Documentation Source Text: Artifact Content

Artifact 0f2c2162b1070e9aac1899b0ad0a23e354b6cdea:

File pages/requirements.in — part of check-in [2cb9dc6d21] at 2012-05-12 22:37:37 on branch trunk — Fix a single spelling error. (user: drh size: 4825)
<title>SQLite Requirements</title>
<tcl>hd_keywords {*requirements}</tcl>

<h2>1.0 About SQLite Requirements</h2>


<ul>
<li><p>
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.

<li><p>
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.

<li><p>
Requirements are sufficiently detailed and precise to permit a 100% compatible
clean-room reimplementation of SQLite.

<li><p>
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".

<li><p>
Every testable statement of truth about SQLite in the
documentation becomes a requirement.

<li><p>
Requirement numbers are the MD5 hash of the requirement itself.
<ol type="a">
<li><p>Requirements are inherently immutable, since any change
to the requirement results in a completely different requirement number.

<li><p>For text requirements, the text is normalized prior to computing the
MD5 hash:
<ul>
<li>Remove all leading and trailing whitespace.
<li>Convert all internal whitespace sequences to a single space character.
<li>Convert "&amp;lt;" to "&lt;", "&amp;gt;" to "&gt;",
    "&amp;#91;" to "&#91;", "&amp;#93;" to "&#93;", and
    "&amp;amp;" to "&amp;".
</ul>
<li><p>For GIF syntax diagram requirements, the MD5 hash is computed over
the entire content of the GIF image file.

<li><p>The MD5 hash is expressed in human-readable form as follows:
<blockquote><b>R-</b><i>N</i><b>-</b><i>N</i><b>-</b><i>N</i><b>-</b><i>N</i><b>-</b><i>N</i><b>-</b><i>N</i><b>-</b><i>N</i><b>-</b><i>N</i></blockquote>
Where each <i>N</i> is a 5-digit number between 00000 and 65536 that
represents 16 bits of the 128-bit MD5 hash.

<li><p>Requirements may be referenced by any unique prefix of their
complete requirement number.
</ol>

<p><li>
Individual text requirements are identified in the
documentation as text between "<b>&#94;</b>" and the first period or
full-stop ("<b>.</b>")
or as text between "<b>&#94;(</b>" and "<b>)&#94;</b>".
<ol type="a">
<li><p>
Text requirements are automatically extracted from the documentation by scripts
that run as part of the documentation build process.

<li><p>
After requirements have been extracted from the documentation, the requirement
markers "<b>&#94;</b>", "<b>&#94;(</b>", and "<b>)&#94;</b>" are removed
from the documentation text.  This is done automatically by the documentation
build scripts.

<li><p>
To avoid collisions with these requirements delimiters, "&#94;" characters that
are part of the text of a requirement or that are otherwise found in the 
documentation, should be coded as "&amp;#94;".
</ol>

<p><li>
Individual GIF syntax diagram requirements are identified in the
documentation as HTML image markup of the
form
<blockquote><b>
&lt;img alt="syntax diagram </b><i>NAME</i><b>" src="</b><i>FILE</i><b>"&gt;
</b></blockquote>
Where <i>NAME</i> is the name of the syntax diagram and <i>FILE</i> is
the name of the GIF file containing the syntax diagram.
<ol type="a">
<li><p>
Syntax diagram requirements are automatically extracted from the 
documentation by scripts
that run as part of the documentation build process.

<li><p>
The GIF file is the requirement, not the HTML markup that references the
GIF file nor the diagram name.
</ol>

<li><p>
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.

</ul>


<h2>2.0 List Of Requirements</h2>

<dl>
<tcl>
db eval {SELECT * FROM requirement ORDER BY reqno} {
  hd_puts "<dt><b>$reqno</b></dt>\n"
  if {$reqimage} {
    hd_puts "<dd><p>$origtext<br>\n"
  } else {
    hd_puts "<dd><p>$reqtext\n"
  }
  set ck [
    db eval {SELECT DISTINCT srccat || '/' || srcfile FROM evidence
             WHERE reqno=$reqno ORDER BY 1}
  ]
  hd_puts "<i>(source <a href=\"$srcfile\">$srcfile</a>"
  if {[llength $ck]==0} {
    hd_puts ")</i>"
  } else {
    hd_puts ", checked-by: [join $ck {, }])</i>"
  }
  hd_puts "</p></dd>\n\n"
}
</tcl>
</dl>