home *** CD-ROM | disk | FTP | other *** search
/ BCI NET / BCI NET Dec 94.iso / archives / utilities / guide / adgformat1_3.lha / ADGformat / ADGFormat.doc next >
Encoding:
Text File  |  1994-10-06  |  7.7 KB  |  196 lines
  1.                          -------=====******=====-------
  2.  
  3.                              ADGFormat version 1.3
  4.  
  5.                          -------=====******=====-------
  6.  
  7.                              © 1994 SA Productions
  8.  
  9.                                     Author:
  10.                                Søren Berg Glasius
  11.  
  12.                             1. Overview               
  13.                             2. Distribution           
  14.                             3. Requirements           
  15.                             4. Installation           
  16.                             5. Usage                  
  17.                             6. ToDo                   
  18.                             7. History                
  19.                             8. About SA Productions   
  20.  
  21. 1. Overview
  22. -----------
  23.     
  24.   You  probably have created guide files for all your Autodoc files, just like I
  25. have.   You  probably  also think that the layout ad2ag (or ad2ht) creates looks
  26. pretty ugly, just like me.  This can ofcourse be fixed.  I have seen a couple of
  27. programs,  that does this, but I thought that they were a bit too slow, and also
  28. they  couldn't  be configured as I would like them to be.  Well, then I wrote my
  29. own:  ADGFormat (AutoDocGuideFormat).
  30.  
  31.   What  it  does, excacly, is that it takes one (or more) AutoDoc guidefiles and
  32. process  them,  in  the  way  you have selected.  You can either have it write a
  33. specific  number of columns or you can specify the maximum width you desire.  If
  34. you specify a maximum width, it will calculate the maximum numbers of columns it
  35. can  create  based upon the widest nodename.  If any nodename is longer than the
  36. maximum  width, there will only be created one column and it will be larger than
  37. the  maximum  width.   You  can also select, if it shall write the formated file
  38. back  to  the  original,  or  if  you want it to create a set of formated files.
  39. Finaly you can select the delimiter between the columns (the default is "|").
  40.  
  41.   ADGFormat is coded using C and FLEX (a lexical analyzer generator).  FLEX does
  42. all the parsing of the file.  If you want to see, how FLEX can be used, please
  43. request the source code from the author.  (See sect. 8.)
  44.  
  45.  
  46. 2. Distribution
  47. ---------------
  48.  
  49.   All code is Copyright © 1994 SA Productions.  It may be copied and distributed
  50. so  long  as  no  commercial  profit is made out of it.  it may not be modified,
  51. sold,  or included in any commercial distribution without my written permission.
  52. Public  Domain  vendors  are  not allowed to sell this program for more than the
  53. price  of  a  regular  disk,  which  should  be no more than the equivalent of 5
  54. Dollars.   The  author  takes no responsibility for any loss or damage resulting
  55. from the use of this program.
  56.  
  57.   This  program  is  MailWare.  If you like it, you must mail the author telling
  58. him so.  Please use either email addresses, or optionally write a postcard.  See
  59. sect. 8.
  60.  
  61.  
  62. 3. Requirements
  63. ---------------
  64.  
  65.   This program is written using OS2.04 and has not been (and will not be) tested
  66. under  versions  belov 2.04.  It works on files created by ad2ag (or ad2ht) so I
  67. guess you'll need them as well.  I guess that's about it :-)
  68.  
  69.  
  70. 4. Installation
  71. ---------------
  72.  
  73.   There  is  nothing  to  it.  Just copy ADGFormat to a directory which is in
  74. your path (C: might be the place :-), and then place this guide in your HELP:
  75. directory.
  76.  
  77.  
  78. 5. Usage
  79. --------
  80.  
  81.   ADGFormat  is  very  easy to use.  It has a total of 7 arguments, where only 5
  82. can be used at the same time.  They are:
  83.  
  84.  ADGFormat  Files/M/A,P=Path/K,O=Overwrite/S,W=Width/K/N,
  85.             C=Columns/K/N,D=Delimiter/K,V=Verbose/S
  86.  
  87.   Here's a closer description:
  88.  
  89.    Keyword       | Default       | Description
  90.    --------------+---------------+------------------------------------------
  91.    Files/M/A     | none          | Here you can specify as many files
  92.                  |               | as you want, including normal Amiga
  93.                  |               | wildcards.
  94.    --------------+---------------+------------------------------------------
  95.    P=Path/K      | T:            | Specify the output path (no wildcards)
  96.    --------------+---------------+------------------------------------------
  97.    O=Overwrite/S | off           | If you select "Overwrite" (or short "O")
  98.                  |               | it will write the file back on top of the
  99.                  |               | original file, when it is done parsing.
  100.                  |               | Note: "Overwrite" overrides the "Path"
  101.                  |               | setting.
  102.    --------------+---------------+------------------------------------------
  103.    W=Width/K/N   | 80            | Specify any width larger than 20.
  104.    --------------+---------------+------------------------------------------
  105.    C=Columns/K/N | not specified | If number of columns is specified, this
  106.                  |               | overrides the width setting.
  107.    --------------+---------------+------------------------------------------
  108.    D=Delimiter/K | "|"           | Specify the character you want to use
  109.                  |               | as a delimiter. If no delimiter is
  110.                  |               | desired, specify a delimiter of ""
  111.    --------------+---------------+------------------------------------------
  112.    V=Verbose/S   | off           | Makes output of progress.
  113.    -------------------------------------------------------------------------
  114.  
  115. So if I want to create a formated copy of my guide file for DOS I'll write:
  116.  
  117.   ADGFormat SC:ADGuides/DOS
  118.  
  119.   And  now  I have a formated copy of DOS in my "T:" drawer, which has a maximum
  120. width of 80 chars in the MAIN node.
  121.  
  122. A bit more exotic:
  123.  
  124.   ADGFormat SC:ADGuides/D* SC:ADGuides/I* path RAM: Columns 4 Delimiter "*"
  125.  
  126.   will create a formatted copy of all files starting with "D" and "I" put them
  127. in RAM:  with 4 columns and a delimiter "*".
  128.  
  129. If I don't want an extra copy, but want to replace the original file, I'd write:
  130.  
  131.   ADGFormat SC:ADGuides/* overwrite 
  132.  
  133. Ofcourse you could use the shorthand for the above, for example:
  134.  
  135.   ADGFormat SC:ADGuides/D* P RAM: W 120 D "*"
  136.  
  137. or even:
  138.   
  139.   ADGFormat SC:ADGuides/D* P=RAM: W=120 D="*" V
  140.  
  141. In the above example, the program will output the progress, while parsing.
  142.  
  143.  
  144. 6. Todo
  145. -------
  146.  
  147. If anybody uses this program (that is, if I get any feedback), I'll probably
  148. make some of the following things:
  149.  
  150.     * Adding the option of creating a backlink.
  151.  
  152.     * Adding the option to create a table of contents based upon the Main node
  153.       in each document.
  154.  
  155.     * Adding an index to each file.
  156.  
  157.     * Making a global index file.
  158.  
  159.     * Localizing it.
  160.     
  161.     * Creating a MUI interface, for easy configuration and running.
  162.  
  163. 7. History
  164. ----------
  165.  
  166. Please see the file "ADGFormat.history"
  167.  
  168. 8. About
  169. --------
  170.   
  171.   We're two university students (Anders Hybertz and Søren Berg Glasius) who like
  172. to  program  for  fun  -  oftent  together.  We both studdy computer science and
  173. electronics at the University of Odense, Denmark.
  174.  
  175.   The  program is MailWare, this means, that if you use the program on a regular
  176. basis,  you must send the author an email or a postcard telling him so.  Also if
  177. you  just  took  a  peek at the program, and didn't like it, please tell us why!
  178.  
  179.   If you have any suggestions or improvements, please also mail them to us.
  180.  
  181.   Also bugreports should be send to either one of us.
  182.  
  183.                   You can reach us at the following addresses:
  184.  
  185. Name:       Anders Hybertz                  Søren Berg Glasius
  186. Address:    Åsumvej 95                      Bjørnemosevej 277
  187.             5240 Odense NØ                  5260 Odense S
  188.             Denmark                         Denmark
  189. Phone:      +45 66 10 10 36                 +45 65 91 21 69
  190. Internet:   jeckyl@imada.ou.dk              siera@imada.ou.dk
  191. FidoNet:    2:237/17.12                     2:237/17.11
  192.  
  193. We hope you like the program.....
  194.  
  195. Søren.
  196.