Documentation Source Text

Check-in [c5aa49ff35]
Login

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

Overview
Comment:Improve the internal links from text to glossary definitions in fileformat.html. Also fix a bunch of issues reported by John Machin on the mailing list.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:c5aa49ff3588e33fb2e71d012ca7fbe3c5d0454a
User & Date: dan 2009-05-26 23:13:58
Context
2009-05-26
23:52
Fix an error in the previous commit. A "todo" note was added in the wrong place. check-in: e0634484e3 user: dan tags: trunk
23:13
Improve the internal links from text to glossary definitions in fileformat.html. Also fix a bunch of issues reported by John Machin on the mailing list. check-in: c5aa49ff35 user: dan tags: trunk
15:13
Add a "todo" note to fix the schema file-format range. Also fix another todo in fileformat.html. check-in: 14e677d1dc user: dan tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to images/fileformat/rtdocs.css.

    54     54     **     <p class=todo>Longer todo note.</p>
    55     55     */
    56     56     .todo        { color: #AA3333 ; font-style : italic }
    57     57     .todo:before { content: 'TODO:' }
    58     58     p.todo       { border: solid #AA3333 1px; padding: 1ex }
    59     59   
    60     60     cite a, cite a:visited { color: inherit; text-decoration: none ; font-style: normal; }
    61         -  .defnlink    { 
    62         -    color: inherit; 
           61  +  .defnlink, .reqlink { 
           62  +    color: inherit;
    63     63       text-decoration: none;
    64         -    font-style: italic;
    65     64     }
    66         -  .defnlink:visited    { color: inherit }
           65  +  .defnlink { font-style: italic }
           66  +  .defnlink:visited,.reqlink:visited { color: inherit }
    67     67     h1 .defnlink, h2 .defnlink, h3 .defnlink, h4 .defnlink, .defn .defnlink{ font-style: inherit }
    68     68     :link:hover,:visited:hover { background: wheat }
    69     69   
    70     70     img {
    71     71       display:block;
    72     72     }
    73     73   

Changes to pages/fileformat.in.

    17     17   # the process in which this document is converted into HTML, TCL script runs
    18     18   # and imports requirements from that file over into this file whenever you
    19     19   # see:
    20     20   #            <t*l>fileformat_import_requirement H00000</t*l>
    21     21   #
    22     22   unset -nocomplain ffreq
    23     23   hd_read_requirement_file $::DOC/req/hlr30000.txt ffreq
           24  +set ::Requirements [list]
    24     25   proc fileformat_import_requirement {reqid} {
    25     26     return [lindex $::ffreq($reqid) 1]
    26     27   }
    27     28   proc fileformat_import_requirement2 {reqid} {
           29  +  lappend ::Requirements $reqid
    28     30     return "<p class=req id=$reqid>[fileformat_import_requirement $reqid]</p>"
    29     31   }
    30     32   ###############################################################################
    31     33   
    32     34   catch { array unset ::SectionNumbers }
    33     35   set ::SectionNumbers(1) 0
    34     36   set ::SectionNumbers(2) 0
................................................................................
    83     85         </center>
    84     86     }
    85     87   }
    86     88   
    87     89   proc sort_by_length {lhs rhs} {
    88     90     return [expr [string length $lhs] - [string length $rhs]]
    89     91   }
           92  +
           93  +set ::Random 0
           94  +proc randomstring {} {
           95  +  incr ::Random
           96  +  return [expr $::Random + rand()]
           97  +}
    90     98   
    91     99   proc FixReferences {body} {
          100  +  if {[info commands hd_resolve_2ndpass] ne ""} return 
          101  +
    92    102     foreach E [lsort -decr -index 1 -command sort_by_length $::Glossary] {
    93    103       # puts $E
    94    104       foreach {term anchor} $E {}
    95    105       set re [string map {" " [-[:space:]]+} $term]
    96    106       set re "${re}s?"
    97         -    set body [regsub -all -nocase $re $body "<a class=defnlink href=\"#$anchor\">\\0</a>"]
          107  +
          108  +    while { [regexp -nocase $re $body thisterm] } {
          109  +      set xxx [randomstring]
          110  +      set body [regsub -nocase $re $body $xxx]
          111  +      lappend l $xxx "<a class=defnlink href=\"#$anchor\">$thisterm</a>"
          112  +    }
          113  +
          114  +    # set body [regsub -all -nocase $re $body "<a class=defnlink href=\"#$anchor\">\\0</a>"]
    98    115       # set body [regsub -all -nocase {(defnlink[^<]*) } $body "\\1&20;"]
    99    116     }
          117  +
          118  +  foreach R $::Requirements {
          119  +    set body [regsub -all "(\[^=\])$R" $body "\\1<a class=reqlink href=#$R>$R</a>"]
          120  +  }
   100    121   
   101    122     foreach {key value} [array get ::References] {
   102    123       foreach {zNumber zTitle} $value {}
   103    124       lappend l <cite>$key</cite> "<cite><a href=\"#$key\" title=\"$zTitle\">$zNumber</a></cite>"
   104    125     }
          126  +
   105    127     set body [string map $l $body]
   106    128   }
   107    129   
   108    130   set ::Glossary {}
   109    131   proc Glossary {term definition} {
   110    132     set anchor [string map {" " _ ' _} $term]
   111    133     set anchor "glossary_$anchor"
   112    134     lappend ::Glossary [list $term $anchor]
   113         -
   114    135     return "<tr><td class=defn><a name=\"$anchor\"></a>$term <td>$definition"
   115    136   }
   116    137   
          138  +# Procs to generate <table> and <tr> tags. They also give alternating rows
          139  +# of the table a grey background, which can make it easier to read.
          140  +# 
   117    141   proc Table {} {
   118    142     set ::Stripe 1
   119    143     return "<table class=striped>"
   120    144   }
   121    145   proc Tr {} {
   122    146     set ::Stripe [expr {($::Stripe+1)%2}]
   123    147     if {$::Stripe} {
................................................................................
   860    884   
   861    885         <ul>
   862    886           <li> The file-format write version (single byte field, byte offset 18), 
   863    887                is always set to 0x01.
   864    888           <li> The file-format read version (single byte field, byte offset 19), 
   865    889                is always set to 0x01.
   866    890           <li> The number of unused bytes on each page (single byte field, byte 
   867         -             offset 20), is always set to 0x01.
          891  +             offset 20), is always set to 0x00.
   868    892           <li> The maximum fraction of an index B-Tree page to use for embedded content 
   869    893   	     (single byte field, byte offset 21), is always set to 0x40.  <li>
   870    894   	     The minimum fraction of an index B-Tree page to use for embedded
   871    895   	     content when using overflow pages (single byte field, byte 
   872    896                offset 22), is always set to 0x20.
   873    897   	<li> The minimum fraction of a table B-Tree page to use for embedded
   874    898   	     content when using overflow pages (single byte field, byte offset 23),
................................................................................
   979   1003           [Tr]<td style="white-space:nowrap">Associated table name.
   980   1004               <td>A string value. For "table" 
   981   1005               or "view" records this is a copy of the second (previous) value. 
   982   1006               For "index" and "trigger" records, this field is set to the name 
   983   1007               of the associated database table.
   984   1008           [Tr]<td style="white-space:nowrap">The "root page" number. 
   985   1009               <td>For "trigger" and "view" records, as well as "table" records
   986         -                associated with virtual tables, this is set to NULL. For other
   987         -                "table" and "index" records (including those associated with
   988         -                UNIQUE or PRIMARY KEY clauses), this field contains the root
         1010  +	        associated with virtual tables, this is set to integer value 0. 
         1011  +		For other "table" and "index" records (including those associated 
         1012  +		with UNIQUE or PRIMARY KEY clauses), this field contains the root
   989   1013                   page number (an integer) of the B-Tree structure that contains
   990   1014                   the table or index data.
   991   1015           [Tr]<td>The SQL statement.
   992   1016               <td>A string value. The SQL statement used to create the schema
   993   1017                   item (i.e.  the complete text of an SQL "CREATE TABLE"
   994   1018                   statement). This field contains an empty string for table
   995   1019                   entries associated with PRIMARY KEY or UNIQUE clauses.
................................................................................
  1168   1192   
  1169   1193         [Table]
  1170   1194           [Tr]<th>Decimal<th>Hexadecimal        <th>Variable Length Integer
  1171   1195           [Tr]<td>43     <td>0x000000000000002B <td>0x2B
  1172   1196           [Tr]<td>200815 <td>0x000000000003106F <td>0x8C 0xA0 0x6F
  1173   1197           [Tr]<td>-1     <td>0xFFFFFFFFFFFFFFFF 
  1174   1198               <td>0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF
  1175         -        [Tr]<td>-78056 <td>0xFFFFFFFFFFFECD56
         1199  +        [Tr]<td>-78506 <td>0xFFFFFFFFFFFECD56
  1176   1200               <td>0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFD 0xCD 0x56
  1177   1201         </table>
  1178   1202   
  1179   1203             [fileformat_import_requirement2 H30520]
  1180   1204             [fileformat_import_requirement2 H30530]
  1181   1205             [fileformat_import_requirement2 H30540]
  1182   1206             [fileformat_import_requirement2 H30550]
................................................................................
  1240   1264               <td>The literal SQL integer 1 (type SQLITE_INTEGER). The value
  1241   1265                   consumes zero bytes of space in the record's data area.
  1242   1266                   Values of this type are only present in databases with
  1243   1267                   a schema file format (the 32-bit integer at byte offset 44
  1244   1268                   of the database header) value of 4 or greater.
  1245   1269   
  1246   1270           [Tr]<td style="white-space:nowrap"><i>bytes</i> * 2 + 12
  1247         -            <td>Even values greater than 12 are used to signify a blob of
  1248         -                data (type SQLITE_BLOB) (<i>n</i>-12)/2 bytes in length, where
  1249         -                <i>n</i> is the integer value stored in the record header.
         1271  +	    <td>Even values greater than or equal to 12 are used to signify a 
         1272  +	        blob of data (type SQLITE_BLOB) (<i>n</i>-12)/2 bytes in length, 
         1273  +	        where <i>n</i> is the integer value stored in the record header.
  1250   1274                   
  1251   1275           [Tr]<td style="white-space:nowrap"><i>bytes</i> * 2 + 13
  1252   1276               <td>Odd values greater than 12 are used to signify a string
  1253   1277                   (type SQLITE_TEXT) (<i>n</i>-13)/2 bytes in length, where
  1254   1278                   <i>n</i> is the integer value stored in the record header.
  1255   1279         </table>
  1256   1280         <p>
................................................................................
  1554   1578           <p> 
  1555   1579             Following the child page number is the total number of bytes 
  1556   1580             consumed by the cell's record, stored as a variable length integer
  1557   1581             (see section <cite>varint_format</cite>). 
  1558   1582           <p> 
  1559   1583             If the record is small enough, it is stored verbatim in the cell.
  1560   1584             A record is deemed to be small enough to be completely stored in
  1561         -          the cell if it consists of less than:
         1585  +          the cell if it consists of less than or equal to:
  1562   1586           <pre>
  1563   1587               <i>max-local</i> := (<i>usable-size</i> - 12) * <i>max-embedded-fraction</i> / 255 - 23
  1564   1588   </pre>
  1565   1589           <p>
  1566   1590             bytes. In the formula above, <i>usable-size</i> is the page-size
  1567   1591             in bytes less the number of unused bytes left at the end of every
  1568   1592             page (as read from byte offset 20 of the database header), and
................................................................................
  1700   1724           <p>The following database properties discuss table B-Tree records 
  1701   1725              with implicit (default) values.
  1702   1726   
  1703   1727             [fileformat_import_requirement2 H31100]
  1704   1728             [fileformat_import_requirement2 H31110]
  1705   1729             [fileformat_import_requirement2 H31120]
  1706   1730   
         1731  +	<p class=todo>
         1732  +          See the note to do with the schema file format version above. Turns
         1733  +          out this field may also be set to 0 by SQLite.
         1734  +
  1707   1735         [h4 "Table B-Tree Page Format"]
  1708   1736           <p>
  1709   1737             Table B-Tree structures use the same page format as index B-Tree 
  1710   1738             structures, described in section <cite>index_btree_page_format</cite>,
  1711   1739             with the following differences:
  1712   1740           <ul>
  1713   1741             <li>The first byte of the page-header, the "flags" field, is set to 

Changes to req/hlr30000.txt.

   124    124   <i>schema table</i> records associated with SQL tables that are not
   125    125   virtual tables contains the page number (an integer value) of the root
   126    126   page of the associated <i>table B-Tree</i> structure within the
   127    127   database file.
   128    128   
   129    129   HLR H30300
   130    130   If the associated database table is a virtual table, the fourth
   131         -field of the <i>schema table</i> record shall contain an SQL NULL
   132         -value.
          131  +field of the <i>schema table</i> record shall contain the integer
          132  +value 0 (zero).
   133    133   
   134    134   HLR H30310
   135    135   In a well-formed database, the fifth field of all <i>schema table</i>
   136    136   records associated with SQL tables shall contain a "CREATE TABLE"
   137    137   or "CREATE VIRTUAL TABLE" statment (a text value).  The details
   138    138   of the statement shall be such that executing the statement
   139    139   would create a table of precisely the same name and schema as the
................................................................................
   694    694   HLR H31190
   695    695   When a table B-Tree cell is stored partially in an
   696    696   <i>overflow page chain</i>, the prefix stored on the B-Tree
   697    697   leaf page consists of the two <i>variable length integer</i> fields,
   698    698   followed by the first <i>N</i> bytes of the database record, where
   699    699   <i>N</i> is determined by the following algorithm:
   700    700   <code>
   701         -<i>min-local</i> := (<i>usable-size</i> - 12) * 255 / 32 - 23
          701  +<i>min-local</i> := (<i>usable-size</i> - 12) * 32 / 255 - 23
   702    702   <i>max-local</i> := (<i>usable-size</i> - 35)
   703    703   <i>N</i> := <i>min-local</i> + (<i>record-size</i> - <i>min-local</i>) % (<i>usable-size</i> - 4)
   704    704   if( <i>N</i> &gt; <i>max-local</i> ) N := <i>min-local</i>
   705    705   </code>
   706    706   
   707    707   HLR H31200
   708    708   A single <i>overflow page</i> may store up to <i>available-space</i>