home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / faq2html.zip / readme.txt < prev   
Text File  |  1995-07-21  |  10KB  |  213 lines
  1.  
  2. FAQ2HTML Version 1.0 
  3.  
  4. An OS/2 FAQ to HTML conversion utility
  5.  
  6. This utility will convert a Frequently Asked Questions (FAQ) document in
  7. standard format into a very nice HTML document for use on World Wide Web.
  8. Non-standard format FAQs and other ASCII documents can be converted as
  9. well but with less detailed control over the results.
  10.  
  11. -----------------------------------------------------------------------------
  12. * DISCLAIMER OF WARRANTY, COPYRIGHT NOTICE, AND OTHER SMALL PRINT
  13.  
  14. This program is provided "as is" without warranties, express or implied. Any
  15. risk arising from the use or performance of this program remains with the
  16. user.  In no event shall Network Cybernetics Corporation be liable for any
  17. damages arising from the use or inability to use this software.
  18.  
  19. While we are fairly certain that all the bits which make up this program
  20. are either 1's or 0's, we make no guarantees that they are in the correct
  21. order.
  22.  
  23. This software is Copyright (C) 1995 by Network Cybernetics Corporation, all
  24. rights reserved.
  25.  
  26. This software is not in the public domain.  It may be distributed for free
  27. over computer networks such as The Internet and bulletin board systems. It
  28. may be sold for profit or included as part of a commercial product without
  29. permission from Network Cybernetics Corporation.  This program may be
  30. included in CD-ROM or other file collections provided that the publisher
  31. agrees to provide at least one copy of the collection to Network Cybernetics
  32. Corporation at no charge.  Inclusion of this file in CD-ROM or other file
  33. collections represents agreement to these terms.  If this file is distributed
  34. in any form, all files (including this readme.txt file) from the original
  35. archive must be included with the distribution.
  36.  
  37.  
  38. -----------------------------------------------------------------------------
  39. * SO WHAT IS THIS THING?
  40.  
  41. I maintain a Frequently Asked Questions list that is updated and posted to a
  42. Usenet newsgroup at regular intervals.  Our company now has a Web site and I
  43. have been making my FAQ available via Web.  The trouble is that it takes a
  44. lot of time to convert an ASCII document to a nice-looking HTML document if
  45. it is done by hand.  After having to do this manually for several months, I
  46. decided to look for a program that could do the conversion automatically.
  47. While I found many references to such programs or to people who were working
  48. on them, I never could actually get my hands on one.  It seemed like such a
  49. simple idea that I decided to build my own.  After a couple of days this is
  50. what I came up with.  It's very basic but does the job.  If you'd like to
  51. see an example of what the output looks like, here is the URL of the FAQ
  52. that I process regularly with it:
  53.  
  54.   http://www.ncc.com/ncc/rcfaq.html
  55.  
  56. With a little tweaking, this program can convert most any ASCII document,
  57. even those that are not in the minimal-digest-format used for FAQ files. 
  58.  
  59. This program does a variety of things to assist in creating an HTML version
  60. of your document:
  61.  
  62. 1.  URLs (http://, ftp://, etc) can be converted to working links
  63. 2.  email addresses can be converted to MAILTO links
  64. 3.  You can select to translate character strings into HTML code (i.e., if
  65.     you have items in your document that are delimited by "*" characters
  66.     used as bullets, the program can convert those into bullet icons.
  67. 4.  If your document follows the minimal-digest-format you can provide
  68.     specific pieces of HTML code to wrap various sections of the document
  69.     (i.e., the header should be big characters, the table of contents should
  70.     be preformatted text, etc.)
  71. 5.  FAQs in minimal-digest-format can have horizontal rules or any other
  72.     HTML code you provide as section dividers between topics.
  73. 6.  You can choose to include or leave out any of the minimal-digest-format
  74.     sections such as the Usenet headers or the digest trailer.
  75. 7.  The items in the table of contents will be hypertext linked to the
  76.     associated subject lines in the FAQ (again, this works only if your FAQ
  77.     is in standard format!).
  78.  
  79.  
  80.  
  81. -----------------------------------------------------------------------------
  82. * HOW TO MAKE IT GO
  83.  
  84. FAQ2HTML is a 32bit command line, text mode, OS/2 program.  To run it you
  85. need to specify at least one and possibly two command line options. It may
  86. be invoked as follows:
  87.  
  88.  FAQ2HTML <faqname> <configuration-file-name>
  89.  
  90. You must include the FAQ name but the configuration file name is optional. 
  91. If you do not include it, FAQ2HTML.CFG is loaded and used as the default
  92. configuration file.  If you maintain only one FAQ, the best plan is to
  93. set up the default configuration file the way you want it.  If you will
  94. be maintaining several FAQs, you will need to create a configuration file
  95. for each of them and invoke FAQ2HTML with the appropriate file names.
  96.  
  97.  
  98. The first and easiest way to invoke the program is by typing:
  99.  
  100.  FAQ2HTML faqname.txt
  101.  
  102. The resulting HTML filename will be faqname.html.
  103.  
  104. This will cause the program to process an ASCII text FAQ file with whatever
  105. name you specify.  For example if your FAQ file is called TRIFFID.FAQ then
  106. you would type "FAQ2HTML TRIFFID.FAQ".  When the program is invoked in this
  107. manner, it will load and use the default configuration file which is called
  108. "FAQ2HTML.CFG".
  109.  
  110.  
  111. The second method should be used if you maintain multiple FAQs.  Let's
  112. suppose that you maintain the "Zippy The Pinhead FAQ" and the "Far Side
  113. FAQ".  For the Zippy FAQ, your faq filename is ZIPPY.FAQ and you have
  114. created a configuration file called ZIPPY.CFG (which contains special
  115. Zippy icons, etc.).  For the Far Side FAQ, your filename is FARSIDE.FAQ
  116. and your configuration file is FARSIDE.CFG.  To convert the Zippy FAQ
  117. to HTML format you would type:
  118.  
  119.  FAQ2HTML ZIPPY.FAQ ZIPPY.CFG
  120.  
  121. This will result in a file called ZIPPY.HTML.
  122.  
  123. To convert the Far Side FAQ you would type (you guessed it):
  124.  
  125.  FAQ2HTML FARSIDE.FAQ FARSIDE.CFG
  126.  
  127. This will result in a file called FARSIDE.HTML.
  128.  
  129.  
  130. -----------------------------------------------------------------------------
  131. * OK, IT MAKES SENSE SO FAR BUT WHAT'S THE CONFIGURATION FILE FOR?
  132.  
  133. The configuration file contains information about your FAQ file that will
  134. assist the FAQ2HTML program in making the coversion to HTML look the way
  135. you want it to.  There are few items that must be edited in the config file
  136. before you will be able to run the program such as the name of your FAQ and
  137. the various flags that indicate whether your FAQ file is in minimal digest
  138. format or not.  There are also many additional items in the configuration
  139. that you may edit to change the look of the finished HTML file such as 
  140. adding icons to be used as bullets and rules within the final document.
  141. The default configuration file that comes with the program contains quite
  142. a bit of documentation in the form of comments and, hopefully, this will be
  143. all the information you need to build a custom configuration file for your
  144. FAQ.  By experimenting with the configuration you produce a wide range of
  145. HTML files.
  146.  
  147.  
  148. -----------------------------------------------------------------------------
  149. * HOW TO CONTACT THE AUTHOR            
  150.  
  151. If you have questions, comments, suggestions, flames, etc. about this
  152. program, send them to: srainwater@ncc.com.  Keep in mind that this is
  153. unsupported software - I make no promises that I will fix bugs, add
  154. features, or even have time to answer email.  I do plan to release an
  155. improved version of this program based on user feedback if time allows.
  156.  
  157.  
  158. -----------------------------------------------------------------------------
  159. * BLATANT COMMERCIAL MESSAGE
  160.  
  161. Since this program is being released as freeware rather than shareware, we
  162. aren't asking for any donations or fees to use it.  However, if you really
  163. like the program or want to do something in return, how about buying one
  164. of our products?  NCC is a CD-ROM publisher and, at the time of releasing
  165. this software, we have 4 shipping titles with 3 more on the way.  Our CDs
  166. are primarily collections of software on various topics such as Astronomy,
  167. Artificial Intelligence, Virtual Reality, etc.  Our AI CD-ROM has received
  168. wonderful reviews (including a nice mention in Jerry Pournelle's column).
  169. Our SL9:Impact '94 CD-ROM was recently selected by Sky & Telescope as the
  170. "most comprehensive" collection of SL9/Jupiter impact images and data
  171. around.  Our other CD-ROM have received equally impressive praise.  You
  172. can find out more by sending us email at info@ncc.com or visiting our web
  173. site at:    http://www.ncc.com/ncc/
  174.  
  175. If you do buy a CD-ROM after reading this, be sure to send in the 
  176. registration file for you disc and mention this program so NCC will no
  177. that it's worthwhile to spend time on the development and maintanence of
  178. this and other free software.
  179.  
  180. Thanks!
  181.  
  182.  
  183. -----------------------------------------------------------------------------
  184. * FINAL NOTES
  185.  
  186. The following documents describe the various standards for creating FAQs
  187. that have been developed by the Internet community.  If you currently
  188. maintain a FAQ or are in the process of creating one, you should make
  189. every attempt to follow these guidelines so that your FAQ will be easily
  190. accessible to the maximum number of people and so that it can be handled
  191. by existing software.  Following these guidelines will give you a lot of
  192. benefits besides just compatibility with programs like FAQ2HTML. Many
  193. newsreaders are equipped to handle digest format messages (with features
  194. such as pressing a key to move between sections of the FAQ). Many FAQ
  195. repositories such as the ohio-state site automatically convert FAQ in
  196. this format for easy viewing by Web browsers.  Other programs on the
  197. net can also take advantage of this FAQ format.
  198.  
  199. RFC 1153 (Digest Format):
  200.  
  201.     http://ds.internic.net/rfc/rfc1153.txt
  202.  
  203.  
  204. The Suggested Minimal Digest Format for FAQs:
  205.  
  206.     ftp://rtfm.mit.edu/pub/usenet/news.answers/faqs/minimal-digest-format
  207.  
  208.  
  209. *.answers submission guidelines can be obtained from:
  210.  
  211.     ftp://rtfm.mit.edu/pub/usenet/news.answers/news-answers/guidelines
  212.  
  213.