home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / htmlcon.zip / HTMLCON.TXT < prev    next >
Text File  |  1995-09-16  |  18KB  |  416 lines
  1.  
  2.                HTMLCon Version 2.2 (September, 1995)
  3.                An HTM(L) to ASCII Document Converter
  4.  
  5.  
  6.                        Satore Township
  7.                        P.O. Box 750836
  8.                    Petaluma, CA 94975-0836
  9.  
  10.              WWW to http://www.crl.com/~mikekell
  11.          FTP to ftp.crl.com/ftp/users/ro/mikekell/ftp
  12.  
  13.       This program may be distributed freely as long as no
  14.       modifications are made to it or this documentation.  We
  15.       ask that you register this program if you find it useful.
  16.       The registration fee of $7.00 (U.S., by check) should be
  17.       mailed to Satore Township at the address given above. If
  18.       you register this program and provide us with your e-mail
  19.       address, we will provide you with the command to eliminate
  20.       the registration request screen which appears when the
  21.       program is initiated.
  22.  
  23.       E-mail to mikekell@crl.com for comments or suggestions.
  24.  
  25.  
  26.                        Acknowledgements
  27.                        ----------------
  28.  
  29. Many of the concepts used in HTMLCon have been suggested by users of the
  30. program.  Particular thanks should go to the following individuals who
  31. made important contributions to HTMLCon:
  32.  
  33.              Claude Grenier (greniec@ere.umontreal.ca)
  34.              Colin Seymour (cseymo@thorn-emi-crl.co.uk)
  35.  
  36. It is not an understatement to say that HTMLCon would not be what it is
  37. today without their patient help and suggestions.
  38.  
  39.  
  40.                        About the Program
  41.                        -----------------
  42.  
  43. HTMLCon converts HTML/HTM files to standard ASCII files, making them ready  
  44. for viewing, editing or printing with standard DOS, OS/2 or Windows tools.  
  45. HTMLCon operates under MSDOS or under any program capable of providing an 
  46. MSDOS session and using COMMAND.COM as a command interpreter.  HTMLCon can
  47. be used in a Windows or WFW environment within a DOS box by clicking on 
  48. the MSDOS icon to start the DOS session and running HTMLCon from its 
  49. directory as discussed in this documentation.  After processing the input 
  50. document, output will be displayed on a viewer or editor of your choice, 
  51. or printed if you choose.
  52.  
  53. HTMLCon recognizes HTML symbology through HTML+ level as of this date.
  54. It will automatically detect HTML files created in either an MSDOS or
  55. UNIX environment and process them correctly.  HTMLCon will attempt to
  56. process the raw HTML file such that the output is as readable as
  57. possible, eliminating unfavorable formatting to every extent practical.
  58.  
  59. A variety of options are available as defined in the control file
  60. (HTMLCON.INI).  The control file is necessary for the proper operation 
  61. of HTMLCon.  This file may be modified with any text editor and is
  62. heavily commented to allow you to set various options.
  63.    
  64.  
  65.                             Installation
  66.                             ------------
  67.  
  68. Copy HTMLCON.EXE and HTMLCON.INI to a new directory of your choice.
  69. Now set the environment variable "HTMLCON" to point to the directory
  70. where HTMLCON.INI resides.  This will allow you to run the program
  71. from any location on your system.  For example, if you put HTMLCON.EXE
  72. and HTMLCON.INI in the directory C:\UTILS, use the following command
  73. in your AUTOEXEC.BAT file:
  74.  
  75.                          SET HTMLCON=C:\UTILS
  76.  
  77. Notice that a trailing backslash should not be used with the environment
  78. variable HTMLCON.  Even if HTMLCon is unable to locate the HTMLCON.INI
  79. file it will operate, however none of the important directives in the
  80. HTMLCON.INI file will be used.  If HTMLCon is unable to locate the control
  81. file it will advise of the problem, wait thirty seconds, then proceed
  82. with processing the files you have selected using default values.
  83.  
  84. If you are using HTMLCon in a Windows environment and experience an
  85. out-of-memory condition (usually indicated by HTMLCon failing to process
  86. a large number of input files) you should experiment with the following
  87. variable in the [NonWindowsApp] section of your SYSTEM.INI file:
  88.              
  89.                   CommandEnvSize=1024 (recommended)
  90.  
  91. In the CONFIG.SYS file you should also set your environment size to be
  92. the same as the CommandEnvSize.  For example:
  93.  
  94.                   SHELL=C:\DOS\COMMAND.COM /E:1024
  95.  
  96. This will ensure that HTMLCon is provided sufficient environment space
  97. to process large numbers of HTM/HTML files in a single session.  Also,
  98. it is suggested that you set your DOS environment to at least 1024 bytes
  99. and your FILES argument in CONFIG.SYS to at least 49 in the event you
  100. experience difficulties.  Since HTMLCon can process any number of HTM/HTML
  101. files in a single session, using these suggested settings as a minimum will
  102. allow the program to operate at maximum efficiency and prevent out-of-memory
  103. conditions in most installations.
  104.  
  105. The program is now ready to run.  Source files may be located in any 
  106. directory.  Output files will be created in the directory from which 
  107. HTMLCon was run.  If you are using the optional filter file (HTMLCON.FIL),
  108. it should be located in the same directory as HTMLCON.EXE and HTMLCON.INI.
  109. There are three additional filter files provided with HTMLCon, which are
  110. named ISO.FIL, DOS.FIL and MAC.FIL (with thanks to Claude Grenier).  The
  111. three filter files will allow various conversions of HTML character
  112. sets.  Your favorite FIL file should be renamed to HTMLCON.FIL for use
  113. with HTMLCon.  Please see the self-documenting FIL files for more
  114. information.  In most cases the default HTMLCON.FIL file (DOS.FIL) will
  115. be appropriate.
  116.  
  117.  
  118.                               Operation
  119.                               ---------
  120.  
  121. HTMLCon can be operated in the interactive mode by running "HTMLCon"
  122. from the MSDOS session.  It can also be run without operator
  123. intervention by using the following command line arguments:
  124.  
  125. HTMLCon input_file[.html] output_file[.ASC], or
  126. HTMLCon input_file[.html]
  127.  
  128. A wide variety of user-defined references can be stated in HTMLCON.INI
  129. control file as shown below.  In addition, HTMLCon will provide a short
  130. menu of fundamental options when run in the interactive mode.  Also,
  131. default file extensions can be overridden on the command line for both
  132. input and output files (as well as in the HTMLCON.INI file).
  133.  
  134. HTMLCon has the ability to process multiple input files.  When used
  135. in this mode HTMLCon will automatically assign the file extension '.ASC'
  136. to all output files unless the default file extension has been changed
  137. in the HTMLCON.INI file.  HTMLCon will automatically detect the multiple file
  138. input mode by the presence of a '*' or '?' in the input file name.
  139. For example, suppose that HTMLCon resides in the directory "C:\HTMLCON"
  140. and that there are several HTM/HTML files in the directory "C:\HTMLWRIT"
  141. that you wish to process.  First, move to the "C:\HTMLCON" directory,
  142. then issue the command "HTMLCON C:\HTMLWRIT\*.html".  HTMLCon will
  143. process the files, one-by-one, asking you each time if you wish to
  144. proceed with processing the next file.  When asked if you wish to
  145. proceed, you will be given the following options: Y)es (the default), N)o
  146. (no to this file only), Q)uit (quit processing all files), or A)ll
  147. (process all of the remaining files without pausing).
  148.  
  149. HTMLCon also has the ability to print processed files.  By placing the
  150. following line in the HTMLCON.INI file you are able to activate printing
  151. capabilities:
  152.  
  153.                          useprinter=yes
  154.  
  155. This command will tell HTMLCon to query each file processed to be sent
  156. to LPT1.  You may respond Y)es or N)o to the query (default YES).  If
  157. the above line does not appear in the HTMLCON.INI file then HTMLCon will
  158. not ask about printing files after they are processed.  Please note that
  159. HTMLCon will only use LPT1 and provides no other processing to the
  160. output file.  HTMLCon assumes you have a printer connected to LPT1 if you
  161. use this option and further assumes that the printer is working
  162. properly.
  163.  
  164. Images found in the HTM file are output as [I], HREF references as
  165. [*].  Forms are properly noted and marked, as is preformatted text and
  166. other special HTML symbols.  Derivatives are ignored except when the
  167. text is preformatted and unless the special HTMLCON.FIL file is used.
  168.  
  169. HTMLCon can make use of a special filter file (HTMLCON.FIL in the
  170. default directory) in order to translate HTML ENTITIES of the user's
  171. choice.  Use of this filter is activated by the statement
  172. "usefilter=yes" in the HTMLCON.INI file (see below).  The user may
  173. define up to 300 such filters in the HTMLCON.FIL file.  See the
  174. sample HTMLCON.FIL file for further details.  This is an advanced
  175. feature and is not necessary for non-demanding HTMLCon use.
  176.  
  177. Since the HTML language is evolving continuously, it is possible that
  178. HTMLCon may not recognize certain symbols properly.  Also, since there
  179. is great variation in the creation of HTML documents, it may not be
  180. possible to ideally format all output.  Problems with the output will be
  181. corrected in future versions and we ask that you let us know of any
  182. problems by sending us e-mail, including the original HTML document that
  183. is not being processed correctly.
  184.  
  185.  
  186.                         Special Functions
  187.                         -----------------
  188.  
  189. HTMLCon can produce a special index of URLs (of the http, ftp, gopher
  190. file, and mailto variety) for use with your favorite browser.  If you
  191. elect to enable the "show links" capability of HTMLCon (from either the
  192. interactive menu or the HTMLCON.INI file), the program will create a
  193. special HTML file named HTMLCONR.HTML.  This HTML file will contain
  194. information about the HTML file processed and a listing of URLs which
  195. meet the above definition.  The file lends itself to use with your
  196. favorite WWW browser as a URL index of the files processed by HTMLCon.
  197. It is important to note that additions will only be made to HTMLCONR.HTML
  198. if the "show links" capability is activated.  Also, HTMLCONR.HTML will
  199. grow indefinitely if left unattended.  No special processing of URLs is
  200. done by HTMLCon when creating HTMLCONR.HTML or appending to it.
  201.  
  202. HTMLCon will also calculate cumulative statistics when one or more HTML
  203. files are converted.  Raw statistics are kept in the file HTMLSTAT.DAT
  204. in the HTMLCon default directory.  This file need never be visited by
  205. the user.  The file HTMLSTAT.TXT, also kept in the default HTMLCon
  206. directory, will maintain readable statistics for one or more HTMLCon
  207. translation sessions.  The interactive menu of HTMLCon will let you
  208. review and reset the cumulative statistics maintained by HTMLCon.
  209. Deleting the HTMLCON.DAT file will have the same effect as resetting
  210. the cumulative statistics from the interactive menu.
  211.  
  212.  
  213.                        HTMLCon Control File
  214.                        --------------------
  215.  
  216. The control file should be named HTMLCON.INI and exist in the same
  217. directory as HTMLCon.  Here is a sample, with explanations, of the
  218. control file:
  219.  
  220. # HTMLCon Initialization File (current through version 2.1)
  221. # ---------------------------------------------------------
  222. #
  223. # ----- ABOUT THE HTMLCON.INI CONTROL FILE -----
  224. #
  225. # Lines beginning with a pound sign are considered comments.
  226. # All other lines are considered instructions and must exactly follow
  227. # the format described in this sample file.  Arguments are seperated
  228. # by an equal sign (=) which must not be preceeded or succeeded by
  229. # a space or tab.
  230. #
  231. #
  232. # ----- DEFINING THE OUTPUT LINE LENGTH -----
  233. #
  234. # Define the default point at which HTMLCon should attempt to break a
  235. # line for the output file.  The break is not guaranteed to occur at
  236. # this point, but as close to it as possible to retain the syntax of
  237. # the input line.  Default=72.  You may also change this option when
  238. # running HTMLCon in the interactive mode.
  239. #
  240. #linebreak=75
  241. #
  242. #
  243. # ----- COLLECTING STATISTICS -----
  244. #
  245. # Statistics can be compiled and written to the output file.
  246. # Use of this function does not increase the processing time and it does
  247. # provide some interesting information in the output file.  In addition,
  248. # by uncommenting the "showlinks=yes" command, HTMLCon will write all
  249. # external URL links found in the input file as an appendix to the
  250. # output file.  The "showlinks" option may be changed when running
  251. # HTMLCon in the interactive mode.
  252. #
  253. statistics=yes
  254. #showlinks=yes
  255. #
  256. #
  257. # ----- VIEWING OR PROCESSING THE OUTPUT FILE AUTOMATICALLY -----
  258. #
  259. # You may launch another program after HTMLCon finishes its work.  This
  260. # may be an ASCII file viewer, editor, or whatever.  The launched program
  261. # must be able to take the output file name as an argument.  In order to
  262. # accomplish this you must provide the FULL PATH to your program.  This
  263. # is a handy function to allow you to automatically and immediately see
  264. # the results of the HTMLCon conversion process.
  265. #
  266. #launchprog=c:\utils\list.com
  267. #
  268. #
  269. # ----- FINDING AND REPLACING THINGS -----
  270. #
  271. # Find and replace:  you may specify up to 50 strings to be located in
  272. # the HTML file and replaced in the ASCII output file.  These will be a
  273. # direct replacement using the two commands "find=" and "replace=".  Each
  274. # "find" element will be replaced by a "replace" element, therefore you
  275. # cannot have a "find=" statement without a following "replace=" statement.
  276. # To specify leading or ending spaces in a statement, surround the statement
  277. # with quotations (").  The strings cannot exceed 40 characters each.
  278. #
  279. find=" -- "
  280. replace=--
  281. #
  282. # Here is an example replacing all HTMLCon reference symbols [*] with just *.
  283. #
  284. #find=[*]
  285. #replace=*
  286. #
  287. # Or just ignore all references altogether...
  288. #
  289. #find=[*]
  290. #replace=
  291. #
  292. # Some nice find/replace items to make the output look a bit better.
  293. #
  294. # [add whatever you would like here]
  295. #
  296. #
  297. # ----- KEEPING THE AUTHOR'S ORIGINAL FORMATTING -----
  298. #
  299. # You may elect to keep the formatting characteristics of the original
  300. # HTML file intact.  This will preserve white spaces, line breaks, etc. as
  301. # originally constructed by the author of the HTML page.  This option
  302. # can be changed when HTMLCon is run in the interactive mode.
  303. #
  304. #keepformatting=yes
  305. #
  306. #
  307. # ----- IGNORING HTMLCON'S MARKERS IN THE OUTPUT FILE -----
  308. #
  309. # You may choose to have HTMLCon not replace certain HTML constructs
  310. # with its own markers (for example, HTMLCon replaces URL references
  311. # with the symbol [*]).  To have HTMLCon simply ignore its own symbols and
  312. # not reference certain items in the original HTML file, uncomment the
  313. # next line.  This option can be changed when HTMLCon is run in the
  314. # interactive mode.
  315. #
  316. #ignoresymbols=yes
  317. #
  318. #
  319. # ----- PRESERVING HREF MARKERS IN THE OUTPUT FILE -----
  320. #
  321. # You may instruct HTMLCon to preserve all <A HREF...> constructs when
  322. # converting the HTML file.  These references will be preserved intact,
  323. # without modification.  To use this feature, uncomment the next line.
  324. # This option can be changed when HTMLCon is run in the interactive mode.
  325. #
  326. #keephref=yes
  327. #
  328. #
  329. # ----- ELIMINATING ADVERTISEMENTS AND DELAYS -----
  330. #
  331. # Eliminate the advertisements and delays
  332. # [available to registered users only]
  333. #
  334. #
  335. # ----- PRINTING THE OUTPUT FILE ON LPT1 -----
  336. #
  337. # If you would like the option to send the processed file to LPT1
  338. # then uncomment the next line.  This option can be changed when HTMLCon
  339. # is run in the interactive mode.
  340. #
  341. #useprinter=yes
  342. #
  343. # Note that you may only send the processed file to a line printer
  344. # attached to LPT1 and that HTMLCon assumes the printer is connected
  345. # and operating properly.
  346. #
  347. #
  348. # ----- SPEED PROCESSING MULTIPLE FILES -----
  349. #
  350. # Uncomment the following line to tell HTMLCon to NEVER pause for any
  351. # prompt, including the call to your file viewer or other
  352. # post-processor.  This option can be changed when HTMLCon is run in
  353. # the interactive mode.
  354. #
  355. #nopause=yes
  356. #
  357. #
  358. # ----- IGNORING CERTAIN FILE TYPES -----
  359. #
  360. # The following directive lists file extensions which should always be
  361. # ignored by HTMLCon.  If an input file name contains one of these
  362. # extensions than it will never be processed.  Note that the file
  363. # extension must always include the "." in this directive:
  364. #
  365. ignore=.ZIP.EXE.COM.LZH.GIF.LPG.ARC.ASC.SYS.INI.TXT.DOC
  366. #
  367. #
  368. # ----- USING USER-DEFINED FILTERS -----
  369. #
  370. # Uncomment the next directive to have HTMLCon apply a set of filter
  371. # replacements contained in the file HTMLCON.FIL in HTMLCon's default
  372. # directory.  This filter file will find and replace HTML ENTITIES
  373. # in your output file.  See any of the sample *.FIL files included with
  374. # HTMLCon for more information.
  375. #
  376. usefilter=yes
  377. #
  378. #
  379. # ----- CHANGING THE DEFAULT OUTPUT FILE NAME EXTENSION -----
  380. #
  381. # HTMLCon normally uses the default file extension ".ASC" when multiple
  382. # files are processed or the file extension is not specified.  You may
  383. # specify your own default file extension using the following command.
  384. # This file extension MUST be preceeded by a "." and contain no more than
  385. # three characters.
  386. #
  387. #extension=.TXT
  388. #
  389. #
  390. # ----- ADDITIONAL OUTPUT FORMAT OPTIONS -----
  391. #
  392. # In order to compress extra spaces in the output, uncomment this
  393. # command.  To keep the original character spacing, ignore it.  You may
  394. # change this option when running HTMLCon in the interactive mode.
  395. #
  396. #compress=yes
  397. #
  398. #
  399. # ----- USER-DEFINED LINE BREAKS -----
  400. #
  401. # HTMLCon will always search for a space, comma or dash to break a
  402. # line for output purposes.  You may also elect to add other characters
  403. # for which HTMLCon will search to logically break a line.  You may
  404. # specify up to 50 such characters in a single command using the option
  405. # below.  Be careful doing this, however, so that you do not end up with
  406. # illogically-truncated lines in your output.  If HTMLCon does not find
  407. # one of the four characters mentioned above, it will seek out one of the
  408. # characters you itemize in the command below.  The FIRST character it
  409. # finds will cause HTMLCon to break the line if it is within the specified
  410. # margin parameters established using the "linebreak=" command above:
  411. #
  412. breakchars=:;=\|/
  413. #
  414. #
  415. # End of file
  416.