System.Data.SQLite
Check-in [960fde8c37]
Not logged in

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

Overview
Comment:Enhance the NDoc3/HtmlHelp build script to support transforming SQLite core library documentation links as necessary.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | coreDocs
Files: files | file ages | folders
SHA1: 960fde8c37759e93fa52409a88af5c95fb9fabe7
User & Date: mistachkin 2014-02-05 01:31:06
Context
2014-02-05
01:36
Some readability improvements to the NDoc3/HtmlHelp build script. check-in: 1e20c68e20 user: mistachkin tags: coreDocs
01:31
Enhance the NDoc3/HtmlHelp build script to support transforming SQLite core library documentation links as necessary. check-in: 960fde8c37 user: mistachkin tags: coreDocs
00:04
Import new SQLite core docs. check-in: c221f9714d user: mistachkin tags: coreDocs
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to Doc/Extra/Core/lang_select.html.

   657    657   <a name="crossjoin"></a>
   658    658   
   659    659   <p><b>Side note: Special handling of CROSS JOIN.</b>
   660    660   There is no difference between the "INNER JOIN", "JOIN" and "," join
   661    661   operators. They are completely interchangeable in SQLite.
   662    662   The "CROSS JOIN" join operator produces the same result as the 
   663    663   "INNER JOIN", "JOIN" and "," operators, but is 
   664         -<a href=optoverview.html#crossjoin>handled differently by the query
          664  +<a href="optoverview.html#crossjoin">handled differently by the query
   665    665   optimizer</a> in that it prevents the query optimizer from reordering
   666    666   the tables in the join.  An application programmer can use the CROSS JOIN 
   667    667   operator to directly influence the algorithm that is chosen to implement
   668    668   the SELECT statement.  Avoid using CROSS JOIN except in specific situations 
   669    669   where manual control of the query optimizer is desired.  Avoid using
   670    670   CROSS JOIN early in the development of an application as doing so is
   671    671   a <a href="http://c2.com/cgi/wiki?PrematureOptimization">premature

Changes to Doc/SQLite.NET.hhc.

   193    193   			<param name="Local" value="Core/lang_with.html">
   194    194   			</OBJECT>
   195    195   		<LI> <OBJECT type="text/sitemap">
   196    196   			<param name="Name" value="PRAGMA">
   197    197   			<param name="Local" value="Core/pragma.html">
   198    198   			</OBJECT>
   199    199   		<LI> <OBJECT type="text/sitemap">
   200         -			<param name="Name" value="Syntax Diagrams For SQLite">
          200  +			<param name="Name" value="Syntax Diagrams">
   201    201   			<param name="Local" value="Core/syntaxdiagrams.html">
   202    202   			</OBJECT>
   203    203   	</UL>
   204    204   </BODY><HTML>

Changes to Doc/buildChm.tcl.

    22     22     set file_id [open $fileName {WRONLY CREAT TRUNC}]
    23     23     fconfigure $file_id -encoding binary -translation binary
    24     24     puts -nonewline $file_id $data
    25     25     close $file_id
    26     26     return ""
    27     27   }
    28     28   
    29         -proc readFileAsSubSpec { fileName } {
    30         -  set data [readFile $fileName]
           29  +proc escapeSubSpec { data } {
    31     30     regsub -all -- {&} $data {\\\&} data
    32     31     regsub -all -- {\\(\d+)} $data {\\\\\1} data
    33     32     return $data
    34     33   }
           34  +
           35  +proc readFileAsSubSpec { fileName } {
           36  +  return [escapeSubSpec [readFile $fileName]]
           37  +}
    35     38   
    36     39   proc getFileHash { fileName } {
    37     40     if {[catch {
    38     41       exec fossil.exe sha1sum [file nativename $fileName]
    39     42     } result] == 0} then {
    40     43       return [string trim [lindex [split $result " "] 0]]
    41     44     }
    42     45     return ""
    43     46   }
           47  +
           48  +#
           49  +# HACK: This procedure checks all the "href" attribute values in the specified
           50  +#       core documentation file.  For each value, this procedure checks if the
           51  +#       reference conforms to one of the following general categories:
           52  +#
           53  +#       1. A relative reference to a named anchor within the same document.
           54  +#       2. An absolute reference using HTTP or HTTPS.
           55  +#       3. A relative reference to an existing local file.
           56  +#       4. An absolute reference to a local file.
           57  +#
           58  +#       Otherwise, this procedure transforms the "href" attribute value into
           59  +#       an absolute reference using the specified base URL.
           60  +#
           61  +proc transformCoreDocumentationFile { fileName url } {
           62  +  #
           63  +  # NOTE: Grab the name of the directory containing the file.
           64  +  #
           65  +  set directory [file dirname $fileName]
           66  +
           67  +  #
           68  +  # NOTE: Read all the textual data from the file.
           69  +  #
           70  +  set data [readFile $fileName]
           71  +
           72  +  #
           73  +  # NOTE: No replacements made yet.
           74  +  #
           75  +  set count 0
           76  +
           77  +  #
           78  +  # NOTE: Process all "href" attribute values from the data.  This pattern is
           79  +  #       not univeral; however, as of this writing (Feb 2014), the core docs
           80  +  #       are using it consistently.
           81  +  #
           82  +  foreach {dummy href} [regexp -all -inline -nocase -- {href="(.*?)"} $data] {
           83  +    #
           84  +    # NOTE: Skip all references to other items on this page.
           85  +    #
           86  +    if {[string index $href 0] eq "#"} then {
           87  +      continue
           88  +    }
           89  +
           90  +    #
           91  +    # NOTE: Skip all absolute HTTP/HTTPS references.
           92  +    #
           93  +    if {[string range $href 0 6] eq "http://" || \
           94  +        [string range $href 0 7] eq "https://"} then {
           95  +      continue
           96  +    }
           97  +
           98  +    #
           99  +    # NOTE: Split on the "#" character to get the file name.  There are some
          100  +    #       places within the core docs that refer to named anchors within
          101  +    #       other files.
          102  +    #
          103  +    set parts [split $href #]; set part1 [lindex $parts 0]
          104  +
          105  +    #
          106  +    # NOTE: If there is no file name part, skip the reference.
          107  +    #
          108  +    if {[string length $part1] == 0} then {
          109  +      continue
          110  +    }
          111  +
          112  +    #
          113  +    # NOTE: If it does not appear to be relative, skip it.
          114  +    #
          115  +    if {[file pathtype $part1] ne "relative"} then {
          116  +      continue
          117  +    }
          118  +
          119  +    #
          120  +    # NOTE: If the referenced file name exists locally, skip it.
          121  +    #
          122  +    if {[file exists [file join $directory $part1]]} then {
          123  +      continue
          124  +    }
          125  +
          126  +    #
          127  +    # NOTE: Replace the reference with an absolute reference using the base
          128  +    #       URL specified by the caller, escaping it as necessary for use
          129  +    #       with [regsub].
          130  +    #
          131  +    set pattern "***=$dummy"; # NOTE: Use literal string syntax.
          132  +    set subSpec "href=\"[escapeSubSpec $url$href]\""
          133  +
          134  +    #
          135  +    # NOTE: Perform the replacements, if any, keeping track of how many were
          136  +    #       done.
          137  +    #
          138  +    incr count [regsub -all -- $pattern $data $subSpec data]
          139  +  }
          140  +
          141  +  #
          142  +  # NOTE: If some replacements were performed on the data from the file, then
          143  +  #       overwrite it with the new data; otherwise, issue a warning.
          144  +  #
          145  +  if {$count > 0} then {
          146  +    writeFile $fileName $data
          147  +  } else {
          148  +    puts stdout "*WARNING* File \"$fileName\" does not match: href=\"(.*?)\""
          149  +  }
          150  +}
    44    151   
    45    152   #
    46    153   # HACK: Copy our local [fixed] copy of the MSDN documenter assembly into the
    47    154   #       installed location of NDoc3, if necessary.  Actually copying the file
    48    155   #       will require elevated administrator privileges; otherwise, it will
    49    156   #       fail.  Any errors encountered while copying the file are reported via
    50    157   #       the console; however, they will not halt further processing (i.e. the
................................................................................
   144    251   
   145    252   #
   146    253   # TODO: If the NDoc version number ever changes, the next line of code will
   147    254   #       probably need to be updated.
   148    255   #
   149    256   set outputPath [file join Output]
   150    257   set temporaryPath [file join $outputPath ndoc3_msdn_temp]
          258  +set corePath [file join $temporaryPath Core]
          259  +set providerPath [file join $temporaryPath Provider]
   151    260   
   152    261   if {[file isdirectory $nDocExtPath]} then {
   153    262     copyMsdnDocumenter $nDocExtPath $nDocInstPath
   154    263   }
   155    264   
   156    265   set code [catch {exec [file join $nDocInstPath bin NDoc3Console.exe] \
   157    266       "-project=[file nativename $projectFile]"} result]
   158    267   
   159    268   puts stdout $result; if {$code != 0} then {exit $code}
   160    269   
   161         -set fileNames [list SQLite.NET.hhp SQLite.NET.hhc]
          270  +foreach fileName [glob -nocomplain [file join $corePath *.html]] {
          271  +  set fileName [file join $path $fileName]
   162    272   
   163         -foreach fileName [glob -nocomplain [file join $temporaryPath *.html]] {
   164         -  lappend fileNames [file tail $fileName]
          273  +  if {![file isfile $fileName]} then {
          274  +    puts stdout "Cannot find core file: $fileName"
          275  +    exit 1
          276  +  }
          277  +
          278  +  transformCoreDocumentationFile $fileName http://www.sqlite.org/
          279  +}
          280  +
          281  +set providerFileNames [list \
          282  +    [file join $temporaryPath SQLite.NET.hhp] \
          283  +    [file join $temporaryPath SQLite.NET.hhc]]
          284  +
          285  +foreach fileName [glob -nocomplain [file join $providerPath *.html]] {
          286  +  lappend providerFileNames $fileName
   165    287   }
   166    288   
   167    289   set patterns(.hhc,1) {<!--This document contains Table of Contents information\
   168    290   for the HtmlHelp compiler\.--><UL>}
   169    291   
   170    292   set patterns(.hhp,1) {Default topic=~System\.Data\.SQLite\.html}
   171    293   
................................................................................
   203    325   set subSpecs(.html,3) {78dfe2yb}
   204    326   set subSpecs(.html,4) {"\1~Overloads.html"}
   205    327   set subSpecs(.html,5) {"\1~Overloads.html"}
   206    328   set subSpecs(.html,6) {"\1~Overloads.html"}
   207    329   set subSpecs(.html,7) {"\1~Overloads.html"}
   208    330   set subSpecs(.html,8) {"\1~Overloads.html"}
   209    331   
   210         -foreach fileName $fileNames {
   211         -  set fileName [file join $path $temporaryPath $fileName]
          332  +foreach fileName $providerFileNames {
          333  +  set fileName [file join $path $fileName]
   212    334   
   213    335     #
   214    336     # NOTE: Make sure the file we need actually exists.
   215    337     #
   216    338     if {![file isfile $fileName]} then {
   217    339       puts stdout "Cannot find file: $fileName"
   218    340       exit 1