Documentation Source Text

Check-in [fc4a66aa03]
Login

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

Overview
Comment:Reformat the core and aggregate function descriptions in a way that works better on mobile. Use the "output_list" proc for the lists of pragma and aggregate and core functions.
Timelines: family | ancestors | descendants | both | mobile-friendly
Files: files | file ages | folders
SHA1: fc4a66aa03d1ecb6b004b6227d6cd2609f21350c
User & Date: drh 2016-09-01 00:48:22
Context
2016-09-01
00:54
Update the comment on the output_list proc. Use the output_list proc from capi3ref.in to process session.in. check-in: 6f74e2171b user: drh tags: mobile-friendly
00:48
Reformat the core and aggregate function descriptions in a way that works better on mobile. Use the "output_list" proc for the lists of pragma and aggregate and core functions. check-in: fc4a66aa03 user: drh tags: mobile-friendly
2016-08-31
21:38
Limit the width of syntax diagram images to the width of the screen. check-in: 2cbeb114ca user: drh tags: mobile-friendly
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to pages/capi3ref.in.

   301    301     hd_putsnl "for(var i=0; i<$vx.length; i++){"
   302    302     hd_putsnl "  if( (++j)>nRow ){"
   303    303     hd_putsnl "    h += \"</ul></td>\\n<td><ul>\\n\";"
   304    304     hd_putsnl "    j = 1;"
   305    305     hd_putsnl "  }"
   306    306     hd_putsnl "  if($vx\[i\].u==\"\" || $vx\[i\].s==2){"
   307    307     hd_putsnl "    h += \"<li>\""
   308         -  hd_putsnl "    ea = \"\\n\""
          308  +  hd_putsnl "    ea = \"\""
   309    309     hd_putsnl "  }else{"
   310    310     hd_putsnl "    h += \"<li><a href='\";"
   311    311     hd_putsnl "    h += $vx\[i\].u;"
   312    312     hd_putsnl "    h += \"'>\";"
   313         -  hd_putsnl "    ea = \"</a>\\n\""
          313  +  hd_putsnl "    ea = \"</a>\""
   314    314     hd_putsnl "  }"
   315         -  hd_putsnl "  if($vx\[i\].s==2) h += \"<s>\""
          315  +  hd_putsnl "  if($vx\[i\].s==2 || $vx\[i\].s==3) h += \"<s>\""
   316    316     hd_putsnl "  h += $vx\[i\].x;"
   317         -  hd_putsnl "  if($vx\[i\].s==2) h += \"</s>\""
          317  +  hd_putsnl "  if($vx\[i\].s==2 || $vx\[i\].s==3) h += \"</s>\""
   318    318     hd_putsnl "  h += ea"
   319    319     hd_putsnl "  if($vx\[i\].s==1) h += \"<small><i>(exp)</i></small>\\n\";"
          320  +  hd_putsnl "  if($vx\[i\].s==3) h += \"&sup1\\n\";"
          321  +  hd_putsnl "  if($vx\[i\].s==4) h += \"&sup2\\n\";"
          322  +  hd_putsnl "  if($vx\[i\].s==5) h += \"&sup3\\n\";"
   320    323     hd_putsnl "}"
   321    324     hd_putsnl "document.getElementById(\"$tx\").innerHTML = h;"
   322    325     hd_putsnl "</script>"
   323    326   }
   324    327   
   325    328   hd_open_aux c3ref/intro.html
   326    329   hd_header Introduction

Changes to pages/lang.in.

  2318   2318   function are different.  ^For example, the [agg_max|max()] function with a
  2319   2319   single argument is an aggregate and the [max()] function with two or more
  2320   2320   arguments is a simple function.
  2321   2321   
  2322   2322   <tcl>
  2323   2323   ##############################################################################
  2324   2324   Section {Core Functions} corefunc {*corefunc}
         2325  +unset -nocomplain corefuncset
  2325   2326   proc funcdef {syntax keywords desc} {
  2326         -  hd_puts {<tr>}
  2327         -  regsub -all {\s+} [string trim $syntax] {<br />} syntax
  2328         -  regsub -all {\(([^*)]+)\)} $syntax {(<i>\1</i>)} syntax
  2329         -  regsub -all {,} $syntax {</i>,<i>} syntax
  2330         -  regsub -all {<i>\.\.\.</i>} $syntax {...} syntax
  2331         -  hd_puts "<td valign=\"top\" align=\"right\" width=\"120\">"
  2332         -  if {[llength $keywords]==0} {
  2333         -    regexp {[a-z_]+} $syntax name
  2334         -    hd_fragment $name *$name "${name}() SQL function"
  2335         -  } else {
  2336         -    set fragname [lindex $keywords 0]
  2337         -    regsub -all {[^a-z]} $fragname {} fragname
  2338         -    hd_fragment $fragname
  2339         -    eval hd_keywords [string map {\n { }} $keywords]
  2340         -  }
  2341         -  hd_puts "$syntax</td>"
  2342         -  hd_puts {<td valign="top">}
  2343         -  hd_resolve $desc
  2344         -  hd_puts {</td></tr>}
         2327  +  global corefuncset
         2328  +  regexp {^[a-z_]+} $syntax basesyntax
         2329  +  set corefuncset($basesyntax) [list $syntax $keywords $desc]
  2345   2330   }
  2346         -</tcl>
  2347         -
  2348         -<p>The core functions shown below are available by default. 
  2349         -[datefunc | Date &amp; Time functions],
  2350         -[aggfunc | aggregate functions], and
  2351         -[json1 | JSON functions] are documented separately.  An
  2352         -application may define additional
  2353         -functions written in C and added to the database engine using
  2354         -the [sqlite3_create_function()] API.</p>
  2355         -
  2356         -<table border=0 cellpadding=10>
  2357         -<tcl>
  2358   2331   funcdef {abs(X)} {} {
  2359   2332     ^The abs(X) function returns the absolute value of the numeric
  2360   2333     argument X.  ^Abs(X) returns NULL if X is NULL. 
  2361   2334     ^(Abs(X) returns 0.0 if X is a string or blob
  2362   2335     that cannot be converted to a numeric value.)^  ^If X is the 
  2363   2336     integer -9223372036854775808 then abs(X) throws an integer overflow
  2364   2337     error since there is no equivalent positive 64-bit two complement value.
................................................................................
  2709   2682     SQLite manages these zeroblobs very efficiently.  Zeroblobs can be used to
  2710   2683     reserve space for a BLOB that is later written using 
  2711   2684     [sqlite3_blob_open() | incremental BLOB I/O].
  2712   2685     ^This SQL function is implemented using the [sqlite3_result_zeroblob()]
  2713   2686     routine from the C/C++ interface.
  2714   2687   }
  2715   2688   </tcl>
  2716         -</table>
         2689  +
         2690  +<p>The core functions shown below are available by default. 
         2691  +[datefunc | Date &amp; Time functions],
         2692  +[aggfunc | aggregate functions], and
         2693  +[json1 | JSON functions] are documented separately.  An
         2694  +application may define additional
         2695  +functions written in C and added to the database engine using
         2696  +the [sqlite3_create_function()] API.</p>
  2717   2697   
  2718   2698   <tcl>
         2699  +set lx {}
         2700  +foreach basesyntax [array names corefuncset] {
         2701  +  foreach {syntax keywords desc} $corefuncset($basesyntax) break
         2702  +  regexp {^[a-z_]+} $basesyntax fragment
         2703  +  foreach coresyntax $syntax {
         2704  +    lappend lx [list $fragment $coresyntax 0]
         2705  +  }
         2706  +}
         2707  +output_list {} 225 [lsort -index 1 $lx]
         2708  +
         2709  +hd_putsnl "<hr class='xhr'>"
         2710  +hd_putsnl "<dl>"
         2711  +foreach basesyntax [lsort [array names corefuncset]] {
         2712  +  foreach {syntax keywords desc} $corefuncset($basesyntax) break
         2713  +  regsub -all {\s+} [string trim $syntax] {<br />} syntax
         2714  +  regsub -all {\(([^*)]+)\)} $syntax {(<i>\1</i>)} syntax
         2715  +  regsub -all {,} $syntax {</i>,<i>} syntax
         2716  +  regsub -all {<i>\.\.\.</i>} $syntax {...} syntax
         2717  +  regexp {^[a-z]+} $basesyntax fragment
         2718  +  if {[llength $keywords]==0} {
         2719  +    regexp {[a-z_]+} $syntax name
         2720  +    hd_fragment $name *$name "${name}() SQL function"
         2721  +  } else {
         2722  +    set fragname [lindex $keywords 0]
         2723  +    regsub -all {[^a-z]} $fragname {} fragname
         2724  +    hd_fragment $fragname
         2725  +    eval hd_keywords [string map {\n { }} $keywords]
         2726  +  }
         2727  +  hd_puts "<dt><p><b>$syntax</b></dt>"
         2728  +  hd_resolve "<dd><p>$desc</dd>\n"
         2729  +}
         2730  +hd_putsnl "</dl>"
         2731  +
  2719   2732   ##############################################################################
  2720   2733   Section {Date And Time Functions} datefunc {*datefunc {date and time functions}}
  2721   2734   hd_keywords {date() SQL function} {time() SQL function}
  2722   2735   hd_keywords {datetime() SQL function} {julianday() SQL function}
  2723   2736   hd_keywords {strftime() SQL function}
  2724   2737   </tcl>
  2725   2738   
................................................................................
  3019   3032   [http://en.wikipedia.org/wiki/Gregorian_calendar | Gregorian calendar]
  3020   3033   system.  It is also assumed that every
  3021   3034   day is exactly 86400 seconds in duration.</p>
  3022   3035   
  3023   3036   <tcl>
  3024   3037   ##############################################################################
  3025   3038   Section {Aggregate Functions} aggfunc {*aggfunc}
  3026         -</tcl>
         3039  +unset -nocomplain corefuncset
  3027   3040   
  3028         -<p>
  3029         -The aggregate functions shown below are available by default.  Additional
  3030         -aggregate functions written in C may be added using the 
  3031         -[sqlite3_create_function()]</a>
  3032         -API.</p>
  3033         -
  3034         -<p>
  3035         -^In any aggregate function that takes a single argument, that argument
  3036         -can be preceded by the keyword DISTINCT.  ^In such cases, duplicate
  3037         -elements are filtered before being passed into the aggregate function.
  3038         -^For example, the function "count(distinct X)" will return the number
  3039         -of distinct values of column X instead of the total number of non-null
  3040         -values in column X.
  3041         -</p>
  3042         -
  3043         -<table border=0 cellpadding=10>
  3044         -<tcl>
  3045   3041   funcdef {avg(X)} {*avg {avg() aggregate function}} {
  3046   3042     ^The avg() function
  3047   3043     returns the average value of all non-NULL <i>X</i> within a
  3048   3044     group.  ^String and BLOB values that do not look like numbers are
  3049   3045     interpreted as 0.
  3050   3046     ^The result of avg() is always a floating point value as long as
  3051   3047     at there is at least one non-NULL input even if all
................................................................................
  3113   3109   
  3114   3110     <p>^Sum() will throw an "integer overflow" exception if all inputs
  3115   3111     are integers or NULL
  3116   3112     and an integer overflow occurs at any point during the computation.
  3117   3113     ^Total() never throws an integer overflow.
  3118   3114   }
  3119   3115   </tcl>
  3120         -</table>
         3116  +
         3117  +
         3118  +<p>
         3119  +The aggregate functions shown below are available by default.  Additional
         3120  +aggregate functions written in C may be added using the 
         3121  +[sqlite3_create_function()]</a>
         3122  +API.</p>
         3123  +
         3124  +<p>
         3125  +^In any aggregate function that takes a single argument, that argument
         3126  +can be preceded by the keyword DISTINCT.  ^In such cases, duplicate
         3127  +elements are filtered before being passed into the aggregate function.
         3128  +^For example, the function "count(distinct X)" will return the number
         3129  +of distinct values of column X instead of the total number of non-null
         3130  +values in column X.
         3131  +</p>
  3121   3132   
  3122   3133   <tcl>
         3134  +set lx {}
         3135  +foreach basesyntax [array names corefuncset] {
         3136  +  foreach {syntax keywords desc} $corefuncset($basesyntax) break
         3137  +  regexp {^[a-z_]+} $basesyntax fragment
         3138  +  foreach coresyntax $syntax {
         3139  +    lappend lx [list $fragment $coresyntax 0]
         3140  +  }
         3141  +}
         3142  +output_list {} 225 [lsort -index 1 $lx]
         3143  +
         3144  +hd_putsnl "<hr class='xhr'>"
         3145  +hd_putsnl "<dl>"
         3146  +foreach basesyntax [lsort [array names corefuncset]] {
         3147  +  foreach {syntax keywords desc} $corefuncset($basesyntax) break
         3148  +  regsub -all {\s+} [string trim $syntax] {<br />} syntax
         3149  +  regsub -all {\(([^*)]+)\)} $syntax {(<i>\1</i>)} syntax
         3150  +  regsub -all {,} $syntax {</i>,<i>} syntax
         3151  +  regsub -all {<i>\.\.\.</i>} $syntax {...} syntax
         3152  +  regexp {^[a-z]+} $basesyntax fragment
         3153  +  if {[llength $keywords]==0} {
         3154  +    regexp {[a-z_]+} $syntax name
         3155  +    hd_fragment $name *$name "${name}() SQL function"
         3156  +  } else {
         3157  +    set fragname [lindex $keywords 0]
         3158  +    regsub -all {[^a-z]} $fragname {} fragname
         3159  +    hd_fragment $fragname
         3160  +    eval hd_keywords [string map {\n { }} $keywords]
         3161  +  }
         3162  +  hd_puts "<dt><p><b>$syntax</b></dt>"
         3163  +  hd_resolve "<dd><p>$desc</dd>\n"
         3164  +}
         3165  +hd_putsnl "</dl>"
         3166  +
  3123   3167   ##############################################################################
  3124   3168   Section INSERT insert {INSERT *INSERTs}
  3125   3169   
  3126   3170   RecursiveBubbleDiagram insert-stmt
  3127   3171   </tcl>
  3128   3172   
  3129   3173   <p>The INSERT statement comes in three basic forms.  
................................................................................
  4848   4892   </p>
  4849   4893   
  4850   4894   <tcl>
  4851   4895   set lx {}
  4852   4896   foreach word $keyword_list {
  4853   4897     lappend lx [list {} $word 0]
  4854   4898   }
  4855         -output_list {} 180 $lx
         4899  +output_list {} 200 $lx
  4856   4900   </tcl>
  4857   4901   <blockquote>
  4858   4902   <table width="100%"><tr>
  4859   4903   <td align="left" valign="top" width="20%">
  4860   4904   <tcl>

Changes to pages/pragma.in.

  1542   1542       <p>When this pragma is on, the SQLITE_MASTER tables in which database
  1543   1543       can be changed using ordinary [UPDATE], [INSERT], and [DELETE]
  1544   1544       statements.)^  ^Warning:  misuse of this pragma can easily result in
  1545   1545       a corrupt database file.</p>
  1546   1546   }
  1547   1547   
  1548   1548   Section {List Of PRAGMAs} {toc} {{pragma list}}
  1549         -</tcl>
  1550         -<table border=0 width="100%" cellpadding=10>
  1551         -<tr><td valign="top" align="left"><ul>
  1552         -<tcl>
  1553         -set allprag [lsort [array names PragmaRef]]
  1554         -set nprag [llength $allprag]
  1555         -set nrow [expr {($nprag+2)/3}]
  1556         -for {set i 0} {$i<$nprag} {incr i} {
  1557         -  set prag [lindex $allprag $i]
         1549  +set lx {}
         1550  +foreach prag [array names PragmaRef] {
  1558   1551     set ref $PragmaRef($prag)
  1559   1552     if {[info exists PragmaLegacy($prag)]} {
  1560         -    hd_puts "<li><a href=\"#pragma_$ref\"><s>$prag</s></a>&sup1;\n"
         1553  +    lappend lx [list "PRAGMA $ref" $prag 3]
  1561   1554     } elseif {[info exists PragmaDebug($prag)]} {
  1562         -    hd_puts "<li><a href=\"#pragma_$ref\"><i>$prag</i></a>&sup2;\n"
         1555  +    lappend lx [list "PRAGMA $ref" $prag 4]
  1563   1556     } elseif {[info exists PragmaTest($prag)]} {
  1564         -    hd_puts "<li><a href=\"#pragma_$ref\"><i>$prag</i></a>&sup3;\n"
         1557  +    lappend lx [list "PRAGMA $ref" $prag 5]
  1565   1558     } else {
  1566         -    hd_puts "<li><a href=\"#pragma_$ref\">$prag</a>\n"
  1567         -  }
  1568         -  if {$i%$nrow==($nrow-1) && $i+1<$nprag} {
  1569         -    hd_puts "</ul></td><td valign=\"top\" align=\"left\"><ul>\n"
         1559  +    lappend lx [list "PRAGMA $ref" $prag 0]
  1570   1560     }
  1571   1561   }
         1562  +output_list {} 250 [lsort -index 1 $lx]
  1572   1563   </tcl>
  1573         -</ul></td></tr></table>
  1574   1564   <p>Notes:
  1575   1565   <ol>
  1576         -<li>Pragmas whose names are marked through in the list above
  1577         -are deprecated.  They are not maintained.  They continue to exist
  1578         -for historical compatibility only.
  1579         -Do not use the deprecated pragmas in new applications.
  1580         -Remove deprecated pragmas
  1581         -from existing applications at your earliest opportunity.</blockquote>
         1566  +<li>Pragmas whose names are <s>struck through</s>
         1567  +are deprecated. Do not use them. They exist
         1568  +for historical compatibility.
  1582   1569   <li>These pragmas are used for debugging SQLite and
  1583   1570   are only available when SQLite is compiled using [SQLITE_DEBUG].
  1584   1571   <li>These pragmas are used for testing SQLite and are not recommended
  1585   1572   for use in application programs.</ol></p>
  1586   1573   <tcl>
  1587   1574   foreach prag [lsort [array names PragmaBody]] {
  1588   1575     hd_fragment pragma_$prag