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.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: dbc14b00bf62fe12856ad5d993cb2271db394c13
User & Date: drh 2007-12-05 18:03:35.000
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
Unified Diff Ignore Whitespace Patch
Changes to pages/capi3ref.in.
44
45
46
47
48
49
50

51
52
53
54
55
56
57
  } 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







>







44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
  } 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
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
  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
    real_puts c=$c
    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>







|















|










338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
  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
    real_puts c=$c
    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
    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







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







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
    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
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
      }
    } 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







>





>




|






<

<

<
<
<
<
<
<
|
<
<
<
<



|

<
<
<

|







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
      }
    } 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
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
      }
      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>







|
|
|
<
<
<
<




150
151
152
153
154
155
156
157
158
159




160
161
162
163
      }
      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>