Documentation Source Text

Check-in [986229bc47]
Login

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

Overview
Comment:Major speed improvement on the script that translates requirements. Fix requirements markup in optoverview.html and in fileformat2.html. Fixes to requirements.html.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 986229bc47ff9c978085ad00594bca66a6fb1a33
User & Date: drh 2011-12-30 14:57:23
Context
2011-12-30
15:04
Additional "help" printout from the Makefile. check-in: e044ff8645 user: drh tags: trunk
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
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to matrix.tcl.

36
37
38
39
40
41
42

43
44
45
46
47
48
49
...
558
559
560
561
562
563
564

565
566
567
568
569
570
571
...
574
575
576
577
578
579
580
581


582
583
584
585
586
587
588
# information.  See the schema.tcl source file for a definition of the
# requirment table.
#
puts -nonewline "Scanning documentation for testable statements"
flush stdout
foreach file $filelist {
  puts -nonewline .

  flush stdout
  set in [open $file]
  set x [read $in [file size $file]]
  close $in
  set orig_x $x
  set origlen [string length $x]
  regsub {^doc/} $file {} srcfile
................................................................................

# Translate documentation to show requirements with links to the matrix.
#
puts -nonewline "Translating documentation"
flush stdout
foreach file $filelist {
  puts -nonewline .

  flush stdout
  regsub {^doc/} $file {} basename
  set outfile doc/matrix/$basename
  if {![info exists matrixname($basename)]} {
    file copy -force $file $outfile
    continue
  }
................................................................................
  close $in
  if {[regexp / $basename]} {
    set matrixpath ../$matrixname($basename)
  } else {
    set matrixpath $matrixname($basename)
  }
  set out {}
  while {[string length $x]>0 && [regexp {^(.*?)\^} $x all prefix]} {


    append out $prefix
    set n [string length $prefix]
    set nx [string range $x [expr {$n+1}] end]
    set c [string index $nx 0]
    if {$c=="("} {
      regexp {^\((([^<]|<.+?>)*?)\)\^} $nx all req
      regsub {^\((([^<]|<.+?>)*?)\)\^} $nx {} nx







>







 







>







 







|
>
>







36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
...
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
...
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
# information.  See the schema.tcl source file for a definition of the
# requirment table.
#
puts -nonewline "Scanning documentation for testable statements"
flush stdout
foreach file $filelist {
  puts -nonewline .
  # puts -nonewline "$file"
  flush stdout
  set in [open $file]
  set x [read $in [file size $file]]
  close $in
  set orig_x $x
  set origlen [string length $x]
  regsub {^doc/} $file {} srcfile
................................................................................

# Translate documentation to show requirements with links to the matrix.
#
puts -nonewline "Translating documentation"
flush stdout
foreach file $filelist {
  puts -nonewline .
  # puts $file
  flush stdout
  regsub {^doc/} $file {} basename
  set outfile doc/matrix/$basename
  if {![info exists matrixname($basename)]} {
    file copy -force $file $outfile
    continue
  }
................................................................................
  close $in
  if {[regexp / $basename]} {
    set matrixpath ../$matrixname($basename)
  } else {
    set matrixpath $matrixname($basename)
  }
  set out {}
  while {[string length $x]>0 && [set n [string first ^ $x]]>=0} {
    incr n -1
    set prefix [string range $x 0 $n]
    append out $prefix
    set n [string length $prefix]
    set nx [string range $x [expr {$n+1}] end]
    set c [string index $nx 0]
    if {$c=="("} {
      regexp {^\((([^<]|<.+?>)*?)\)\^} $nx all req
      regsub {^\((([^<]|<.+?>)*?)\)\^} $nx {} nx

Changes to pages/fileformat2.in.

903
904
905
906
907
908
909
910
911

912
913
914
915
916
917
918

919
920
921
922
923
924
925
926
....
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
....
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
....
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
the records that the keys represent.  Record comparison progresses column
by column.  Columns of a record are examined from left to right.  The
first pair of columns that are not equal determines the relative order
of the two records.  The sort order of individual columns is as
follows:</p>

<ol>
<li>^NULL values (serial type 0) sort first
<li>^Numeric values (serial types 1 through 9) sort next and in numeric order

<li>^Text values (odd serial types 13 and larger) sort next in the order
    determined by the columns [collating function]
<li>^BLOB values (even serial types 12 and larger) sort last in order 
    determined by memcmp().
</ol>

<p>A [collating function] for each column is necessary in order to compute

the order of text fields.  ^SQLite defines three built-in collating functions:
</p>

<blockquote><table border=0 cellspacing=10>
<tr>^<td valign=top>BINARY
    <td>Strings are compared byte by byte using the memcmp() function
        from the standard C library.
<tr>^<td valign=top>NOCASE
................................................................................

<p>^The sqlite_master table contains a row for each table, index, view,
and trigger in the database schema, except there is no entry for the
sqlite_master table itself.</p>

<p>^(The sqlite_master.type column will be one
of the following text strings:  'table', 'index', 'view', or 'trigger'
according to the type of object defined.  ^The 'table' string is used
for both ordinary and [virtual tables].)^</p>

</p>^(The sqlite_master.name column will hold the name of the object.
^For indices that are automatically created by UNIQUE or PRIMARY KEY
constraints, the name is "sqlite_autoindex_TABLE_N" where TABLE is 
replaced by the name of the table that contains the constraint and N 
is an integer beginning
with 1 and increasing by one with each constraint seen.)^</p>

<p>The sqlite_master.tbl_name column holds the name of a table or view
that the object is associated with.  ^For a table or view, the
................................................................................
and virtual tables, the rootpage column is 0 or NULL.</p>

<p>^(The sqlite_master.sql column stores SQL text that describes the
object.  This SQL text is a [CREATE TABLE], [CREATE VIRTUAL TABLE],
[CREATE INDEX],
[CREATE VIEW], or [CREATE TRIGGER] statement that if evaluated against
the database file when it is the main database of a [database connection]
would recreated the object.)  The text is usually a copy of the original
statement used to create the object but with normalizations applied so
that the text conforms to the following rules:

<ul>
<li>^The CREATE, TABLE, VIEW, TRIGGER, and INDEX keywords at the beginning
of the statement are converted to all upper case letters.
<li>^The TEMP or TEMPORARY keyword is removed if it occurs after the 
................................................................................
detected and the journal will be automatically played back to restore the
database to its state at the start of the incomplete transaction.</p>

<p>^A rollback journal is only considered to be valid if it exists and
contains a valid header.  Hence a transaction can be committed in one
of three ways:
<ol>
<li>^The rollback journal file can be deleted,
<li>^The rollback journal file can be truncated to zero length, or
<li>^The header of the rollback journal can be overwritten with
invalid header text (for example, all zeros).
</ol>
^These three ways of committing a transaction correspond to the DELETE,
TRUNCATE, and PERSIST settings, respectively, of the [journal_mode pragma].
</p>


<p>A valid rollback journal begins with a header in the following format:</p>







|
|
>
|
|
|
|



>
|







 







|


|
|







 







|







 







|
|
|
|







903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
....
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
....
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
....
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
the records that the keys represent.  Record comparison progresses column
by column.  Columns of a record are examined from left to right.  The
first pair of columns that are not equal determines the relative order
of the two records.  The sort order of individual columns is as
follows:</p>

<ol>
<li>^(NULL values (serial type 0) sort first.)^
<li>^(Numeric values (serial types 1 through 9) sort after NULLs
      and in numeric order.)^
<li>^(Text values (odd serial types 13 and larger) sort after numeric
    values in the order determined by the columns [collating function].)^
<li>^(BLOB values (even serial types 12 and larger) sort last and in the order 
    determined by memcmp().)^
</ol>

<p>A [collating function] for each column is necessary in order to compute
the order of text fields.
^(SQLite defines three built-in collating functions:)^
</p>

<blockquote><table border=0 cellspacing=10>
<tr>^<td valign=top>BINARY
    <td>Strings are compared byte by byte using the memcmp() function
        from the standard C library.
<tr>^<td valign=top>NOCASE
................................................................................

<p>^The sqlite_master table contains a row for each table, index, view,
and trigger in the database schema, except there is no entry for the
sqlite_master table itself.</p>

<p>^(The sqlite_master.type column will be one
of the following text strings:  'table', 'index', 'view', or 'trigger'
according to the type of object defined.  The 'table' string is used
for both ordinary and [virtual tables].)^</p>

</p>^(The sqlite_master.name column will hold the name of the object.)^
^(For indices that are automatically created by UNIQUE or PRIMARY KEY
constraints, the name is "sqlite_autoindex_TABLE_N" where TABLE is 
replaced by the name of the table that contains the constraint and N 
is an integer beginning
with 1 and increasing by one with each constraint seen.)^</p>

<p>The sqlite_master.tbl_name column holds the name of a table or view
that the object is associated with.  ^For a table or view, the
................................................................................
and virtual tables, the rootpage column is 0 or NULL.</p>

<p>^(The sqlite_master.sql column stores SQL text that describes the
object.  This SQL text is a [CREATE TABLE], [CREATE VIRTUAL TABLE],
[CREATE INDEX],
[CREATE VIEW], or [CREATE TRIGGER] statement that if evaluated against
the database file when it is the main database of a [database connection]
would recreated the object.)^  The text is usually a copy of the original
statement used to create the object but with normalizations applied so
that the text conforms to the following rules:

<ul>
<li>^The CREATE, TABLE, VIEW, TRIGGER, and INDEX keywords at the beginning
of the statement are converted to all upper case letters.
<li>^The TEMP or TEMPORARY keyword is removed if it occurs after the 
................................................................................
detected and the journal will be automatically played back to restore the
database to its state at the start of the incomplete transaction.</p>

<p>^A rollback journal is only considered to be valid if it exists and
contains a valid header.  Hence a transaction can be committed in one
of three ways:
<ol>
<li>^(The rollback journal file can be deleted)^,
<li>^(The rollback journal file can be truncated to zero length)^, or
<li>^(The header of the rollback journal can be overwritten with
invalid header text (for example, all zeros).)^
</ol>
^These three ways of committing a transaction correspond to the DELETE,
TRUNCATE, and PERSIST settings, respectively, of the [journal_mode pragma].
</p>


<p>A valid rollback journal begins with a header in the following format:</p>

Changes to pages/optoverview.in.

171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
  ^(For the index above and WHERE clause like this:
}
CODE {
  ... WHERE b IN (1,2,3) AND c NOT NULL AND d='hello'
}
PARAGRAPH {
  The index is not usable at all because the left-most column of the
  index (column "a") is not constrained.^)  ^Assuming there are no other
  indices, the query above would result in a full table scan.
}
PARAGRAPH {
  ^(For the index above and WHERE clause like this:
}
CODE {
  ... WHERE a=5 OR b IN (1,2,3) OR c NOT NULL OR d='hello'







|







171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
  ^(For the index above and WHERE clause like this:
}
CODE {
  ... WHERE b IN (1,2,3) AND c NOT NULL AND d='hello'
}
PARAGRAPH {
  The index is not usable at all because the left-most column of the
  index (column "a") is not constrained.)^  ^Assuming there are no other
  indices, the query above would result in a full table scan.
}
PARAGRAPH {
  ^(For the index above and WHERE clause like this:
}
CODE {
  ... WHERE a=5 OR b IN (1,2,3) OR c NOT NULL OR d='hello'

Changes to pages/requirements.in.

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
...
108
109
110
111
112
113
114

115
116
117
118
119
120
121
122
123
124
125
<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
................................................................................
<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>







|
|


|



|
|
|
|







 







>











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
...
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
<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
................................................................................
<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>