Documentation Source Text

Check-in [61f2878145]
Login

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

Overview
Comment:Only count duplicate requirements once when scoring, but show every usage in the matrix reports.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 61f2878145a36b42e03ea5ed88d40091d82ac91b
User & Date: drh 2015-03-05 00:17:40
Context
2015-03-05
01:22
Fix a bug in matrix generation. Relax a restriction on the use of VALUES clauses - a restriction that did not actually apply. Fix a formatting problem in the FTS5 docs. check-in: f61b2a7935 user: drh tags: trunk
00:17
Only count duplicate requirements once when scoring, but show every usage in the matrix reports. check-in: 61f2878145 user: drh tags: trunk
2015-03-04
23:15
Clarifications on INDEXED BY documentation. Syntax diagrams which are default visible are always requirements even if they occur multiple times, but syntax diagrams that are default hidden now have the "data-noreq" attribute which prevents them from being marked as requirements. check-in: 000660158c user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to main.mk.

51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
	./tclsh $(SRC)/tool/mksqlite3h.tcl $(SRC) | \
	sed 's/^SQLITE_API //' >sqlite3.h

# Generate the directory into which generated documentation files will
# be written.
#
docdir:
	mkdir -p doc doc/c3ref doc/matrix doc/matrix/c3ref

# This rule generates all documention files from their sources.  The
# special markup on HTML files used to identify testable statements and
# requirements are retained in the HTML and so the HTML generated by
# this rule is not suitable for publication.  This is the first step
# only.
#







|







51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
	./tclsh $(SRC)/tool/mksqlite3h.tcl $(SRC) | \
	sed 's/^SQLITE_API //' >sqlite3.h

# Generate the directory into which generated documentation files will
# be written.
#
docdir:
	mkdir -p doc doc/c3ref doc/matrix doc/matrix/c3ref doc/matrix/syntax

# This rule generates all documention files from their sources.  The
# special markup on HTML files used to identify testable statements and
# requirements are retained in the HTML and so the HTML generated by
# this rule is not suitable for publication.  This is the first step
# only.
#

Changes to matrix.tcl.

2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
..
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
..
80
81
82
83
84
85
86




87
88
89
90
91
92
93
...
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
...
437
438
439
440
441
442
443
444

445
446

447
448
449
450
451
452
453
454
...
469
470
471
472
473
474
475



476
477
478
479
480
481
482
...
625
626
627
628
629
630
631
632
633
634
635

636
637
638
639
640
641
642
643
#
# This script generates the requirements traceability matrix and does
# other processing related to requirements and coverage analysis.
#

# Get a list of source HTML files.
#
set filelist [lsort [glob -nocomplain doc/*.html doc/c3ref/*.html]]
foreach exclude {doc/capi3ref.html doc/changes.html} {
  set i [lsearch $filelist $exclude]
  set filelist [lreplace $filelist $i $i]
}

# Initialize the database connection.
#
................................................................................
flush stdout
foreach file $filelist {
  if {$file=="doc/fileformat.html" 
        && [lsearch $filelist doc/fileformat2.html]>=0} {
    continue
  }
  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
................................................................................
      puts "$srcfile: duplicate [string range $reqno 0 12] in $s2: \[$r2\]"
    }
    db eval {
      INSERT OR IGNORE INTO requirement
              (reqno, reqtext, origtext, reqimage,srcfile,srcseq)
        VALUES($reqno,$req,    $orig,    0,      $srcfile,$seqno);
    }




    set x $nx
  }
  set x $orig_x
  unset orig_x
  while {[string length $x]>0 
     && [regexp {^(.+?)(<img alt="syntax diagram .*)$} $x all prefix suffix]} {
    set x $suffix
................................................................................
      set orig "<img src=\"$image\">"
      if {![file exists doc/$image]} {
        puts stderr "No such image: doc/$image"
        continue
      }
      set reqno R-[md5file-10x8 doc/$image]

      # We dont really care about duplicate image file references
      #db eval {SELECT srcfile AS s2, reqtext as r2
      #         FROM requirement WHERE reqno=$reqno} {
      #  puts "$srcfile: duplicate image [file tail $image]\
      #        [string range $reqno 0 12] in $s2"
      #}

      db eval {
        INSERT OR IGNORE INTO requirement
                (reqno, reqtext, origtext, reqimage,srcfile,srcseq)
          VALUES($reqno,$req,    $orig,    1,      $srcfile,$seqno);
      }




    }
  }
}
db eval COMMIT
set cnt [db one {SELECT count(*) FROM requirement}]
set evcnt [db one {
  SELECT count(*) FROM requirement WHERE reqno IN (SELECT reqno FROM evidence)
................................................................................
  puts $out "[file tail $srcfile]</h1>"
  puts $out "<h2><a href=\"matrix.html\">Index</a>"
  puts $out "<a href=\"matrix_s$docid.html\">Summary</a>"
  puts $out "<a href=\"$basename\">Markup</a>"
  puts $out "<a href=\"../$basename\">Original</a></h2>"

  db eval {
    SELECT reqno, reqimage, origtext, reqtext

      FROM requirement
     WHERE srcfile=$srcfile

     ORDER BY srcseq
  } {
    puts $out "<hr><a name=\"$reqno\"></a>"
    puts $out "<p><a href=\"$basename#$reqno\">$reqno</a>"

    set ev(tcl) 0
    set ev(slt) 0
    set ev(th3) 0
................................................................................
        incr proof($reqno)
      } else {
        set cx evnil
      }
      puts $out "<cite class=$cx>$srcclass</cite>"
    }
    puts $out "</p>"



    set orig [string map -nocase {<dt> {} </dt> {} <dd> {} </dd> {}} $origtext]
    puts $out "<p>$orig</p>"
    set sep <p>

    db eval {
      SELECT srccat || '/' || srcfile || ':' || srcline AS x, url
        FROM evidence
................................................................................
  set x $out
  set out {}
  while {[string length $x]>0 
     && [regexp {^(.+?)(<img alt="syntax diagram .*)$} $x all prefix suffix]} {
    append out $prefix
    set x $suffix
    if {[regexp \
           {<img alt="(syntax diagram [-a-z]+)" src="[./]*([-./a-z]+\.gif)"} \
           $x all name image]} {
      #puts "DIAGRAM: $file $name $image"
      set req $name

      set rno R-[md5file-10x8 doc/$image]
      set shortrno [string range $rno 0 12]
      append out "<a name=\"$rno\"></a><font color=\"blue\"><b>"
      set link "<a href=\"$matrixpath#$rno\" style=\"color: #0000ff\">"
      append out "$link$shortrno</a>:\[</b></font>\n"
      if {$proof($rno)>=2} {
        set clr green
      } elseif {$proof($rno)==1} {







|







 







|







 







>
>
>
>







 







|
<
|
<
<
<
>





>
>
>
>







 







|
>
|
|
>
|







 







>
>
>







 







|



>
|







2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
..
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
..
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
...
104
105
106
107
108
109
110
111

112



113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
...
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
...
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
...
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
#
# This script generates the requirements traceability matrix and does
# other processing related to requirements and coverage analysis.
#

# Get a list of source HTML files.
#
set filelist [lsort [glob -nocomplain doc/*.html doc/c3ref/*.html doc/syntax/*.html]]
foreach exclude {doc/capi3ref.html doc/changes.html} {
  set i [lsearch $filelist $exclude]
  set filelist [lreplace $filelist $i $i]
}

# Initialize the database connection.
#
................................................................................
flush stdout
foreach file $filelist {
  if {$file=="doc/fileformat.html" 
        && [lsearch $filelist doc/fileformat2.html]>=0} {
    continue
  }
  puts -nonewline .
  # puts "$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
................................................................................
      puts "$srcfile: duplicate [string range $reqno 0 12] in $s2: \[$r2\]"
    }
    db eval {
      INSERT OR IGNORE INTO requirement
              (reqno, reqtext, origtext, reqimage,srcfile,srcseq)
        VALUES($reqno,$req,    $orig,    0,      $srcfile,$seqno);
    }
    db eval {
      INSERT OR IGNORE INTO reqsrc(srcfile, srcseq, reqno)
      VALUES($srcfile, $seqno, $reqno)
    }
    set x $nx
  }
  set x $orig_x
  unset orig_x
  while {[string length $x]>0 
     && [regexp {^(.+?)(<img alt="syntax diagram .*)$} $x all prefix suffix]} {
    set x $suffix
................................................................................
      set orig "<img src=\"$image\">"
      if {![file exists doc/$image]} {
        puts stderr "No such image: doc/$image"
        continue
      }
      set reqno R-[md5file-10x8 doc/$image]

      if {[string match *syntax/*.html $srcfile]} {

        db eval {DELETE FROM requirement WHERE reqno=$reqno}



      }
      db eval {
        INSERT OR IGNORE INTO requirement
                (reqno, reqtext, origtext, reqimage,srcfile,srcseq)
          VALUES($reqno,$req,    $orig,    1,      $srcfile,$seqno);
      }
      db eval {
        INSERT OR IGNORE INTO reqsrc(srcfile, srcseq, reqno)
        VALUES($srcfile,$seqno,$reqno)
      }
    }
  }
}
db eval COMMIT
set cnt [db one {SELECT count(*) FROM requirement}]
set evcnt [db one {
  SELECT count(*) FROM requirement WHERE reqno IN (SELECT reqno FROM evidence)
................................................................................
  puts $out "[file tail $srcfile]</h1>"
  puts $out "<h2><a href=\"matrix.html\">Index</a>"
  puts $out "<a href=\"matrix_s$docid.html\">Summary</a>"
  puts $out "<a href=\"$basename\">Markup</a>"
  puts $out "<a href=\"../$basename\">Original</a></h2>"

  db eval {
    SELECT requirement.reqno, reqimage, origtext, reqtext,
           CASE WHEN requirement.srcfile!=$srcfile THEN requirement.srcfile END AS canonical
      FROM requirement, reqsrc
     WHERE reqsrc.srcfile=$srcfile
       AND reqsrc.reqno=requirement.reqno
     ORDER BY reqsrc.srcseq
  } {
    puts $out "<hr><a name=\"$reqno\"></a>"
    puts $out "<p><a href=\"$basename#$reqno\">$reqno</a>"

    set ev(tcl) 0
    set ev(slt) 0
    set ev(th3) 0
................................................................................
        incr proof($reqno)
      } else {
        set cx evnil
      }
      puts $out "<cite class=$cx>$srcclass</cite>"
    }
    puts $out "</p>"
    if {$canonical!=""} {
      puts $out "<p>Canonical usage: <a href='$canonical'>$canonical</a></p>"
    }
    set orig [string map -nocase {<dt> {} </dt> {} <dd> {} </dd> {}} $origtext]
    puts $out "<p>$orig</p>"
    set sep <p>

    db eval {
      SELECT srccat || '/' || srcfile || ':' || srcline AS x, url
        FROM evidence
................................................................................
  set x $out
  set out {}
  while {[string length $x]>0 
     && [regexp {^(.+?)(<img alt="syntax diagram .*)$} $x all prefix suffix]} {
    append out $prefix
    set x $suffix
    if {[regexp \
           {<img alt="(syntax diagram [-a-z]+)" src="([-./a-z]+\.gif)"} \
           $x all name image]} {
      #puts "DIAGRAM: $file $name $image"
      set req $name
      regsub {^(\.\./)+} $image {} img2
      set rno R-[md5file-10x8 doc/$img2]
      set shortrno [string range $rno 0 12]
      append out "<a name=\"$rno\"></a><font color=\"blue\"><b>"
      set link "<a href=\"$matrixpath#$rno\" style=\"color: #0000ff\">"
      append out "$link$shortrno</a>:\[</b></font>\n"
      if {$proof($rno)>=2} {
        set clr green
      } elseif {$proof($rno)==1} {

Changes to pages/syntax.in.

26
27
28
29
30
31
32

33

34
35
36
37
38
39
40
  file mkdir $::DEST/syntax
  hd_open_aux syntax/$name.html
  hd_enable_main 0
  hd_header "SQLite Syntax: $name"
  hd_keywords $name "$name syntax diagram"
  hd_putsnl "<h1 align='center'>$name</h1>"
  hd_putsnl "<blockquote>"

  hd_putsnl "<img src='../images/syntax/$name.gif'></img><br>"

  foreach {cx px} $syntax_linkage($name) break
  if {[llength $px]>0} {
    hd_puts "\nUsed by:"
    foreach c $px {
      hd_puts "&nbsp;&nbsp; <a href='./$c.html'>$c</a>"
    }
  }







>
|
>







26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
  file mkdir $::DEST/syntax
  hd_open_aux syntax/$name.html
  hd_enable_main 0
  hd_header "SQLite Syntax: $name"
  hd_keywords $name "$name syntax diagram"
  hd_putsnl "<h1 align='center'>$name</h1>"
  hd_putsnl "<blockquote>"
  hd_puts "<img alt=\"syntax diagram $name\" "
  hd_puts "src=\"../images/syntax/$name.gif\">"
  hd_putsnl "</img><br>"
  foreach {cx px} $syntax_linkage($name) break
  if {[llength $px]>0} {
    hd_puts "\nUsed by:"
    foreach c $px {
      hd_puts "&nbsp;&nbsp; <a href='./$c.html'>$c</a>"
    }
  }

Changes to schema.tcl.

56
57
58
59
60
61
62
63
64
65
66
67
68
69
70




71







72
73
74
75
76
77
78
  
  /* Requirements or Testable Statements Of Truth (Tsots).
  ** These are extracts from the documentation that define what
  ** the product does and how it performs.
  */
  CREATE TABLE IF NOT EXISTS requirement(
    rid INTEGER PRIMARY KEY, -- Requirement ID for internal use only
    reqno TEXT,              -- Ex: R-12345-67890-...
    reqimage BOOLEAN,        -- True for an image requirement
    reqtext TEXT,            -- Normalized text of requirement or image filename
    origtext TEXT,           -- Original, unnormalized text
    srcfile TEXT,            -- Document from which extracted
    srcseq INTEGER,          -- Sequence within the same document
    UNIQUE(srcfile,srcseq)
  );




  CREATE INDEX IF NOT EXISTS reqno ON requirement(reqno);







  
  /* Evidence of fulfillment of a requirement is recorded in this
  ** table.
  */
  CREATE TABLE IF NOT EXISTS evidence(
    reqno TEXT,              -- Prefix of a requirement number
    reqtext TEXT,            -- Normalized requirement text taken from source







|



|



>
>
>
>
|
>
>
>
>
>
>
>







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
  
  /* Requirements or Testable Statements Of Truth (Tsots).
  ** These are extracts from the documentation that define what
  ** the product does and how it performs.
  */
  CREATE TABLE IF NOT EXISTS requirement(
    rid INTEGER PRIMARY KEY, -- Requirement ID for internal use only
    reqno TEXT UNIQUE,       -- Ex: R-12345-67890-...
    reqimage BOOLEAN,        -- True for an image requirement
    reqtext TEXT,            -- Normalized text of requirement or image filename
    origtext TEXT,           -- Original, unnormalized text
    srcfile TEXT,            -- Document from which first extracted
    srcseq INTEGER,          -- Sequence within the same document
    UNIQUE(srcfile,srcseq)
  );

  /* The source text for a requirement.  Some requirements (especially
  ** syntax diagram images) can occur in multiple places.
  */
  CREATE TABLE IF NOT EXISTS reqsrc(
    srcfile TEXT,            -- Document from which extracted
    srcseq INTEGER,          -- Sequence within the same document
    reqno TEXT,              -- The requirement that is repeated
    PRIMARY KEY(srcfile,srcseq)
  ) WITHOUT ROWID;

  /* Image requirements can appears at multiple places in the
  
  /* Evidence of fulfillment of a requirement is recorded in this
  ** table.
  */
  CREATE TABLE IF NOT EXISTS evidence(
    reqno TEXT,              -- Prefix of a requirement number
    reqtext TEXT,            -- Normalized requirement text taken from source

Changes to wrap.tcl.

617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
      "<button id='$a' onclick='hideorshow(\"$a\",\"$b\")'>hide</button></p>\n\
       <blockquote id='$b'>\n\
       <img $alt src=\"$hd(rootpath-$class)images/syntax/$name.gif\" />"
  } else {
    puts $hd($class) \
      "<button id='$a' onclick='hideorshow(\"$a\",\"$b\")'>show</button></p>\n\
       <blockquote id='$b' style='display:none;'>\n\
       <img $alt data-noreq src=\"$hd(rootpath-$class)images/syntax/$name.gif\" />"
  }
  if {[info exists syntax_linkage($name)]} {
    foreach {cx px} $syntax_linkage($name) break
    foreach c $cx {
      if {[lsearch $exclude $c]>=0} continue
      RecursiveBubbleDiagram_helper $class $c $open2 [concat $exclude $cx]
    }  







|







617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
      "<button id='$a' onclick='hideorshow(\"$a\",\"$b\")'>hide</button></p>\n\
       <blockquote id='$b'>\n\
       <img $alt src=\"$hd(rootpath-$class)images/syntax/$name.gif\" />"
  } else {
    puts $hd($class) \
      "<button id='$a' onclick='hideorshow(\"$a\",\"$b\")'>show</button></p>\n\
       <blockquote id='$b' style='display:none;'>\n\
       <img $alt src=\"$hd(rootpath-$class)images/syntax/$name.gif\" />"
  }
  if {[info exists syntax_linkage($name)]} {
    foreach {cx px} $syntax_linkage($name) break
    foreach c $cx {
      if {[lsearch $exclude $c]>=0} continue
      RecursiveBubbleDiagram_helper $class $c $open2 [concat $exclude $cx]
    }