Documentation Source Text

Check-in [03b2db4bd8]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Update the requirements.html document to actually show a list of requirements.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 03b2db4bd8bb6c58ba66de0fa792dd5f5e8ac779
User & Date: drh 2011-12-30 13:35:42
Context
2011-12-30
14:57
Major speed improvement on the script that translates requirements. Fix requirements markup in optoverview.html and in fileformat2.html. Fixes to requirements.html. check-in: 986229bc47 user: drh tags: trunk
13:35
Update the requirements.html document to actually show a list of requirements. check-in: 03b2db4bd8 user: drh tags: trunk
2011-12-25
23:06
Move the content-type meta-tag to right after the head tag. It is reported that this helps browsers to load faster. check-in: 17f12988a0 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/requirements.in.

1
2
3
4
5
6
7

8

















9
10
11
12
13









14
15








16
17
18
19
20
21





22


23
24
25
26






27
28
29
30
31
32
33

34
35
36
37
38
39
40
41









42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57





58
59





60
61














62
63
64




65
66





67
68












<!-- title>SQLite Requirements</title -->
<tcl>hd_keywords {*requirements}</tcl>

<h1>SQLite Requirements</h1>

<h2>1.0 Introduction</h2>


<p>These requirements strive to describe the interfaces and operation of 

















SQLite in sufficient detail that a compatible implementation of SQLite
can be written solely from these requirements and without reference to
the canonical SQLite source code.</p>

<p>Software development processes typically recognize a hierarchy of









requirements:</p>









<ul>
<li>System requirements</li>
<li>High-level requirements</li>
<li>Derived high-level requirements</li>
<li>Low-level requirements</li>
<li>Derived low-level requirements</li>





</ul>



<p>The usual distinction between high-level and low-level requirements is
that high-level requirements describe "what" the system does and the
low-level requirements describe "how" the system does it.  Since






the requirements denoted here describe the
behavior of SQLite and not its implementation, they are best thought of
as high-level requirements.  Consistent with that view, most of
the requirements numbers begin with the letter "<b>H</b>" (for "high-level"). 
A few of the requirements presented here specify broad objectives that
SQLite strives to achieve.  These broad requirements can be thought of
as system requirements and are number with an initial letter "<b>S</b>".</p>


<p>These requirements are hierarchical in the sense that the more
specific requirements are derived from broader and more general
requirements.  When requirement B is derived from requirement A, we say
that A is the parent of B and that B is a child of A.  The parent/child
relationships of all requirements are tracked.  All requirements presented
here ultimately derive from a single very broad, very high-level, and
very general system requirement called "S10000".</p>










<p>Some behaviors of SQLite are undefined.  For example, the order in
which result rows are returned from a SELECT statement is undefined if
there is no ORDER BY clause.  As another example, many of the C interfaces
require a pointer to an open [database connection] as their first argument
and the behavior of those interfaces is undefined (and probably undesirable)
if a pointer to some other object is supplied instead.  Some, but not all
undefined behaviors are explicitly stated and number in this document
with numbers beginning with the "<b>U</b>" for "Undefined".  Applications
that use SQLite should never depend on undefined behavior.  If a behavior
is not explicitly defined by a requirement, then the behavior is undefined,
and so explicitly stating undefined behaviors in this document is
technically redundant.  Nevertheless, we find that explicitly stating
some undefined behaviors helps application developers to better understand
the boundaries of operation of SQLite and to generate safer and more
accurate programs that use SQLite.</p>






<h2><a href="sysreq.html">2.0 System Requirements</a></h2>






<h2><a href="hlr10000.html">3.0 Application C-Language Interfaces</a></h2>















<h2><a href="hlr20000.html">4.0 C-Language Interfaces For
Extending SQLite</a></h2>





<h2><a href="hlr30000.html">5.0 Database File Format</a></h2>






<h2><a href="hlr40000.html">6.0 SQL Language Specification</a></h2>












|


|

<

>
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
<
<

<
>
>
>
>
>
>
>
>
>
|

>
>
>
>
>
>
>
>

<
<
<
<
<
>
>
>
>
>

>
>

<
<
<
>
>
>
>
>
>
|
<
<
<
<
<
<
>

<
<
<
<
<
<
<
>
>
>
>
>
>
>
>
>

<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
>
>
>
>
>

<
>
>
>
>
>

<
>
>
>
>
>
>
>
>
>
>
>
>
>
>

<
<
>
>
>
>

<
>
>
>
>
>

<
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5

6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


27

28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47





48
49
50
51
52
53
54
55
56



57
58
59
60
61
62
63






64
65







66
67
68
69
70
71
72
73
74
75















76
77
78
79
80
81

82
83
84
85
86
87

88
89
90
91
92
93
94
95
96
97
98
99
100
101
102


103
104
105
106
107

108
109
110
111
112
113

114
115
116
117
118
119
120
121
122
123
124
125
<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, or a table.  A GIF image of a bubble syntax
diagram is also a requirement.

<li><p>
Requirements are written in fluent 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 is 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 inheriently 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>"
  hd_puts "<dd><p>$reqtext <i>(source: $srcfile)</i></p></dd>"
}
</tcl>
</dl>