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