home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 4 / FreshFish_May-June1994.bin / new / text / hyper / text2guide / text2guide.doc < prev    next >
Text File  |  1994-04-25  |  9KB  |  272 lines
  1. Document Text2Guide documentation
  2.  
  3.                         Text2Guide Documentation
  4.                        ~~~~~~~~~~~~~~~~~~~~~~~~~~
  5.                   Release 03.01 © Stephan Sürken 1993
  6.  
  7.                           Closed 25 Apr 1994
  8.  
  9. 0. Important
  10. =============
  11.  
  12.   I have not done much testing with this new version - just some of
  13.  my own files, and with them, this version did well. So please give
  14.  me details about the fabulous crashes it produces on your machine.
  15.  
  16.  :-)   (misplaced smily).    See `:-)' for silly things.
  17.  
  18. 0.1. Copyright & legal stuff
  19. -----------------------------
  20.  
  21.  Text2Guide 02.XX, 03.XX is © Stephan Sürken 1993, 1994.
  22.  
  23.  Text2Guide is PUBLIC DOMAIN, that means you may copy and use it
  24.  freely, but any gifts are welcome :-)
  25.  
  26.  For any comments, bug reports or similar stuff, contact me (see
  27.  `The Author').
  28.  
  29.  Note the following:
  30.  
  31.   o If you copy it, you MUST copy the whole original archive.
  32.   o You may include this copy on any Public Domain Series, but you
  33.     MUST NOT include it on any disk that is selled for more than
  34.     5 US Dollar (or an equivalent in other currencies).
  35.   o The program must neither be used nor copied by any extremely 
  36.     right wing organisations or persons.
  37.  
  38. 1. Installation
  39. ------------------
  40.  
  41.  Well, it's a CLI-Tool. Copy it anywhere you like, perhaps to "c:".
  42.  
  43.  
  44. 2. Documentation
  45. =================
  46.  
  47.  Text2Guide converts plain ASCII text into AmigaGuide (c) format.
  48.  Sticking to some simple organisation of the text file one can
  49.  simply realize a well structured guide file while still having
  50.  a well readable text file at hand.
  51.  
  52. 2.0. Introduction
  53. ------------------
  54.  
  55.  After searching for a progam of this kind in various ftp nets for
  56.  quite a time (without success), I decided to write it myself.
  57.  
  58.  Here it is!
  59.  
  60. 2.1. Usage
  61. -----------
  62.  
  63.  Text2Guide is a CLI-Tool. Type "Text2Guide" in a Shell and you'll
  64.  get something like:
  65.  
  66.  ---
  67.  Text2Guide 03.01 (25 Apr 1994) © Stephan Sürken
  68.  
  69.  Failed: Can't open input text file!
  70.  
  71.  SYNTAX: Text2Guide <text_file> <guide_file> {+-uwito}
  72.  
  73.  u: ignore Underline of units,      default on.
  74.  w: show Warnings,                  default on.
  75.  i: show progress Information,      default off.
  76.  t: perform node Test,              default on.
  77.  o: force Overwrite of output file, default off.
  78.  ---
  79.  
  80.  That's rather self-explaining, is it not??
  81.  
  82.  See `Options' for exact meaning of the options.
  83.  
  84. 2.2. Text file organization
  85. ----------------------------
  86.  
  87.  There are following rules for the text file:
  88.  
  89.  o The document starts with the keyword "Document" at the beginning
  90.    of a line. The rest of this line will be taken as name of the
  91.    AmigaGuide database.
  92.    In the document you are reading this is in the first line (where
  93.    it normally should be).
  94.  
  95.  o You have to divide your text document in units. These units must
  96.    start at the beginning of a line, and consist of arabic numbers
  97.    divided by dots. Whole hierarchical relations are recognized.
  98.    The rest of the line after this unit number will be taken as
  99.    title of this unit.
  100.    Examples:
  101.  
  102.         1. Einleitung                    -> unit number: "1",
  103.                                             title      : "Einleitung"
  104.         4.2.1. Das Spiel beginnen        -> unit number: "4 2 1",
  105.                                             title      : "Das Spiel beginnen"
  106.  
  107.  o Lines that are neither the first document line nor start with
  108.    a unit number are texts. In texts, there may be links to other
  109.    units, e.g. like `Test Link'. Such links start with an
  110.    "`"-character and end with an
  111.    "'"-character, containing the title of the required unit. Such
  112.    links must be in one line.
  113.  
  114.   Example: Please look at this document as example!
  115.   ~~~~~~~~
  116.  
  117. 2.2.1. Test Link
  118. -----------------
  119.  
  120.  You have clicked on the test link, so you are now in this chapter.
  121.  Simply retrace or click `Text file organization' to get back.
  122.  
  123. 2.3. Options
  124. -------------
  125.  
  126.  These options can be supplied to Text2Guide as arguments after
  127.  the input and output file name. "-" will put off an option,
  128.  "+" will put it on.
  129.  
  130.  Option u: ignore underline lines, default on.
  131.  ~~~~~~~~~
  132.          If this option is on, lines directly following to lines
  133.          with unit numbers are ignored. That is to let you
  134.          underline such units in the plain text file.
  135.  
  136.          For example this unit is defined in the text file by
  137.          these two lines:
  138.  
  139.          2.3. Options
  140.          -------------
  141.  
  142.         If option u would be off, you would see the "-------------"
  143.         at the top of the window in the guide document...
  144.  
  145.  Option w: out warnings, default on.
  146.  ~~~~~~~~~
  147.          If this option is on, warnings are written, else not.
  148.          You should normally not put this off.
  149.  
  150.  Option i: show progress information, default off.
  151.  ~~~~~~~~~
  152.          If this option is on, evrey scanned resp. written unit title
  153.          will be printed while the convertion is in progress.
  154.  
  155.  Option t: test for multiple nodes, default on.
  156.  ~~~~~~~~~
  157.          If this option is on, Text2Guide will perform a test for
  158.          multiple defined nodes (->units) after scanning, and
  159.          produce warnings if multiple nodes are found. Since version
  160.          3.00, two tests will be performed: for multiple node ids
  161.          (the unit numbers, e.g. "1.2.") and for multiple node titles
  162.          (e.g. "Introduction"). Due to the intern test routine, the
  163.          warnings will be printed as often as the multiple id's (resp.
  164.          titles) appear in the text file...
  165.          NOTE that with "t" on and "w" off the test will be performed
  166.          but no warnings written.
  167.  
  168.  Example: Text2Guide Text2Guide.doc Text2Guide.guide -wt +u
  169.  ~~~~~~~~
  170.         This will recompile this document; no warnings will be written
  171.         and not multiple node test will be performed; underlines of
  172.         units will be omitted ("+o" is obsolete as its default is on).
  173.  
  174. 3. History
  175. ===========
  176.  
  177. 3.1. Release 01.00
  178. -------------------
  179.  
  180.  Initial Release. A one-night-work. Undocumented.
  181.  
  182.  Included on the VideoMaxe Release 04.12.
  183.  
  184. 3.2. Release 02.00
  185. -------------------
  186.  
  187.  Major update.
  188.  
  189.  o improved whole program structure...
  190.  o can now convert links in texts
  191.  o multiple node test
  192.  o argument line `options'
  193.  
  194. 3.3. Release 02.01
  195. -------------------
  196.  
  197.  o made lines Text2Guide can process bigger: from 80 chars to 160 chars.
  198.    (had some problems with longer links...)
  199.  o nodes were NOT prolonged by " ", text links were; this should be
  200.    the other way round and is now.
  201.  
  202. 3.4. Release 03.01
  203. -------------------
  204.  
  205.  Date: 25 Apr 1994
  206.  
  207.  Major Update.
  208.  
  209.  o Now all strings are dynamic - no more fussing about with line length,
  210.    no more limitations. Please allow it to be somewhat slower therefore!
  211.  o Now the process is divided into three main parts:
  212.    (i)   Scanning the text file.
  213.    (ii)  Testing integrity.
  214.    (iii) Writing guide file.
  215.  o Nodes are now identified with the unit number, no longer with its title.
  216.    E.g.: "1. Introduction" 
  217.          used to become  "@{" Installation " Link Installation}" [klick no use!]
  218.          will now become "@{" Installation " Link 1.}"           [please klick!]
  219.    Thus, the guide file will be somewhat smaller and you might address a
  220.    node by its number - no matter what label it has. Useful for example
  221.    if you have two similar guide files in two different languages and 
  222.    you want to address the "Introduction" or the "Einleitung", respectively.
  223.    You can now adress it via "1.", no matter what file is used.
  224.  o Added options "i" (-> progress information) and "o". (jo!). Will now
  225.    automatically overwrite existing output file only if "o" is set - else
  226.    you will be requested. Just as it should be!
  227.  o Program can now be interrupted via "ctr-c".
  228.  o Better testing, better output, better warnings. 
  229.  
  230. 4. The Author
  231. ==============
  232.  
  233.  The author is me and I am the author.
  234.  
  235.  Send your gifts to:
  236.  
  237.       |-----------------------------------------------------------|
  238.       |          ADDRESS                                          |
  239.       |···························································|
  240.       |          Stephan Sürken                                   |
  241.       |          Kurt-Schumacher-Str. 34 A 161                    |
  242.       |          D-67663 Ka