home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 308.lha / Man_v1.2 / man.doc < prev    next >
Encoding:
Text File  |  1980-12-04  |  7.1 KB  |  205 lines
  1. MAN V1.0
  2.  
  3. NAME
  4.     man - display information about topic from manual pages and/or 
  5.           do something even more useful
  6.  
  7. SYNOPSIS
  8.     man <topic>
  9.  
  10. DESCRIPTION
  11.     Man is a program similar to the **ix 'man' command. But as there
  12.     is no documentation of the Amiga commands on disk (except ARP),
  13.     you'll have to build your own information 'data base'.
  14.     Additionally to that you are able to execute files or scripts or
  15.     whatever you like...
  16.  
  17.     To use man, just create a directory (you don't have to, but it
  18.     will for sure help your harddisk [you must be joking, you wanna
  19.     use man on a disk ?]) and assign the logic path 'man:' to it,
  20.     e.g.:
  21.  
  22.         assign man: dh0:manuals
  23.  
  24.     To view files, man uses the program 'less'. You may change this
  25.     any time.
  26.     Then, all you have to do is to copy the files you want to use for
  27.     documentation in it.  To view the file, just type 'man' and the
  28.     name of the file.  You may use any legal AmigaDos filename, but
  29.     remember you're *ALWAYS* in the MAN:-directory, do don't give it
  30.     something like:
  31.     
  32.         man dh0:s/startup-sequence
  33.         
  34.     as the Dos just isn't able to work with a path
  35.     'man:dh0:s/startup-sequence'...
  36.     
  37.     But now to the interesting part of the story, the special
  38.     functions.
  39.     First of all you have to create a file 'manuals' in the
  40.     man:-directory, which contains the line:
  41.     
  42.     START_MAN
  43.  
  44.     at the beginning of the file and the line:
  45.     
  46.     END_MAN
  47.     
  48.     at the end. Any other text before START_MAN and after END_MAN is
  49.     ignored, so you may put any remarks and explanations there... BTW,
  50.     there shouldn't be any empty lines between START_MAN and END_MAN,
  51.     as this might confuse man (I know that's not nice, but it's almost
  52.     11 p.m. now and I don't wanna do anymore on it...).
  53.     
  54.     The next thing you have to do is to make sure how many characters
  55.     16 and 4 is on your local text editor.
  56.     
  57.     Start a new line and type the name your command is to be known as.
  58.     But only use up to 16 characters (well, you may use up to 20, but
  59.     only the first 16 are checked). Then, fill the name up until you
  60.     have the 16 chars (only with spaces!), and add 4 more spaces. To
  61.     use some special manual-path for doc-files, just enter the full
  62.     path to it now. But watch out! No Spaces may be used for this
  63.     option (spaces are allowed for commands!), as a space is used for
  64.     filename delimiter.
  65.     
  66.     If you want to call a command, first type a '!', then the full
  67.     command line. E.g., suppose you have a file 'fishdisks' (a
  68.     complete list of Fred's disks, about 360K) in the dir 'dh0:div.'
  69.     and you want to edit it with an editor named 'ed' (no, please not
  70.     the C=A-Ed !!![Isn't there anybody out there who can convince C=A to
  71.     put a new editor on their disks ?]).  You want to get the list by
  72.     typing 'man fish'. Then you have to enter the following:
  73.  
  74.         fish                !ed dh0:div./fishdisks
  75.             ^ 12 spaces^#### <- plus 4 more spaces
  76.  
  77.     Now, type 'man fish', and voila, an editor should pop up (probably
  78.     saying you don't have a directory 'dh0:div.' or a file
  79.     'fishdisks'...). Works fine, does it?
  80.  
  81.     To do more than one command, just write a small script file that
  82.     does 'em, and execute it via 'execute <file>'.
  83.  
  84.     You may put comments behind the different entries. For normal
  85.     files, a space will do as a delimiter, but for commands you have
  86.     to use the ';' (DOS does the job for me, it's just a standard
  87.     comment then...). If you use filenames with spaces, you'll have to 
  88.     put quotes (") on both sides of the whole path.
  89.  
  90. Using multiple doc files
  91. ------------------------
  92.  
  93.     By using the 'manuals' file, you may print out several doc files
  94.     just by putting the same name in the file twice (or even more),
  95.     e.g.:
  96.     
  97.         man                 man1
  98.         man                 man2
  99.  
  100.     Typing 'man man' will give you both files (I'm used to that from
  101.     our Apollos) (less is started with run, so man doesn't wait for
  102.     less' completion).
  103.  
  104.     A little trick at the end: you can view the 'manuals' file easily
  105.     by typing 'man manuals', as this treats this file as a standard
  106.     doc file.
  107.  
  108. BUGS
  109.     'Man' (no, not  man, but my program) does *not* include any free
  110.     bugs. Bugs may be bought at your local pet shop and placed in the
  111.     program at your own wishes.  Anyway, there may be any number of
  112.     undesireable features (credits to L. Schwab for the last part of
  113.     that...).
  114.  
  115.     Well, I don't think there can be *many* in that short piece of
  116.     code (about 3 hours work all in all), and I didn't find any up to
  117.     now. Anyway, bug reports will be welcome, either eMail or paper.
  118.     As I'm not sure about how much longer I'll have my Bitnet-Account
  119.     [Garry@DGIHRZ01.BITNET], or if you can't reach me via eMail,
  120.     just get out a piece of paper, some special disposable word 
  121.     processor (pencil) and send it to the following address:
  122.     [if you happen to live in West Germany, a call might do to...
  123.     {and if you live in some other corner of this small world and have
  124.     too much money --- I do speak english; if you do too, just give me a
  125.     call!}]) (phew, has anybody got a fourth and fifth kind of
  126.     brackets?) (where did I start with them brackets? Oh yeah, I was
  127.     talking about bug reports).
  128.  
  129.  
  130.     'Normal' Mail address:
  131.  
  132.            Garry Glendown
  133.            Gueldene Kammer 35  (If you speak \TeX, make that 'G\"uldene')
  134.            6430 Bad Hersfeld
  135.            West Germany
  136.            
  137.            Tel.: 06621-73483
  138.  
  139.     or, US mail:
  140.  
  141.             Garry Glendown
  142.             Box R
  143.             APO NY 09141
  144.  
  145.  
  146. -------------------------------------------------------------------
  147.  
  148. Update on June 20th, 1989:
  149.  
  150.     Man V1.1
  151.  
  152.     To tell MAN to check for several paths, insert a line like:
  153.  
  154.         PATH <Path>
  155.             ^
  156.             Space
  157.  
  158.     before the START_MAN command.  Up to 10 paths may be defined (all
  159.     must begin at the first column with the 'PATH ' statement. And don't
  160.     add any extra spaces!).  All these are scanned (as well as the
  161.     'man:' path).  Also, LESS won't open up any more if there is no
  162.     manual you want in the 'man:'-directory. But no checking is done for
  163.     files named in the manuals-file!
  164.  
  165.     Example:
  166.  
  167.         PATH man:autodocs/
  168.                          ^ make sure your path ends with a '/' or a ':'!
  169.  
  170.     To use an other text viewer than 'less', insert the line:
  171.  
  172.         VIEW:<view command>
  173.  
  174.     (before the START_MAN - line!). I'd advise you to use run, runback or
  175.     arun so that multiple available files are shown.
  176.  
  177.     Example:
  178.     
  179.         VIEW:run MoreOrLess
  180.  
  181. -------------------------------------------------------------------
  182.  
  183. Update on August 8th, 1989:
  184.  
  185.     Man V1.2
  186.     
  187.     As of this version, command line arguments are supported:
  188.     
  189.         -v    To use a custom file viewer, add the path and filename after
  190.             the '-v'-option. This overides the default file viewer and
  191.             the one specified in the 'manuals'-file.
  192.  
  193.         -p    adds another path to the paths found in the 'manuals'-file.
  194.  
  195.         -f    If you use this option, only the first file found will be
  196.             displayed.
  197.  
  198.         -d    displays the paths defined by CLI-parameter and in the
  199.             'manuals'-file and the current file viewer.
  200.             No manual will be displayed.
  201.  
  202.     'Man' will now assume that the last string without a '-' in front of
  203.     it is the manual you wish to see.
  204.  
  205.