Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
| Comment: | Generate C interface reference document both as the single big file and also as lots of individual small files. |
|---|---|
| Timelines: | family | ancestors | descendants | both | trunk |
| Files: | files | file ages | folders |
| SHA1: |
ae0c38c66299089a0bee3dec5fca6ee3 |
| User & Date: | drh 2007-11-12 20:38:33 |
Context
|
2007-11-13
| ||
| 01:24 | Cleaned up the famous users webpage. Work on the about page. check-in: 8a34ae6a2f user: drh tags: trunk | |
|
2007-11-12
| ||
| 20:38 | Generate C interface reference document both as the single big file and also as lots of individual small files. check-in: ae0c38c662 user: drh tags: trunk | |
| 15:32 | Complete reorganization of the documentation sources. check-in: 275febef8f user: drh tags: trunk | |
Changes
Changes to main.mk.
33 33 34 34 capi3ref.html: $(DOC)/mkapidoc.tcl sqlite3.h 35 35 tclsh $(DOC)/mkapidoc.tcl <sqlite3.h >capi3ref.html 36 36 37 37 docdir: 38 38 mkdir -p doc 39 39 40 -doc: docdir always 40 +doc: sqlite3.h docdir always 41 41 rm -rf doc/images 42 42 cp -r $(DOC)/images doc 43 43 cp $(DOC)/rawpages/* doc 44 44 tclsh $(DOC)/wrap.tcl $(DOC) $(SRC) doc $(DOC)/pages/*.in 45 45 46 46 always: 47 47 48 48 49 49 clean: 50 50 rm -f doc sqlite3.h
Changes to pages/capi3ref.in.
51 51 set keyword($kx) 1 52 52 } elseif {[regexp {^typedef .* (sqlite[0-9a-z_]+);} $line all kx]} { 53 53 set type datatype 54 54 set keyword($kx) 1 55 55 } elseif {[regexp {^[a-z].*[ *](sqlite3_[a-z0-9_]+)\(} $line all kx]} { 56 56 set type function 57 57 set keyword($kx) 1 58 + } elseif {[regexp {^SQLITE_EXTERN .*(sqlite[0-9a-z_]+);} $line all kx]} { 59 + set type datatype 60 + set keyword($kx) 1 58 61 } 59 62 append code $line\n 60 63 } 61 64 } 62 65 } 63 66 67 + 68 +# Convert a tag name into the filename used for the 69 +# multi-file version. 70 +# 71 +proc convert_tag_name {oldname} { 72 + regsub -nocase {^sqlite3?_} $oldname {} name 73 + return $name.html 74 +} 75 + 76 +# Compute a mapping from keywords to filenames. 77 +# 78 +unset -nocomplain keyword_to_file 79 +foreach c [lsort $content] { 80 + foreach {key title type keywords body code} $c break 81 + set file [convert_tag_name [lindex $keywords 0]] 82 + foreach k $keywords { 83 + set keyword_to_file($k) $file 84 + } 85 +} 86 + 64 87 # Output HTML that displays the given list in N columns 65 88 # 66 -proc output_list {N lx} { 89 +proc output_list {N lx multi} { 90 + global keyword_to_file 67 91 puts {<table width="100%" cellpadding="5"><tr>} 68 92 set len [llength $lx] 69 93 set n [expr {($len + $N - 1)/$N}] 70 94 for {set i 0} {$i<$N} {incr i} { 71 95 set start [expr {$i*$n}] 72 96 set end [expr {($i+1)*$n}] 73 97 puts {<td valign="top"><ul>} 74 98 for {set j $start} {$j<$end} {incr j} { 75 99 set entry [lindex $lx $j] 76 100 if {$entry!=""} { 77 101 foreach {link label} $entry break 78 - puts "<li><a href=\"#$link\">$label</a></li>" 102 + if {$multi} { 103 + set link $keyword_to_file($link) 104 + } else { 105 + set link "#link" 106 + } 107 + puts "<li><a href=\"$link\">$label</a></li>" 79 108 } 80 109 } 81 110 puts {</ul></td>} 82 111 } 83 112 puts {</tr></table>} 84 113 } 114 + 115 +# Open a separate output file for a single interface 116 +# 117 +proc c3ref_open_file {filename title} { 118 + global DEST OUT save_OUT 119 + file mkdir $DEST/c3ref 120 + set save_OUT $OUT 121 + set OUT [open $DEST/c3ref/$filename w] 122 + PutsHeader "SQLite C Interface: $title" ../ 123 + puts {<a href="intro.html"><h2>SQLite C Interface</h2></a>} 124 + puts "<h3>$title</h3>" 125 +} 126 +proc c3ref_close_file {} { 127 + global HOMEDIR OUT save_OUT 128 + PutsFooter $HOMEDIR/sqlite3.h 129 + close $OUT 130 + set OUT $save_OUT 131 +} 132 + 133 +c3ref_open_file intro.html Introduction 134 +</tcl> 135 + 136 +<p>These pages defined the C-language interface to SQLite. 137 +These pages are intended as a reference to what SQLite 138 +is suppose to do. This is not a tutorial. These 139 +pages are designed to be precise, not easy to read.</p> 140 + 141 +<p>This version of the C-language interface reference is 142 +broken down into small pages for easy viewing. The 143 +same content is also available as a 144 +<a href="../capi3ref.html">single large HTML file</a> 145 +for those who prefer that format.</p> 146 + 147 +<p>The content on these pages is extracted from comments 148 +in the source code.</p> 149 + 150 +<p>The interface is broken down into three catagories:</p> 151 + 152 +<ol> 153 +<li><p><a href="objlist.html"><b>List Of Objects.</b></a> 154 + All abstract objects and datatypes used by the 155 + SQLite library. There are a handful of objects, but 156 + only three which most users need to be aware of: 157 + A database connection object 158 + <a href="sqlite3.html">sqlite3</a>, a prepared statement 159 + object <a href="stmt.html">sqlite3_stmt</a>, and the 64-bit integer 160 + type <a href="int64.html">sqlite3_int64</a>.</p></li> 161 + 162 +<li><p><a href="constlist.html"><b>List Of Constants.</b></a> 163 + Numeric constants just by SQLite and represented by 164 + #defines in the sqlite3.h header file. These constants 165 + are things such as numeric return parameters from 166 + various interfaces (ex: 167 + <a href="ABORT.html">SQLITE_OK</a>) or flags passed 168 + into functions to control behavior 169 + (ex: <a href="OPEN_CREATE.html">SQLITE_OPEN_READONLY</a>).</p></li> 170 + 171 +<li><p><a href="funclist.html"><b>List Of Functions.</b></a> 172 + Functions and/or methods operating on the 173 + <a href="objlist.html">objects</a> and using and/or 174 + returning <a href="constlist.html">constants</a>. There 175 + are many function, but most applications only use a handful. 176 + </p></li> 177 +</ol> 178 + 179 +<tcl> 180 +c3ref_close_file 181 + 182 +</tcl> 183 + 184 +<p>This page defined the C-language interface to SQLite. 185 +This page is intended as a reference to what SQLite 186 +is suppose to do. This is not a tutorial. This 187 +page is designed to be precise, not easy to read.</p> 188 + 189 +<p>This page contains all C-language interface information 190 +in a single HTML file. The same information is also 191 +available broken out into 192 +<a href="c3ref/intro.html">lots of small pages</a> 193 +for easier viewing, if you prefer.</p> 194 + 195 +<p>The content on this document is extracted from comments 196 +in the source code.</p> 197 + 198 +<hr> 199 + 200 +<tcl> 85 201 86 202 # Do a table of contents for objects 87 203 # 88 204 set objlist {} 89 205 foreach c $content { 90 206 foreach {key title type keywords body code} $c break 91 207 if {$type!="datatype"} continue 92 208 set keywords [lsort $keywords] 93 209 set k [lindex $keywords 0] 94 210 foreach kw $keywords { 95 211 lappend objlist [list $k $kw] 96 212 } 97 213 } 98 -puts {<h2>Datatypes:</h2>} 99 -output_list 3 $objlist 214 +puts {<h2>Objects:</h2>} 215 +output_list 3 $objlist 0 100 216 puts {<hr>} 217 +c3ref_open_file objlist.html Objects 218 +output_list 3 $objlist 1 219 +puts {<p>Other lists: 220 +<a href="constlist.html">Constants</a> and 221 +<a href="funclist.html">Functions</a>.} 222 +c3ref_close_file 101 223 102 224 # Do a table of contents for constants 103 225 # 104 226 set clist {} 105 227 foreach c $content { 106 228 foreach {key title type keywords body code} $c break 107 229 if {$type!="constant"} continue ................................................................................ 109 231 set k [lindex $keywords 0] 110 232 foreach kw $keywords { 111 233 lappend clist [list $k $kw] 112 234 } 113 235 } 114 236 puts {<h2>Constants:</h2>} 115 237 set clist [lsort -index 1 $clist] 116 -output_list 3 $clist 238 +output_list 2 $clist 0 117 239 puts {<hr>} 240 +c3ref_open_file constlist.html Constants 241 +output_list 2 $clist 1 242 +puts {<p>Other lists: 243 +<a href="objlist.html">Objects</a> and 244 +<a href="funclist.html">Functions</a>.</p>} 245 +c3ref_close_file 118 246 119 247 120 248 # Do a table of contents for functions 121 249 # 122 250 set funclist {} 123 251 foreach c $content { 124 252 foreach {key title type keywords body code} $c break ................................................................................ 127 255 set k [lindex $keywords 0] 128 256 foreach kw $keywords { 129 257 lappend funclist [list $k $kw] 130 258 } 131 259 } 132 260 puts {<h2>Functions:</h2>} 133 261 set funclist [lsort -index 1 $funclist] 134 -output_list 3 $funclist 262 +output_list 3 $funclist 0 135 263 puts {<hr>} 264 +c3ref_open_file funclist.html Functions 265 +output_list 3 $funclist 1 266 +puts {<p>Other lists: 267 +<a href="constlist.html">Constants</a> and 268 +<a href="objlist.html">Objects</a>.</p>} 269 +c3ref_close_file 270 + 136 271 137 -# Resolve links 272 +# Resolve links to anchors in the single-file spec. 138 273 # 139 274 proc resolve_links {args} { 140 275 set tag [lindex $args 0] 141 276 regsub -all {[^a-zA-Z0-9_]} $tag {} tag 142 277 set x "<a href=\"#$tag\">" 143 278 if {[llength $args]>2} { 144 279 append x [lrange $args 2 end]</a> 145 280 } else { 146 281 append x [lindex $args 0]</a> 147 282 } 148 283 return $x 149 284 } 285 + 286 +# Resolve links to anchors in the multi-file spec. 287 +# 288 +proc resolve_m_links {args} { 289 + set tag [lindex $args 0] 290 + regsub -all {[^a-zA-Z0-9_]} $tag {} tag 291 + global keyword_to_file 292 + if {[info exists keyword_to_file($tag)]} { 293 + set tag $keyword_to_file($tag) 294 + set begin "<a href=\"$tag\">" 295 + set end "</a>" 296 + } else { 297 + set begin "" 298 + set end "" 299 + } 300 + if {[llength $args]>2} { 301 + append x $begin[lrange $args 2 end]$end 302 + } else { 303 + append x $begin[lindex $args 0]$end 304 + } 305 + return $x 306 +} 150 307 151 308 # Output all the records 152 309 # 153 310 foreach c [lsort $content] { 154 311 foreach {key title type keywords body code} $c break 155 312 foreach k $keywords { 156 313 puts "<a name=\"$k\"></a></a>" ................................................................................ 160 317 puts "$code" 161 318 puts "</pre></blockquote>" 162 319 regsub -all "\n\n+" $body {</p>\1<p>} body 163 320 regsub -all {\[} <p>$body</p> {[resolve_links } body 164 321 set body [subst -novar -noback $body] 165 322 puts "$body" 166 323 puts "<hr>" 324 + set fkey [lindex $keywords 0] 325 + if {![info exists keyword_to_file($fkey)]} { 326 + real_puts fkey=$fkey 327 + real_puts c=$c 328 + exit 329 + } 330 + c3ref_open_file $::keyword_to_file($fkey) $title 331 + puts "<blockquote><pre>" 332 + puts "$code" 333 + puts "</pre></blockquote>" 334 + set body [lindex $c 4] 335 + regsub -all "\n\n+" $body {</p>\1<p>} body 336 + regsub -all {\[} <p>$body</p> {[resolve_m_links } body 337 + set body [subst -novar -noback $body] 338 + puts "$body" 339 + puts {<p>See also lists of 340 + <a href="objlist.html">Objects</a>, 341 + <a href="constlist.html">Constants</a>, and 342 + <a href="funclist.html">Functions</a>.</p>} 343 + c3ref_close_file 167 344 } 168 345 </tcl>
Changes to wrap.tcl.
26 26 set DEST [lindex $argv 2] 27 27 set HOMEDIR [pwd] 28 28 rename puts real_puts 29 29 proc puts {text} { 30 30 real_puts $::OUT $text 31 31 flush $::OUT 32 32 } 33 +proc putsin4 {text} { 34 + regsub -all "\n " $text \n text 35 + real_puts $::OUT [uplevel 1 [list subst -noback -nocom $text]] 36 + flush $::OUT 37 +} 38 +proc PutsHeader {title {relpath {}}} { 39 + puts {<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">} 40 + puts {<html><head>} 41 + puts "<title>$title</title>" 42 + putsin4 {<style type="text/css"> 43 + body { 44 + max-width: 800px; /* not supported in IE 6 */ 45 + margin: auto; 46 + font-family: "Verdana" "sans-serif"; 47 + padding: 8px 1%; 48 + } 49 + 50 + a { color: #4F7263 } 51 + a:visited { color: #80a796 } 52 + 53 + .logo { position:absolute; margin:3px; } 54 + .tagline { 55 + float:right; 56 + text-align:right; 57 + font-style:italic; 58 + width:240px; 59 + margin:12px; 60 + margin-top:58px; 61 + } 62 + 63 + .toolbar { 64 + background-color: #80a796; 65 + position: relative; 66 + font-variant: small-caps; 67 + clear: both; 68 + text-align: center; 69 + line-height: 1.6em; 70 + margin-bottom: 5px; 71 + padding:1px 8px; 72 + height:1%; /* IE hack to fix rounded corner positions */ 73 + } 74 + .toolbar a { color: white; text-decoration: none; padding: 6px 4px; } 75 + .toolbar a:visited { color: white; } 76 + .toolbar a:hover { color: #80a796; background: white; } 77 + 78 + .content { margin: 5%; } 79 + .content dt { font-weight:bold; } 80 + .content dd { margin-bottom: 25px; margin-left:20%; } 81 + .content ul { padding:0px; padding-left: 15px; margin:0px; } 82 + 83 + /* rounded corners */ 84 + .se,.ne,.nw,.sw { position: absolute; width:8px; height:8px; 85 + font-size:7px; /* IE hack to ensure height=8px */ } 86 + .se { background-image: url(${relpath}se.png); bottom: 0px; right: 0px; } 87 + .ne { background-image: url(${relpath}ne.png); top: 0px; right: 0px; } 88 + .sw { background-image: url(${relpath}sw.png); bottom: 0px; left: 0px; } 89 + .nw { background-image: url(${relpath}nw.png); top: 0px; left: 0px; } 90 + </style> 91 + <meta http-equiv="content-type" content="text/html; charset=UTF-8"> 92 + } 93 + puts {</head>} 94 + putsin4 {<body> 95 + <div><!-- container div to satisfy validator --> 96 + 97 + <img class="logo" src="${relpath}SQLite.gif" alt="SQLite Logo"> 98 + <div><!-- IE hack to prevent disappearing logo--></div> 99 + <div class="tagline">The World's Most Used SQL Database.</div> 100 + 101 + <div class="toolbar"> 102 + <a href="${relpath}index.html">Home</a> 103 + <a href="${relpath}about.html">About</a> 104 + <a href="${relpath}docs.html">Documentation</a> 105 + <a href="${relpath}download.html">Download</a> 106 + <a href="${relpath}copyright.html">License</a> 107 + <a href="${relpath}press.html">Advocacy</a> 108 + <a href="${relpath}devhome.html">Developers</a> 109 + <a href="${relpath}news.html">News</a> 110 + <a href="${relpath}support.html">Support</a> 111 + <!-- rounded corners --> 112 + <div class="ne"></div><div class="se"></div><div class="nw"> 113 + </div><div class="sw"></div> 114 + </div> 115 + } 116 +} 117 +proc PutsFooter {srcfile} { 118 + puts {<hr><small><i>} 119 + set mtime [file mtime $srcfile] 120 + set date [clock format $mtime -format {%Y/%m/%d %H:%M:%S UTC} -gmt 1] 121 + puts "This page last modified $date" 122 + puts {</i></small></div></body></html>} 123 +} 33 124 34 125 # The following proc is used to ensure consistent formatting in the 35 126 # HTML generated by lang.tcl and pragma.tcl. 36 127 # 37 128 proc Syntax {args} { 38 129 puts {<table cellpadding="10" class=pdf_syntax>} 39 130 foreach {rule body} $args { ................................................................................ 67 158 set in [read $fd] 68 159 close $fd 69 160 set title {No Title} 70 161 regexp {<title>([^\n]*)</title>} $in all title 71 162 regsub {<title>[^\n]*</title>} $in {} in 72 163 set outfile [file root [file tail $infile]].html 73 164 set ::OUT [open $::DEST/$outfile w] 74 - puts {<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">} 75 - puts {<html><head>} 76 - puts "<title>$title</title>" 77 - puts {<style type="text/css"> 78 - body { 79 - max-width: 800px; /* not supported in IE 6 */ 80 - margin: auto; 81 - font-family: "Verdana" "sans-serif"; 82 - padding: 8px 1%; 83 - } 84 - 85 - a { color: #4F7263 } 86 - a:visited { color: #80a796 } 87 - 88 - .logo { position:absolute; margin:3px; } 89 - .tagline { 90 - float:right; 91 - text-align:right; 92 - font-style:italic; 93 - width:240px; 94 - margin:12px; 95 - margin-top:58px; 96 - } 97 - 98 - .toolbar { 99 - background-color: #80a796; 100 - position: relative; 101 - font-variant: small-caps; 102 - clear: both; 103 - text-align: center; 104 - line-height: 1.6em; 105 - margin-bottom: 50px; 106 - padding:1px 8px; 107 - height:1%; /* IE hack to fix rounded corner positions */ 108 - } 109 - .toolbar a { color: white; text-decoration: none; padding: 6px 4px; } 110 - .toolbar a:visited { color: white; } 111 - .toolbar a:hover { color: #80a796; background: white; } 112 - 113 - .content { margin: 5%; } 114 - .content dt { font-weight:bold; } 115 - .content dd { margin-bottom: 25px; margin-left:20%; } 116 - .content ul { padding:0px; padding-left: 15px; margin:0px; } 117 - 118 - /* rounded corners */ 119 - .se,.ne,.nw,.sw { position: absolute; width:8px; height:8px; 120 - font-size:7px; /* IE hack to ensure height=8px */ } 121 - .se { background-image: url(se.png); bottom: 0px; right: 0px; } 122 - .ne { background-image: url(ne.png); top: 0px; right: 0px; } 123 - .sw { background-image: url(sw.png); bottom: 0px; left: 0px; } 124 - .nw { background-image: url(nw.png); top: 0px; left: 0px; } 125 - </style> 126 - <meta http-equiv="content-type" content="text/html; charset=UTF-8"> 127 - } 128 - puts {</head>} 129 - puts {<body> 130 - <div><!-- container div to satisfy validator --> 131 - 132 - <img class="logo" src="http://www.sqlite.org/SQLite.gif" alt="SQLite Logo"> 133 - <div><!-- IE hack to prevent disappearing logo--></div> 134 - <div class="tagline">The World's Most Used SQL Database.</div> 135 - 136 - <div class="toolbar"> 137 - <a href="index.html">Home</a> 138 - <a href="about.html">About</a> 139 - <a href="docs.html">Documentation</a> 140 - <a href="download.html">Download</a> 141 - <a href="copyright.html">License</a> 142 - <a href="press.html">Advocacy</a> 143 - <a href="devhome.html">Developers</a> 144 - <a href="news.html">News</a> 145 - <a href="support.html">Support</a> 146 - <!-- rounded corners --> 147 - <div class="ne"></div><div class="se"></div><div class="nw"></div><div class="sw"></div> 148 - </div> 149 - } 165 + PutsHeader $title 150 166 regsub -all {<tcl>} $in "\175; eval \173" in 151 167 regsub -all {</tcl>} $in "\175; puts \173" in 152 168 eval "puts \173$in\175" 153 169 cd $::HOMEDIR 154 - puts {<hr><small><i>} 155 - set mtime [file mtime $infile] 156 - set date [clock format $mtime -format {%Y/%m/%d %H:%M:%S UTC} -gmt 1] 157 - puts "This page last modified $date" 158 - puts {</i></small></div></body></html>} 170 + PutsFooter $infile 159 171 close $::OUT 160 172 }