Documentation Source Text

Check-in [dbc14b00bf]
Login

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

Overview
Comment:Tinkering with the C/C++ documentation generator so that it extracts requirements from the sqlite.h.in file.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: dbc14b00bf62fe12856ad5d993cb2271db394c13
User & Date: drh 2007-12-05 18:03:35
Context
2007-12-06
02:41
Continuing work on the C/C++ interface requirements. check-in: 2111eeb610 user: drh tags: trunk
2007-12-05
18:03
Tinkering with the C/C++ documentation generator so that it extracts requirements from the sqlite.h.in file. check-in: dbc14b00bf user: drh tags: trunk
2007-12-02
12:57
Add the "See Also" sidebar on the About page. The "features" link goes to the Features page, not to the About page. check-in: 53144a576e user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Show Whitespace Changes Patch

Changes to pages/capi3ref.in.

44
45
46
47
48
49
50

51
52
53
54
55
56
57
...
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
...
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
  } elseif {$phase==2} {
    if {$line==""} {
      set kwlist [lsort [array names keyword]]
      unset -nocomplain keyword
      set key $type:$kwlist
      regsub { *\{[\w.]+\}} $title {} title
      regsub -all { *\{[\w.]+\}} $body {} body

      lappend content [list $key $title $type $kwlist $body $code]
      set title {}
      set keywords {}
      set type {}
      set body {}
      set code {}
      set phase 0
................................................................................
  foreach k $keywords {
    puts "<a name=\"$k\"></a></a>"
  }
  puts "<h2>$title</h2>"
  puts "<blockquote><pre>"
  puts "$code"
  puts "</pre></blockquote>"
  regsub -all "\n\n+" $body {</p>\1<p>} body
  regsub -all {\[} <p>$body</p> {[resolve_links } body
  set body [subst -novar -noback $body]
  puts "$body"
  puts "<hr>"
  set fkey [lindex $keywords 0]
  if {![info exists keyword_to_file($fkey)]} {
    real_puts fkey=$fkey
................................................................................
    exit
  }
  c3ref_open_file $::keyword_to_file($fkey) $title
  puts "<blockquote><pre>"
  puts "$code"
  puts "</pre></blockquote>"
  set body [lindex $c 4]
  regsub -all "\n\n+" $body {</p>\1<p>} body
  regsub -all {\[} <p>$body</p> {[resolve_m_links } body
  set body [subst -novar -noback $body]
  puts "$body"
  puts {<p>See also lists of
  <a href="objlist.html">Objects</a>,
  <a href="constlist.html">Constants</a>, and
  <a href="funclist.html">Functions</a>.</p>}
  c3ref_close_file
}
</tcl>







>







 







|







 







|










44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
...
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
...
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
  } elseif {$phase==2} {
    if {$line==""} {
      set kwlist [lsort [array names keyword]]
      unset -nocomplain keyword
      set key $type:$kwlist
      regsub { *\{[\w.]+\}} $title {} title
      regsub -all { *\{[\w.]+\}} $body {} body
      set code [string map {& &amp; < &lt; > &gt;} $code]
      lappend content [list $key $title $type $kwlist $body $code]
      set title {}
      set keywords {}
      set type {}
      set body {}
      set code {}
      set phase 0
................................................................................
  foreach k $keywords {
    puts "<a name=\"$k\"></a></a>"
  }
  puts "<h2>$title</h2>"
  puts "<blockquote><pre>"
  puts "$code"
  puts "</pre></blockquote>"
  regsub -all "\n\n+" $body "</p>\n\n<p>" body
  regsub -all {\[} <p>$body</p> {[resolve_links } body
  set body [subst -novar -noback $body]
  puts "$body"
  puts "<hr>"
  set fkey [lindex $keywords 0]
  if {![info exists keyword_to_file($fkey)]} {
    real_puts fkey=$fkey
................................................................................
    exit
  }
  c3ref_open_file $::keyword_to_file($fkey) $title
  puts "<blockquote><pre>"
  puts "$code"
  puts "</pre></blockquote>"
  set body [lindex $c 4]
  regsub -all "\n\n+" $body "</p>\n\n<p>" body
  regsub -all {\[} <p>$body</p> {[resolve_m_links } body
  set body [subst -novar -noback $body]
  puts "$body"
  puts {<p>See also lists of
  <a href="objlist.html">Objects</a>,
  <a href="constlist.html">Constants</a>, and
  <a href="funclist.html">Functions</a>.</p>}
  c3ref_close_file
}
</tcl>

Changes to pages/requirements.in.

43
44
45
46
47
48
49















50
51
52
53
54
55
56
..
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
126
127
128
129
...
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
    set x3 [expr {$back+1}]
    set tail [string range $in $x3 end]
    return 1
  } else {
    return 0
  }
}
















# Read sqlite3.h line by line and extract interface definition
# information.
#
while {![eof $in]} {
  set line [gets $in]
  incr lineno
................................................................................
      }
    } elseif {[string range $line 0 1]=="*/"} {
      set phase 2
    }
  } elseif {$phase==2} {
    if {$line==""} {
      set kwlist [lsort [array names keyword]]

      unset -nocomplain keyword
      set key $type:$kwlist
      if {[regexp {\{([\w.]+)\}} $title all tag]} {
        regsub { *\{[\w.]+\}} $title {} title
        if {$dcnt>1} {set d declarations} {set d {a declaration}}

        set req "The \"sqlite3.h\" header file\
            shall contain $d equivalent to the following:\
            \n<blockquote><pre>\n$code</pre></blockquote>"
        regexp {\d+} $tag key
        lappend reqlist [list $key $tag sqlite3.h $title_lineno $req {}]
      }
      set x $body
      while {[split_text $x prefix tag suffix]} {
        if {![split_text $suffix req endtag tail]} {
          set req $suffix
          set x {}
          set ex {}
        } elseif {$endtag=="END"} {
          set ex {}
          set x $tail
        } elseif {$endtag=="EX"} {
          if {![split_text $tail ex end2 tail2]} {
            set ex $tail
            set x {}
          } elseif {$end2=="END"} {
            set x $tail2
          } else {
            set x "{$end2} $tail2"
          }
        } else {
          set ex {}
          set x "{$endtag} $tail"
        }
        regsub -all {\[([^]|]+\|)?([^]]+)\]} $req {\2} req
        regsub -all {\s+} $req { } req
        set req [string trim $req]
        regsub -all {\[([^]|]+\|)?([^]]+)\]} $ex {\2} ex
        regsub -all {\s+} $ex { } ex
        set ex [string trim $ex]
        regexp {\d+} $tag key
        lappend reqlist [list $key $tag sqlite3.h $title_lineno $req $ex]
      }
      set title {}
      set keywords {}
      set type {}
      set body {}
      set code {}
      set phase 0
................................................................................
      }
      append code $line\n
    }
  }
}

foreach req [lsort -index 0 $reqlist] {
  foreach {key tag file lineno text ex} $req break
  puts "<tr><td valign=\"top\">$tag</td>"
  puts "<td valign=\"top\"><b>$text</b>"
  if {$ex!=""} {
    puts "<p>$ex</p>"
  }
  puts "</td></tr>"
}
</tcl>

</table>







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







 







>





>




|






<

<

<
<
<
<
<
<
|
<
<
<
<



|

<
<
<

|







 







|
|
|
<
<
<
<




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
..
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
126
127
128
129
130
131
...
150
151
152
153
154
155
156
157
158
159




160
161
162
163
    set x3 [expr {$back+1}]
    set tail [string range $in $x3 end]
    return 1
  } else {
    return 0
  }
}

# Convert a tag name into the filename used for the
# multi-file version.
#
# Constants begin with SQLITE_.  The names are converted
# to lower case and prefixed with "c_".  If we did not
# do this, then the names "SQLITE_BLOB" and "sqlite3_blob"
# would collide.
#
proc convert_tag_name {oldname} {
  set oldname [string tolower $oldname]
  regsub {^sqlite_} $oldname {c_} oldname
  regsub {^sqlite3_} $oldname {} name
  return $name.html
}

# Read sqlite3.h line by line and extract interface definition
# information.
#
while {![eof $in]} {
  set line [gets $in]
  incr lineno
................................................................................
      }
    } elseif {[string range $line 0 1]=="*/"} {
      set phase 2
    }
  } elseif {$phase==2} {
    if {$line==""} {
      set kwlist [lsort [array names keyword]]
      set docfile [convert_tag_name [lindex $kwlist 0]]
      unset -nocomplain keyword
      set key $type:$kwlist
      if {[regexp {\{([\w.]+)\}} $title all tag]} {
        regsub { *\{[\w.]+\}} $title {} title
        if {$dcnt>1} {set d declarations} {set d {a declaration}}
        set code [string map {& &amp; < &lt; > &gt;} $code]
        set req "The \"sqlite3.h\" header file\
            shall contain $d equivalent to the following:\
            \n<blockquote><pre>\n$code</pre></blockquote>"
        regexp {\d+} $tag key
        lappend reqlist [list $key $tag sqlite3.h $title_lineno $req $docfile]
      }
      set x $body
      while {[split_text $x prefix tag suffix]} {
        if {![split_text $suffix req endtag tail]} {
          set req $suffix
          set x {}

        } elseif {$endtag=="END"} {

          set x $tail






        } else {




          set x "{$endtag} $tail"
        }
        regsub -all {\[([^]|]+\|)?([^]]+)\]} $req {\2} req
        #regsub -all {\s+} $req { } req
        set req [string trim $req]



        regexp {\d+} $tag key
        lappend reqlist [list $key $tag sqlite3.h $title_lineno $req $docfile]
      }
      set title {}
      set keywords {}
      set type {}
      set body {}
      set code {}
      set phase 0
................................................................................
      }
      append code $line\n
    }
  }
}

foreach req [lsort -index 0 $reqlist] {
  foreach {key tag file lineno text docfile} $req break
  puts "<tr><td valign=\"top\"><a href=\"c3ref/$docfile\">$tag</a></td>"
  puts "<td valign=\"top\">$text</td></tr>"




}
</tcl>

</table>