home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / programs / textual / text2html / !Text2Html / !Help < prev    next >
Encoding:
Text File  |  1997-12-18  |  6.0 KB  |  137 lines
  1. .-----------.
  2. |== == == / |               .--------------.
  3. |== ==== / /|               ¦  !Text2Html  ¦ v 0.17
  4. |=== == / / |-----.         '--------------'
  5. |== == /_/ =|     |
  6. |==== // == |     V       Converts a text file into
  7. '-----------/-----------. an HTML page; changes all
  8.      |      |   =====   | occurrences of  "&<>  etc
  9.      |      |_ ---------| to the appropriate entity,
  10.      '----->|*¯-. ======| similarly for top-bit-set
  11.             |•*·*\ =====| characters.
  12.             |*•*·*| ====|
  13.             '-----------' Please read Instructions!
  14.                           ⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩⇩
  15.  What it’s for:
  16.  =============
  17.  This is not supposed to be a WYSIWIG web-authoring package, because
  18.  it only deals with the textual /content/ of a page, /not/ the fancy
  19.  markup and presentation.
  20.  Its main use will be when you have drafted a significant amount of text,
  21.  possibly using all the keyboard and Alt accented characters, and wish to
  22.  put that up on your site as a Web Page:  there will be a number of
  23.  characters that are illegal (eg top-bit-set, and especially the ASCII
  24.  codes from 127 to 159), and MUST be changed into something acceptable.
  25.  After you have done that, you only have to add markup for headings etc
  26.  (which this program can’t guess at on your behalf;  but which you can
  27.  easily do in any text editor).
  28.  
  29.  To Run the program:
  30.  ==================
  31.  double-click on the !Text2Html icon.
  32.  
  33.  To process a text file:
  34.  ======================
  35.  drag a text-file (max size 64K ¹) on to the icon-bar icon.
  36.  
  37.  Select the options:
  38.  ------------------
  39.  • In the writable icon labelled “<TITLE>” you should type in the title
  40.    that you want the page to have (that appears in the title-bar of a
  41.    browser’s window).
  42.  
  43.  • From the panel labelled “•Bullet”, select how you want ASCII 143 to be
  44.    represented:
  45.    • as a centre-dot thus ·
  46.    • as an asterisk, thus *
  47.    • as a bold lower-case o
  48.    • or as a “List Item”; which PLEASE NOTE will require you to add by hand
  49.      the necessary <UL> and </UL> around them afterwards ².
  50.  
  51.  • In the bottom-right writable icon, edit the suggested “leaf name” for
  52.    the resulting file, if it is not to your liking ³.
  53.  
  54.  Create the HTML file:
  55.  --------------------
  56.  Drag the HTML-file icon into the directory you want it to go in.
  57.  The conversion now actually takes place, and you get a progress window
  58.  while it is happening.
  59.  
  60.  What you finish up with:
  61.  =======================
  62.  All reserved characters and top-bit-set characters in the original text
  63.  are replaced by entities (such as < for < and © for ©).
  64.  
  65.  A spirited guess is made as to where you meant deliberate line-breaks
  66.  or new paragraphs, and <BR> and <P> tags respectively are inserted
  67.  (actually, it’s a bit over-zealous with <BR> tags, so you may want or
  68.  need to take a few out afterwards).
  69.  
  70.  It will “top-and-tail” the output document with some <HTML>, <HEAD>,
  71.  <TITLE> & <BODY> tags, and </BODY></HTML> tags:
  72.  
  73.  this means the output file should be a valid HTML page/document
  74.  (although you will still need to add “presentational” markup yourself).
  75.  
  76.  Errors and warnings:
  77.  ===================
  78.  You will get an error if the incoming file is larger than 64K ¹.
  79.  
  80.  You will get an error if the incoming file is not a text-file (&FFF).
  81.  
  82.  You will get a warning if you try to drag in another text-file
  83.  before you’ve processed the last one.
  84.  
  85.  You will get a warning if you try to save over an already-existing file.
  86.  
  87.  
  88.  
  89.  Notes:
  90.  =====
  91.  ¹ If you need to process text files longer than 64K, you will have to
  92.  hack the program by loading !RunImage into an editor, searching for
  93.  the the occurrence of “maxSz%=64*1024” (probably around line 54),
  94.  and editing the “64” to the number of K you need.
  95.  You MUST ALSO edit the !Run file to increase the WimpSlot by the
  96.  same amount as you’ve increased maxSz%.
  97.  
  98.  ² Yes I know the program could have automatically inserted a <UL>
  99.  immediately before the first <LI>;  but there’s no way it can be sure
  100.  how to recognise the “last” <LI> item to be followed by </UL>:  a list
  101.  item /could/ be several sentences or even paragraphs,  and/or you might
  102.  have intended to finish one list and immediately start another!
  103.  So tough, you have to tidy that up yourself  ;-)
  104.  
  105.  ³ One little “feature” you might spot:  The suggested save leaf-name is
  106.  derived from the first six characters of the incoming leaf-name, plus the
  107.  extension “/html”;  the mental-arithmeticians and mutants among you may
  108.  spot that this adds up to ELEVEN characters total!  If the original leaf
  109.  name was only five characters or less, there will be no problem.  
  110.  If the incoming name was six characters or more, the outgoing name will 
  111.  be one character too long for a 10-character-max filing system:  
  112.  either the name will get truncated, so it finishes up with the shorter 
  113.  extension “/htm”, or else you will have to edit out one of the characters.
  114.  If however you save into something like a !Longfiles or !X-files image- 
  115.  filing system (which allows longer filenames), the eleven characters will 
  116.  be preserved (or you can even lengthen the name up to fifteen characters,
  117.  allowing you to create names such as “DosEight/htm” or “riscos_ten/html”).
  118.  
  119.  More notes for hackers:
  120.  ----------------------
  121.  The text-file “GlyphNames” within the application is used to look up the
  122.  entity names, and/or what to substitute for illegal characters.
  123.  You can:
  124.  • Leave it well alone, and keep your sticky fingers off it;
  125.  • Edit it, eg change entry 144 to ‘‘’ to crash-test a browser;
  126.  • Lose your temper and delete it: the program will still (sort of) work!
  127.  
  128.  
  129.  AFAIK this program should be compatible on anything from RiscOS 2.0 up to
  130.  StrongArm RO3.7  (for all I know, it might even work under Arthur ;-)
  131.  
  132.                                                              John Alldred
  133.                                                          18 December 1997
  134.                                                      john@protovale.co.uk
  135.                                          http://www.protovale.co.uk/john/
  136.                        http://www.argonet.co.uk/users/protovale/john.html
  137.