home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 3 / goldfish_volume_3.bin / files / util / cli / man / man.doc < prev    next >
Text File  |  1994-03-04  |  9KB  |  360 lines
  1.  
  2.  MAN, written by Kai Iske February 28. 1994
  3.       This is PUBLIC DOMAIN; you may do with it whatever you like
  4.  
  5.  
  6. If you change/republish/delete/sell the program or do anything similar, please
  7. be so kind to keep my name within the program and all the other files, even
  8. though you`re not obliged to, as for the definition of Public Domain
  9.  
  10. MAN  was  written  because  of  the fact that MRMan (by Mark Rinfret) had some
  11. severe  problems  under  OS 2.x (or was it 3.x).  Anyway, I wrote this tool in
  12. order not to have to keep in mind the locations of all the various man pages I
  13. spread across the subdirectories of my MAN:  directory.
  14.  
  15. MAN was written using SAS-C 6.51....
  16.  
  17. !!! Man requires OS 2.x and up to run !!!
  18.  
  19.  
  20. -----------------
  21. What does MAN ???
  22. -----------------
  23.  
  24.  
  25. Well, it is a MAN command similar to the one found on any UNIX System.  Simply
  26. type  "man dummy" and the manual pages (documentation) for a file called dummy
  27. will  be searched for.  If man was successful in finding the appropriate file,
  28. a textviewer will be used to display the documentation.
  29.  
  30. You may configure MAN in order to tell the program where to find the man pages
  31. and  what  text  viewers  to  use.   Wait a minute.  Textviewers ???  Yep, MAN
  32. recognizes the following suffixes as to be part of man pages:
  33.  
  34.   .doc   - Simple ASCII text file
  35.   .man   - Simple ASCII text file
  36.   .guide - Got it, AmigaGuide compatible guide file.
  37.   .dvi   - Whoops, TeX .DVI output
  38.  
  39. So now you know why there are different textviewers.
  40.  
  41.    For example...
  42.  
  43.       You have the documentation for a program called "KCommodity" somewhere
  44.       within your docs directory. The doc file is called "KCommodity.Man". In
  45.       order to get the documentation loaded by man, simply type:
  46.  
  47.           MAN KCommodity
  48.  
  49.       ...and the ASCII textviewer will be used. If your filename ends up with
  50.       .guide ("KCommodity.guide"), MAN assumes it to be a GUIDE file and will
  51.       use the GUIDE Viewer instead...
  52.  
  53.       See, no suffixes needed. MAN will take the first file matching a
  54.       suffix mentioned above.
  55.  
  56.  
  57. You may even add features to MAN using environment variables. Read on...
  58.  
  59.  
  60. ----------------------
  61. How to install MAN ???
  62. ----------------------
  63.  
  64. Copy the main program to a directory within your search path (i.e. C:).
  65.  
  66. Simply set an environment variable, so that MAN knows what to do.
  67. The template for this variable (MANOPT) is as follows:
  68.  
  69.    MANPATHS/K/A,MANVIEW/K/A,MANVIEWAG/K/A,MANVIEWDVI/K/A,MANNRMEXT/K,MANAGEXT/K,
  70.    MANDVIEXT/K,MANNOVIEW/K,MANGETFILE/S,MANBASENAME/S
  71.  
  72.  
  73.   *REMEMBER* to enclose parameters containing spaces by quotes. If you don`t
  74. want to write a file MANOPT to your ENVARC: directory but like to use SetEnv
  75. from within your S:User-StartUp file, use something like this :
  76.  
  77.  
  78.   SetEnv MANOPT "... MANVIEWAG=*"SYS:Utilities/AmigaGuide PUBSCREEN 'Dummy'*""
  79.  
  80. The ellipsis "..." is only meant to shorten the example, of course you have
  81. to add the other (needed) parameters as well. You see, if you want to set a
  82. variable to a string which contains spaces you have to use the special
  83. escape charater *" to force quotes.
  84.  
  85. Required parameters are : MANPATHS, MANVIEW, MANVIEWAG, and MANVIEWDVI
  86.  
  87.  
  88.                              --------------------
  89.  
  90.  
  91. The meaning of the keywords :
  92.  
  93.    MANPATHS    - This option tells man where to look for man pages.
  94.  
  95.    For example...
  96.  
  97.       MANPATHS=MAN:,MAN:CSHDOC|MAN:HPDOCS,MAN:AUTODOCS
  98.  
  99.    You see, you may either use "," or the "|" as seperators between
  100.    directory names.
  101.  
  102.  
  103.  
  104.  
  105.    MANVIEW     - This one is the path (including filename) for the
  106.                  textviewer you wish to use for displaying normal
  107.                  ASCII files.
  108.  
  109.    For example...
  110.  
  111.       MANVIEW=SYS:Utilities/More
  112.  
  113.    REMEMBER: Complete path and filename
  114.  
  115.  
  116.  
  117.  
  118.  
  119.    MANVIEWAG   - This one is used to set the path (and filename) for
  120.                  the AmigaGuide GUIDE-Viewer.
  121.  
  122.    For example...
  123.  
  124.       MANVIEWAG=SYS:Utilities/AmigaGuide
  125.  
  126.    REMEMBER : Complete path and filename
  127.  
  128.  
  129.  
  130.  
  131.    MANVIEWDVI  - This one is used to set the path (and filename) for
  132.                  the DVI-Viewer.
  133.  
  134.    For example...
  135.  
  136.       MANVIEWDVI=TeX:bin/ShowDVI
  137.  
  138.    REMEMBER : Complete path and filename
  139.  
  140.  
  141.  
  142.  
  143.  
  144. Additionally there are six more keywords you may use to add
  145. extensions and functions to man. These are :
  146.  
  147.    MANNRMEXT   - You may use this option to add extensions to the already
  148.                  known, which should be treated (shown) as plain ASCII files.
  149.  
  150.    For example...
  151.  
  152.       MANNRMEXT=.txt|.asc|.dok
  153.  
  154.    Will add these extensions to known ASCII files
  155.  
  156.  
  157.  
  158.  
  159.    MANAGEXT    - Using this option you may add extensions for AmigaGuide
  160.                  files
  161.  
  162.    For example
  163.  
  164.       MANAGEXT=.bla|.blo|.blu
  165.  
  166.    Will add these extensions to known AmigaGuide compatible files
  167.  
  168.  
  169.  
  170.  
  171.    MANDVIEXT   - Using this option you may add extensions for DVI
  172.                  files
  173.  
  174.    For example
  175.  
  176.       MANDVIEXT=.ble|.bli
  177.  
  178.    Will add these extensions to known DVI compatible files
  179.  
  180.  
  181.  
  182.  
  183.    MANNOVIEW   - If a file doesn`t end up with an extension (starting with a
  184.                  dot), MAN will use the predefined ASCII viewer to display
  185.                  such a file. You may change the viewer for such files using
  186.                  this option. Additionally this option may be turned off,
  187.                  when you issue "NONE".
  188.  
  189.    For example
  190.  
  191.       MANNOVIEW=SYS:Utilities/AmigaGuide
  192.  
  193.    Will tell MAN to display files, without extension, using AmigaGuide
  194.  
  195.  
  196.  
  197.  
  198.    MANGETFILE  - If MAN didn`t succeed in finding the required man page
  199.                  it will pop up a FileRequester asking for a file to
  200.                  be loaded. The requester will pop up if you didn`t
  201.                  specify any manpage, too. In this case MAN won`t
  202.                  issue an error, but it will if you omit this keyword.
  203.  
  204.                  Simply add this option to your MANOPT environment var,
  205.                  if you want MAN to pop up a FileRequester.
  206.  
  207.  
  208.  
  209.  
  210.    MANBASENAME - Normally you would call MAN with only a filename/manpage,
  211.                  but if you launch MAN from within (ie) ToolsDaemon, it might
  212.                  be launched with a pathname as well. The pathpart of a
  213.                  manpage will be cut off if you supply this attribute
  214.                  to MANOPT.
  215.  
  216.  
  217.  
  218. A more complete example
  219.  
  220.  
  221.    SetEnv MANOPT "MANPATHS=docs:|guide: MANVIEW=More MANVIEWAG=AmigaGuide
  222.              MANVIEWDVI=ShowDVI"
  223.  
  224.  
  225.  
  226. It is best to place this line within your S:User-StartUp file, or simply edit
  227. a file called MANOPT in your ENVARC: directory containing the parameters. The
  228. copy the file to ENV:, or simply reboot.
  229.  
  230.  
  231.                              --------------------
  232.  
  233.  
  234.  
  235. -----------
  236. Version 1.0
  237. -----------
  238.   - initial release
  239.  
  240.  
  241. -----------
  242. Version 1.1
  243. -----------
  244.   - Accidentially called Exit() instead of exit(), which
  245.     prevented the program to pass the cleanup code of SAS.
  246.     So a lock to the directory was kept and the shell could
  247.     never been left.............
  248.  
  249.  
  250. -----------
  251. Version 1.2
  252. -----------
  253.   - Used MAN as a keyword for the template which prevented MAN
  254.     to accept inputs like "man man".
  255.  
  256.  
  257. -----------
  258. Version 1.3
  259. -----------
  260.   - Added CTRL-C checking
  261.   - Recompiled using SAS 6.50
  262.   - Reduced stack usage
  263.   - Reduced executable size
  264.  
  265.  
  266. -----------
  267. Version 1.4
  268. -----------
  269.   - DOS-Library wasn`t closed
  270.  
  271.  
  272. -----------
  273. Version 1.5
  274. -----------
  275.   - Referenced free memory area
  276.  
  277.  
  278. -----------
  279. Version 1.6
  280. -----------
  281.   - Added MANRMEXT, MANAGEXT and MANNOVIEW options,
  282.     which may be used for extensibility of MAN
  283.     (Somehow suggested by : Michael 'Mick' Hohmann)
  284.  
  285.  
  286. -----------
  287. Version 1.7
  288. -----------
  289.   - All config variables have been moved to a single one,
  290.     which will be parsed just like a CommandLine
  291.     (Suggested by : Michael 'Mick' Hohmann)
  292.  
  293.  
  294. -----------
  295. Version 1.8
  296. -----------
  297.   - Man now correctly handles multi-assigns, since ExAll
  298.     doesn`t....;)
  299.     (Reported by : Jan Hoeydahl)
  300.  
  301.  
  302. -----------
  303. Version 1.9
  304. -----------
  305.   - Recompiled using SAS/C 6.51
  306.   - Added MANGETFILE parameter
  307.     (Requested by : Bill Hogsett)
  308.  
  309.  
  310. ------------
  311. Version 1.10
  312. ------------
  313.   - Mike Barsoom added MANBASENAME attribute for stripping
  314.     off any path names from the manpage name. Useful when
  315.     launching MAN from within (ie) ToolsDaemon
  316.     (Submitted by : Mike Barsoom)
  317.  
  318.  
  319. ------------
  320. Version 1.11
  321. ------------
  322.   - Man will no longer issue an error if you a) didn`t specify a
  323.     manpage and b) set the MANGETFILE attribute for the File
  324.     Requester. This way the Requester will popup if you
  325.     call MAN without any arguments
  326.     (Requested by : Bill Hogsett)
  327.   - The FileRequester will pop up on the default PubScreen now
  328.     (Requested by : Bill Hogsett)
  329.   - The default path for the FileRequester will be set to the
  330.     first Dir of the MANPATHS now
  331.     (Requested by : Bill Hogsett)
  332.   - Support for DVI files added
  333.   - MAN will set the Viewer`s current dir of that where the
  334.     man page resides in
  335.  
  336.  
  337. -------------
  338. Version 1.11a
  339. -------------
  340.   - Man produced an enforcer hit when no manpage was supplied
  341.     (Reported by : Michael van Elst)
  342.  
  343.  
  344. Hope you like it, if not, delete it......
  345.  
  346.  
  347.  
  348. So long,
  349.  
  350.      Kai
  351.  
  352.  
  353.  
  354.  
  355.  --- Kai Iske
  356.  Brucknerstrasse 18, 63452 Hanau, Germany, Tel.: +49-(0)6181-850181
  357.  Z-Net    : KAI@SWEET.ZER            usenet : kai@iske.adsp.sub.org
  358.  internet : iske@informatik.uni-frankfurt.de              IRC:kiske
  359.  ---- Life sucks ----
  360.