home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 8 Other / 08-Other.zip / sm2addon.zip / readme.txt < prev    next >
Text File  |  1999-01-28  |  10KB  |  250 lines
  1. SM2ADDON Copyright (c) 1996-99 by Steffen Siebert (sm2addon@SteffenSiebert.de)
  2. ==============================================================================
  3.  
  4.  
  5.   This program is free software; you can redistribute it and/or modify
  6.   it under the terms of the GNU General Public License as published by
  7.   the Free Software Foundation; either version 2 of the License, or
  8.   (at your option) any later version.
  9.  
  10.   This program is distributed in the hope that it will be useful,
  11.   but WITHOUT ANY WARRANTY; without even the implied warranty of
  12.   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13.   GNU General Public License for more details.
  14.  
  15.   You should have received a copy of the GNU General Public License
  16.   along with this program; if not, write to the Free Software
  17.   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  18.  
  19.  
  20. Introduction:
  21.  
  22. The IBM Search Manager/2 is a very powerful tool for easy finding a
  23. document which you remember being on your hard-drive, but have absolutely no
  24. idea, where it is or how it's named.
  25.  
  26. Unfortunately the SM/2 is held secret by the IBM marketing and even
  27. support is hard to get (don't bother to search the Internet for fixes,
  28. just write to the support-staff on Compuserve, Forum IBMDES). But the
  29. tool is rather cheap and the demo looked very well to me, so I
  30. decided to buy and use it.
  31.  
  32. Soon I've found that SM/2 lacks some essential features, making the
  33. program rather useless to me: It can't handle compressed files, the
  34. language of ASCII-files can only specified by filename-extension and
  35. it can't even handle html-files.
  36.  
  37. These functions are rather simple to implement, if you've gotten the
  38. source of the supplied dll's, which SM/2 uses for the OS/2
  39. file-system. But unfortunately IBM didn't gave me the source (yes, I've
  40. asked them), thus I had to reimplement the existing functions. But
  41. after lots of programming and debugging, I finally got a working
  42. replacement for the original dll's and could start writing the new
  43. functions.
  44.  
  45. If you replace the original dll's with mine, you should see no
  46. difference, unless you have gzipped file (with extension .gz) or
  47. RMAIL files (with extension .rmail), which are always handled
  48. by the AddOn DLL's.
  49.  
  50. The other new functions only apply, if you enable them by setting
  51. environment-variables.
  52.  
  53.  
  54. 1. RMAIL Support
  55. ================
  56.  
  57. SM/2 AddOn now supports RMAIL files (aka Babyl Format) used by GNU Emacs
  58. to store mails and news.
  59.  
  60. SM/2 AddOn treats files with extension .rmail like a directory containing
  61. files, where each file correspond to one mail. The name of the virtual
  62. directory is the same as the rmail file, the virtual files are named
  63. after the subject line of the mail they contain.
  64.  
  65. SM/2 AddOn creates a special index file with extension .rmail.rdx
  66. for each RMAIL file to speed up the access to single mails. You can
  67. delete these index files without doing much harm, since SM/2 will
  68. recreate them the next time it indexes the RMAIL file, it just slows
  69. the indexing process down. (Note: if you use SM/2 on several computers
  70. (e.g. at home and at work), you should not copy the index files created
  71. on one system onto another or SM/2 might not index all messages on the
  72. second computer!)
  73.  
  74. If you store mails in several languages into one RMAIL file, SM/2 AddOn
  75. can use a heuristic to determine the language of each mail. Currently
  76. only English and german mails are recognized. If you want this feature,
  77. install the DLL's from the subdirectory "dll.ger" (see 6. Installation
  78. for details). Please note that the creation of the .rmail.rdx file
  79. is much slower when the heuristic is used.
  80.  
  81. For very short mails the heuristic can not determine the language,
  82. the default language is used in this case.
  83.  
  84.  
  85. 2. html-Support
  86. ===============
  87.  
  88. For SM/2 to recognize HTML documents, you need an HTML to ASCII filter
  89. program. There are several programs available, which can do this job.
  90. The program should only expect two parameters, first the name of the
  91. HTML-file, second the name of the ASCII output file. I'm using the UNH
  92. 2.12 HTML stripper by Don Hawkinson.
  93.  
  94. The HTML support is enabled by assigning the name of the filter to the
  95. environment variable SM2_HTML_FILTER. SM/2 then treats files with the
  96. extensions ".htm", ".html" and ".shtml" as HTML files.
  97.  
  98.  
  99. 3. gzip-Support
  100. ===============
  101.  
  102. If you have a large collection of text-files on your hard-disk, you
  103. probably want to store them compressed to save disk-space. The SM/2
  104. AddOn DLL's are linked to the zlib library, thus they can handle
  105. gzipped files without using external tools (like gzip).
  106.  
  107. SM/2 will decompress all files with the extension .gz and treat them
  108. as if they were stored uncompressed on the disk, using the old
  109. filename minus the .gz extension as the new filename.
  110.  
  111.  
  112. 4. Ignore files
  113. ===============
  114.  
  115. Sometimes you have a directory with text-files, which SM2 should index,
  116. but there are also some files, which SM2 should ignore: for example the
  117. graphic files among the HTML-Files you've downloaded from the
  118. www, or the backup files which your favourite editor automaticly
  119. creates.  Just set the environment-variable SM2_IGNORE_EXT to a
  120. semicolon delimited list of file-extensions (including the dot, if it's
  121. a "real" extension), and SM/2 will skip any file with a matching
  122. extension.
  123.  
  124. Example: add "SET SM2_IGNORE_EXT=.gif;.jpg;~" to your config.sys and
  125. SM2 will ignore your GIFs and JPEGs as well as any emacs-backupfile,
  126. which ends with a tilde (note the missing dot!).
  127.  
  128.  
  129. 5. Set file attributes per directory
  130. ====================================
  131.  
  132. If you have a "stupid" text-format like ASCII, the only way to tell
  133. SM2 something about the content (like the language) was to define a
  134. special file-extension (no more than 3 letters!) and rename the file.
  135.  
  136. But now you can write a special resource-file, set the name to the
  137. environment-variable SM2_RC_FILENAME, and SM2 will search the
  138. directories with files to index for this file and treat any text-file
  139. in the same directory according to the rules defined in the
  140. resource-file.
  141.  
  142. If you add "SET SM2_RC_FILENAME=sm2info.rc" to your config.sys and
  143. write a file named sm2info.rc, which contains the following 3 lines:
  144.  
  145. * e ascii
  146. deutsch.txt d ascii
  147. lies.mich d word
  148.  
  149. then SM2 will handle deutsch.txt as german ASCII-File, lies.mich as
  150. german Word-File and every other file as an english ASCII-File.
  151. (Note: SM2 seems to ignore the supplied file-type and determines it by
  152. the file-contents, so even if you declare all files to be ASCII, SM2
  153. will handle files created by word processors correct. I think of it as
  154. a bug, but IBM tells me it's a feature :)
  155.  
  156. The format of the resource file is the following:
  157.  
  158. [<filename>|*] [d|e] [ascii|swriter|word]
  159.  
  160. the filename must not contain any wildcards
  161.  
  162. d is for german language ("deutsch") e is for english language
  163.  
  164. ascii is for ASCII-Files swriter is for Starwriter Files word is for
  165. Word Files
  166.  
  167. If you need support for other languages or want to specify the
  168. codepage, mail me.
  169.  
  170. (You may use any other filename for your resource-files, if you set it to
  171. SM2_RC_FILENAME. But choose a name which is unlikely to match a "real"
  172. document, since SM2 will never index a file with this name)
  173.  
  174.  
  175. 6. Installation
  176. ===============
  177.  
  178. First of all, you should have successfully installed SearchManager/2!
  179.  
  180. Create an empty directory on your harddisk and copy the files ehslscfs.dll
  181. and ehslssfs.dll into it. This release contains two versions of these
  182. dll's, please read section 1 - RMAIL Support, for details on the version
  183. in subdirectory "dll.ger".
  184.  
  185. Unless you use RMAIL files with german _and_ english emails, you should
  186. install the dll's stored in the subdirectory "dll".
  187.  
  188. Add the name of the directory to the LIBPATH statement of the config.sys
  189. and make sure it is in front of the dll-path of SM/2 (x:\sm2\dll).
  190.  
  191. Enable some or all features of the SM2ADDON by adding the environment
  192. variables described before to the config.sys
  193.  
  194. Reboot and run SearchManager/2.
  195.  
  196.  
  197. 7. Deinstallation
  198. =================
  199.  
  200. If you want to remove SM2ADDON, just undo the changes made to the config.sys
  201. during installation, reboot and delete the dll's.
  202.  
  203.  
  204. 8. Source
  205. =========
  206.  
  207. This release includes the complete source.
  208.  
  209. Please read "The Cathedral and the Bazaar" 
  210. (http://sagan.earthspace.net/~esr/writings/cathedral-bazaar/)
  211. if you want to know my motivation to release it.
  212.  
  213. The source is based on the sample code provided by IBM with the SM/2
  214. Toolkit.
  215.  
  216. Currently you need the IBM Visual Age C++ 3.0 compiler to compile the
  217. source.
  218.  
  219. It also compiles with the free EMX 0.9c GCC compiler, but the resulting
  220. DLL's are not working. (If someone manages to build them successfully
  221. with EMX, please send me the patches.)
  222.  
  223. The DLL's are using two libraries, whose source is also included:
  224. zlib 1.1.1 and GNU rx 1.5.
  225.  
  226. To create the DLL's, unzip the file src.zip, go to the src subdirectory
  227. and type "make".
  228.  
  229. If there is any problem, please read the makefile for further information.
  230.  
  231.  
  232. 9. Support
  233. ==========
  234.  
  235. Please read the file sm2addon.faq, which answers several frequently
  236. asked question.
  237.  
  238. SM2ADDON comes without any warranty or support, but if you have problems,
  239. questions or any comments about SM2ADDON, feel free to send me an email
  240. to the following address:
  241.  
  242. sm2addon@SteffenSiebert.de
  243.  
  244. For further informations on SM2ADDON, please visit it's homepage at
  245.  
  246. http://www.SteffenSiebert.de/sm2/index.html
  247.  
  248. You can register the page to receive email on new releases.
  249.  
  250.