software/tcl/tkunixhelp.html

   1 <html><head><title>Unix help extension for Tk</title></head>
   2 <meta name="description" content="Viewer for compressed html help files,
   3 which can be build from same sources as Microsoft CHM files">
   4 <body>
   5
   6
   7 <h1>Unixhelp extension</h1>
   8
   9
  10 This is pure Tcl extension which allows to create context-sensitive help
  11 for Tk apps from same sources as windows help files (.chm).
  12
  13 <p>
  14 It is designed to be drop-in replacement for Christian Werner's <a href="http://www.ch-werner.de/winhelp/">WinHelp</a> extension.
  15 </p><p>
  16 Goal is to allow authors of cross-platform application to use native
  17 help viewer on Windows system and use same on-line documentation source
  18 (and quite simular interface) for Unix version of application.
  19 </p><p>
  20 It would be ideal if we would be able to use native help viewer on
  21 various MacOS versions as well, but I don't have access to any MacOS
  22 machine. Contributions are welcome.
  23
  24 </p><p>
  25 Required Tcl/Tk packages:
  26 </p><ul>
  27 <li>Tcl/Tk version 8.4 or above.
  28 </li><li>htmlparse (from <a href="http://www.sf.net/projects/tcllib">tcllib</a>) - for compiling
  29 help files only. We need version from Tcllib 1.7 and abouve
  30 </li><li><a href="http://www.hwaci.com/sw/tkhtml/">Tkhtml</a> 2.0 and above.
  31 Get it from CVS. Note that you can encounter some problems with Tkhtml
  32 and recent versions of Tcl, especially if build with --enable-thread.
  33 <p>
  34 I've fixed random segfaults in my debian package for TkHtml. Patches are
  35 available in the <a href="http://ftp.45.free.net/pub/debian-cosy/sarge/tcl">repository</a>.
  36
  37 </p></li><li><a href="http://www.sf.net/projects/tclvfs">Tclvfs</a>
  38 </li><li><a href="http://www.sf.net/projects/tcltrf">Trf </a> and <a href="http://www.sf.net/projects/memchan">memchan</a> - to make zip vfs working.
  39 </li></ul>
  40 Debian packages for all these extensions can be found on <a href="http://www.45.free.net/debian/repository/">45.free.net apt
  41 repository</a>
  42 <p>
  43 Apart from the packages mentioned above unixhelp uses tree widget,
  44 derived from <a href="http://www.hwaci.com/sw/tk/index.html">Richard
  45 Hipp's code</a> and notebook widget by<a href="http://www.cs.man.ac.uk/%7Efellowsd/tcl/mwidx.html#notebook">Donal
  46 K. Fellows</a>.
  47 </p><p>
  48 These packages were modified by me, so use included version.
  49
  50 </p><h2>Features</h2>
  51 <h3>Present</h3>
  52 <ul>
  53 <li> Table of contents
  54 </li><li> Keyword index
  55 </li><li> Full text search (uses regular expression, as Unix user expects)
  56 </li><li> Unlimited history
  57 </li><li> Compiler for microsoft html help workshop project files which
  58 creates help files, usable with our viewer.
  59 </li><li> <b>tkhhc</b> and <b>unixhelp </b> tcl command are documented in
  60 standard man pages.
  61 </li><li> Proper i18n using <b>msgcat</b> package. Although only Russian
  62 message catalog is present for now. Contributions are welcome.
  63 </li><li> Image support. If you use Img extension in your application, any
  64 types of images are supported. If not, you are limited to gifs.
  65 </li></ul>
  66 <h3>Missing</h3>
  67 <ul>
  68 <li>Prototype has print button. Should investigate postscript generation
  69 capabilites of recent Tkhtml.
  70 </li><li>Prototype has button to hide/show contents pane
  71 </li><li>It seems to be possible to use chm-files directly rather than
  72 rebuild other format from source. Only thing we need - chmlib-based tcl
  73 vfs, and some code to parse #SYSTEM file.
  74 </li><li>Add separate application to view help file and control it via send
  75 command.
  76 </li></ul>
  77
  78 <h2>Why doesn't unixhelp read .chm files directly</h2>
  79
  80 Just because I cannot now imagine any use for it.
  81 It is just easy to write tclvfs using <a href="http://66.93.236.84/%7Ejedwin/projects/chmlib/">chmlib</a>.
  82 <p>
  83 There exists some opensource code to reconstruct neccessary parts of
  84 project file from binary metainformation file #SYSTEM (see for instance
  85 <a href="http://bonedaddy.net/pabs3/hhm/">chmdeco</a>.
  86 </p><p>
  87 All this code is published under GPL. So we have following situation:
  88 </p><ol>
  89 <li>If we have closed source application, we cannot link chmlib into it
  90 without violate a license. So, better to use something else.
  91 <p>
  92 There exist workaround. You can use <a href="http://www.45.free.net/%7Evitus/ice/tcl/chmcat.tar.gz">external
  93 program</a> to extract information from CHM file, and since it is
  94 external, it can be GPL.
  95 </p></li><li>If we have open source application, it is not a good thing to depend
  96 on proprietary tools for the development, because you actually prohibit
  97 people without this tool to make changes in your program, since they are
  98 unable to document this changes in the help. And opensource <a href="http://bonedaddy.net/pabs3/hhm/">hhm</a> compiler is not mature
  99 enough to produce .chm files compatible with windows help viewer.
 100 </li></ol>
 101 Really only interesting use for direct access to .CHM files under Unix
 102 is standalone reader for .chm files. Many proprietary documentation
 103 is now supplied in this format, and one might want to read it under *nix
 104 system. But not me, I don't have such crap.
 105 <p>
 106 Of course there exist <a href="http://xchm.sf.net/">xCHM</a>
 107 but it has some problems with non-engilsh chm files (it uses not robust
 108 enough algorithm to find out text encoding).
 109 And since it is written on C++ it is hard to understand and fix.
 110 </p><p>
 111 I've written <a href="http://www.45.free.net/%7Evitus/ice/tcl/readsys.tcl">some code</a> to decode metainformation from CHM
 112 #SYSTEM file, which already does more than corresponding xchm code. Code
 113 to convert .hhc and .hhk files is already in <b>tkhhc</b>
 114 </p><p>
 115 If you want to help, you are welcome.
 116
 117 </p><h2>Preparing help file</h2>
 118 <h3>From the sources of Microsoft HTML Help Workshop project</h3>
 119
 120 Just run supplied <b>tkhhc</b> script, specifying you help project file
 121 name and output file name (which should not be same as output name for
 122 .chm file, specified in the project file). It would do following:
 123
 124 <ol>
 125 <li>Extract following information from the Html help workshop (.hhp) project file:
 126 <ul>
 127 <li>Default topic (Default topic = filename.htm)
 128 </li><li>Name of contents table file (Contents file = filename.hhc)
 129 </li><li>Name of keyword index file (Index file = filename.hhk)
 130 </li></ul>
 131 </li><li>write file props.txt which contain following information:
 132 <pre>encoding <i>tcl name of your locale encoding</i>
 133 starttopic <i>filename name of default topic</i>
 134 </pre>
 135 Note that contents of this file would be passed to tcl <b>array
 136 set</b> command.
 137 </li><li>Convert content table file (.hhc) and keyworkd index (.hhk) into
 138 form suitable to unixhelp viewer and write them into
 139 contents.lst and index.lst files
 140 </li><li>collect &lt;META NAME="MS-HAID"&gt; tags from all topics
 141 and write meta.lst file.
 142 </li><li>create zip archive containing all pages listed in [files] section of
 143 help project as well as three files created on steps above. Give it any
 144 name and extension you like.
 145 </li></ol>
 146 <h3>From scratch</h3>
 147 <ol>
 148 <li>Write set of interlinked html pages. It is recommended that they
 149 should have extension .htm rather than html
 150 </li><li>Write props.txt file as described above
 151 </li><li>Write content.lst file
 152 This file contain list of  tcl list in the format
 153 <pre>page-title filename ?list of subnodes?
 154 </pre>
 155 where each element of subnodes lists follow same syntax as toplevel
 156 node. Example
 157 <pre>{Introduction intro.htm}
 158 {"Chapter 1" chap1_preface.htm
 159         {"Section 1.1" chap1_1.htm}
 160         {"Section 1.2" chap1_2.htm}
 161         {"Section 1.3" ""
 162                 {"Subsection 1.3.1" chap1_3_1.htm}
 163                 {"Subsection 1.3.2" chap1_3_2.htm}
 164         }
 165 }
 166 {"Chapter 2" chap2_preface.htm
 167         {"Section 2.1" chap2_1.htm}
 168 }
 169 {"Appendix" appendix.htm}
 170 </pre>
 171 It is possible to use anchors in this file.
 172 </li><li>Write index.lst file. This file has essentially same format, but
 173 typically toplevel nodes, named after keywords, have empty filename and
 174 second level nodes point to real pages (may be with anchors)
 175 </li><li>Pack everything into zip archive
 176 </li></ol>
 177
 178 <h2>Using help from program</h2>
 179 <pre>package require unixhelp
 180
 181 unixhelp <i>window</i> <i>filename</i> ?<i>topic</i>?
 182 </pre>
 183 where <i>window</i> is the toplevel window, whose child would be help viewer
 184 toplevel (typically .), <i>filename</i> and topic (which can be omitted) is either
 185 name of html page inside archive or name of page, accompanied with
 186 anchor name, separated by # sign.
 187
 188 <p>
 189 Subsequentual calls for <b>unixhelp</b> with same filename wouldn't lead
 190 to reloading of the file, so just always call it with full pathna,me
 191 </p><p>
 192 </p><h2>Download</h2>
 193 <a href="tkunixhelp.tar.gz">tkunixhelp.tar.gz</a>
 194 Unpack this archive somewhere in your tcl_packagePath and you'll get
 195 three packages available - unixhelp, noteboook and tree.
 196 <br>Debian package for sarge and all prerequisites are availiable from <a href="http://45.free.net/debian/repository">45.free.net repository</a>.
 197 Note that there are two packages  <b>tkunixhelp</b> and
 198 <b>tkunixhelp-dev</b>. Later contains  <b>tkhhc</b> compiler, which is
 199 not needed just for using applications which employ tkunixhtml help
 200 system.
 201 <p>
 202 Should be installable on both woody and sarge if you take pain of
 203 rebuilding my tkhtml package for woody.
 204 </p><h2>Todo</h2>
 205 <ul>
 206 <li>Make tkhhc support forward slashes as directory  separartors.
 207 </li><li>Document format (or provide tools to create) .hhc and .hhk files
 208 </li></ul>
 209
 210 </body></html>