Documentation Source Text

Check-in [ae0c38c662]
Login

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: ae0c38c66299089a0bee3dec5fca6ee3bf910f77
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
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

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.

    45     45         set body {}
    46     46         set code {}
    47     47         set phase 0
    48     48       } else {
    49     49         if {[regexp {^#define (SQLITE_[A-Z0-9_]+)} $line all kx]} {
    50     50           set type constant
    51     51           set keyword($kx) 1
    52         -      } elseif {[regexp {^typedef .* (sqlite[0-9a-z_]+);} $line all kx]} {
           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  +        set keyword($kx) 1
           58  +      } elseif {[regexp {^SQLITE_EXTERN .*(sqlite[0-9a-z_]+);} $line all kx]} {
           59  +        set type datatype
    57     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   }