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

Changes to pages/capi3ref.in.

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

Changes to pages/requirements.in.

    43     43       set x3 [expr {$back+1}]
    44     44       set tail [string range $in $x3 end]
    45     45       return 1
    46     46     } else {
    47     47       return 0
    48     48     }
    49     49   }
           50  +
           51  +# Convert a tag name into the filename used for the
           52  +# multi-file version.
           53  +#
           54  +# Constants begin with SQLITE_.  The names are converted
           55  +# to lower case and prefixed with "c_".  If we did not
           56  +# do this, then the names "SQLITE_BLOB" and "sqlite3_blob"
           57  +# would collide.
           58  +#
           59  +proc convert_tag_name {oldname} {
           60  +  set oldname [string tolower $oldname]
           61  +  regsub {^sqlite_} $oldname {c_} oldname
           62  +  regsub {^sqlite3_} $oldname {} name
           63  +  return $name.html
           64  +}
    50     65   
    51     66   # Read sqlite3.h line by line and extract interface definition
    52     67   # information.
    53     68   #
    54     69   while {![eof $in]} {
    55     70     set line [gets $in]
    56     71     incr lineno
................................................................................
    75     90         }
    76     91       } elseif {[string range $line 0 1]=="*/"} {
    77     92         set phase 2
    78     93       }
    79     94     } elseif {$phase==2} {
    80     95       if {$line==""} {
    81     96         set kwlist [lsort [array names keyword]]
           97  +      set docfile [convert_tag_name [lindex $kwlist 0]]
    82     98         unset -nocomplain keyword
    83     99         set key $type:$kwlist
    84    100         if {[regexp {\{([\w.]+)\}} $title all tag]} {
    85    101           regsub { *\{[\w.]+\}} $title {} title
    86    102           if {$dcnt>1} {set d declarations} {set d {a declaration}}
          103  +        set code [string map {& &amp; < &lt; > &gt;} $code]
    87    104           set req "The \"sqlite3.h\" header file\
    88    105               shall contain $d equivalent to the following:\
    89    106               \n<blockquote><pre>\n$code</pre></blockquote>"
    90    107           regexp {\d+} $tag key
    91         -        lappend reqlist [list $key $tag sqlite3.h $title_lineno $req {}]
          108  +        lappend reqlist [list $key $tag sqlite3.h $title_lineno $req $docfile]
    92    109         }
    93    110         set x $body
    94    111         while {[split_text $x prefix tag suffix]} {
    95    112           if {![split_text $suffix req endtag tail]} {
    96    113             set req $suffix
    97    114             set x {}
    98         -          set ex {}
    99    115           } elseif {$endtag=="END"} {
   100         -          set ex {}
   101    116             set x $tail
   102         -        } elseif {$endtag=="EX"} {
   103         -          if {![split_text $tail ex end2 tail2]} {
   104         -            set ex $tail
   105         -            set x {}
   106         -          } elseif {$end2=="END"} {
   107         -            set x $tail2
   108         -          } else {
   109         -            set x "{$end2} $tail2"
   110         -          }
   111    117           } else {
   112         -          set ex {}
   113    118             set x "{$endtag} $tail"
   114    119           }
   115    120           regsub -all {\[([^]|]+\|)?([^]]+)\]} $req {\2} req
   116         -        regsub -all {\s+} $req { } req
          121  +        #regsub -all {\s+} $req { } req
   117    122           set req [string trim $req]
   118         -        regsub -all {\[([^]|]+\|)?([^]]+)\]} $ex {\2} ex
   119         -        regsub -all {\s+} $ex { } ex
   120         -        set ex [string trim $ex]
   121    123           regexp {\d+} $tag key
   122         -        lappend reqlist [list $key $tag sqlite3.h $title_lineno $req $ex]
          124  +        lappend reqlist [list $key $tag sqlite3.h $title_lineno $req $docfile]
   123    125         }
   124    126         set title {}
   125    127         set keywords {}
   126    128         set type {}
   127    129         set body {}
   128    130         set code {}
   129    131         set phase 0
................................................................................
   148    150         }
   149    151         append code $line\n
   150    152       }
   151    153     }
   152    154   }
   153    155   
   154    156   foreach req [lsort -index 0 $reqlist] {
   155         -  foreach {key tag file lineno text ex} $req break
   156         -  puts "<tr><td valign=\"top\">$tag</td>"
   157         -  puts "<td valign=\"top\"><b>$text</b>"
   158         -  if {$ex!=""} {
   159         -    puts "<p>$ex</p>"
   160         -  }
   161         -  puts "</td></tr>"
          157  +  foreach {key tag file lineno text docfile} $req break
          158  +  puts "<tr><td valign=\"top\"><a href=\"c3ref/$docfile\">$tag</a></td>"
          159  +  puts "<td valign=\"top\">$text</td></tr>"
   162    160   }
   163    161   </tcl>
   164    162   
   165    163   </table>