home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 5 / FreshFish_July-August1994.bin / bbs / util / qtools-1.1.lha / QTools-1.1 / QuickTools.doc < prev    next >
Encoding:
Text File  |  1994-05-05  |  16.6 KB  |  420 lines
  1. 940505                    QuickTools Release 1.1
  2.          Requires an Amiga with OS compatible with Workbench 2.04.
  3.  
  4.        Copyright © 1994 Ultima Thule Software, All Rights Reserved.
  5.                           Author: Eivind Nordseth
  6.  
  7. This package is NOT public domain, but it is freely distributable. In other
  8. word it is FreeWare. This means that you can copy it and give it to all
  9. your friends, upload it to a BBS or include it in a PD-library. The only
  10. restrictions are: All the files included in this archive must be in their
  11. original form without additions, deletions or modifications of any kind.
  12. QuickTools may not be distributed for profit. Only a nominal charge may be
  13. associated with its distribution. If you want to distribute QuickTools
  14. along with any commercial product you need written permission from the
  15. author. QuickTools is provided "AS IS" without warranty of any kind, and
  16. the author is not responsible for any damage this software may do. (Just in
  17. case :-)
  18.  
  19.  
  20. BACKGROUND:
  21. ~~~~~~~~~~~ 
  22. This package started with Qcd (Quick Change Directory) a few years ago. Qcd
  23. was made because I was tired of writing long pathnames when I should move
  24. around on my harddisk. I had seen a utility on PC which did CD to
  25. directories by writing a part of the directory name (NortonCD). I wanted to
  26. make something like it on the Amiga. Up the years Qcd has been improved and
  27. I got the idea to make a search package for both files and directories. And
  28. here it is: QuickTools.
  29.  
  30.  
  31. QUICKTOOLS PACKAGE
  32. ~~~~~~~~~~~~~~~~~~
  33. This package consist of:
  34. - quicktools.library: This library contains the search-routines for 
  35.                       searching in the database.
  36. - GetQInfo: Scans disks to build up the database of files and directories.
  37. - Qcd: Change directory by searching the database.
  38. - QFind: Find files in the database.
  39. - QMan: Finds documentation files using the database.
  40. - QPop: Commodity for finding files and directories.
  41. - QAsn, Qdir: Scriptfiles using Qcd.
  42.  
  43. If you want to use the search routines in the library from your own
  44. programs, the autodocs and includes for the library are included in this
  45. package.
  46.  
  47.  
  48. INSTALLATION
  49. ~~~~~~~~~~~~
  50. The installation is quite simple. Just copy the library to LIBS: and put
  51. the executables from the bin directory somewhere in your path. Qcd, QFind
  52. and QMan is pure and can be made resident. (If the pure-bit is not set on
  53. your copies, use "Protect" to set it.) If you want QPop to start up every
  54. time the computer boots, you can drop the QPop icon in the WBStartup
  55. drawer. The scriptfiles from the S directory should be in the S: directory.
  56. (If the script-bit is not set on your copies, use "Protect" to set it.) 
  57.  
  58. The default path when storing the datafiles used to hold the database of
  59. files and directories is "S:". If you want to store the datafiles somewhere
  60. else can you set the envirorment variable called "QuickTools/DataPath" to
  61. contain the prefered path. If you change the "QuickTools/DataPath" setting
  62. must you either rerun GetQInfo or copy the old datafiles from the old path
  63. to the new one.
  64.  
  65. The database itself is stored in two files. These are: QuickTools.Dirs and
  66. QuickTools.Files.
  67.  
  68.  
  69. USING WILDCARDS
  70. ~~~~~~~~~~~~~~~
  71. All programs using quicktools.library for searching will allow the use of
  72. standard AmigaDOS wildcards. A '#?' wildcard is automaticaly added to every
  73. file and directory name used for searching. So searching for 'tes' equals
  74. searching for 'tes#?', and searching for wo:sou/qto/#?.c equals searching
  75. for 'wo#?:sou#?/qto#?/#?.c#?'.
  76.  
  77.  
  78. GETQINFO
  79. ~~~~~~~~
  80. Before you can use Qcd, QFind and QPop you must use GetQInfo to gather the
  81. database for the library. GetQInfo should be run on a regular basis to
  82. keep your database up to date.
  83.  
  84. The parameters GetQInfo takes are:
  85. DRIVE/M       - Drives to scan for files and directories.
  86. OLDERTHAN/N/K - The  drives  will only be scanned if the database is older
  87.                 than a given number of days.
  88. DELAY/K/N     - Seconds to delay before scanning drives.
  89. SAVEREQUEST/S - Pop up a requester before saving the database. Use this to
  90.                 ensure the database is not saved when the machine is about 
  91.                 to crash.
  92. EXCLUDEDIR/K  - Exclude pattern for directories. Standard AmigaDOS
  93.                 wildcards. The exclude pattern will be matched with the
  94.                 complete path (with volume name) of all directories found.
  95. EXCLUDEFILE/K - Exclude pattern for files. Standard AmigaDOS
  96.                 wildcards. The exclude pattern will be matched with the
  97.                 complete path (with volume name) of all files found.
  98. USAGE/S       - Show help. Same as using no parameters.
  99.  
  100. Example: 
  101.  GetQInfo System2.0: Work: EXCLUDEDIR Work:xfh EXCLUDEFILE #?.info
  102.   Scans drives System2.0: and Work: for directories and files and stores
  103.   them in the database. The Work:xfh directory (with subdirectories) and
  104.   all files ending with .info will not be added to the database.
  105.  
  106. The OLDERTHAN and DELAY parameters are ment to be used if you have GetQInfo
  107. in your S:User-Startup. Example from my User-Startup:
  108.  
  109.  run >nil: Tools:myC/GetQInfo Sys: Tools: OlderThan 1 Delay 30 SAVEREQUEST
  110.  
  111. Scans Sys: and Tools: and builds a new database if the old database is
  112. older than a day, but wait 30 seconds before scanning. The reason for
  113. waiting is to delay the scanning so it starts after the User-Startup and
  114. WBStratup is done.
  115.  
  116. When using the EXCLUDEDIR and EXCLUDEFILE parameters there is no need to
  117. give the *complete* path in the pattern.
  118. Example:
  119.  EXCLUDEFILE #?/data/bbs0/#?
  120.   This will exclude the following files: 
  121.     Grab:Thor/data/BBS0/MsgData0
  122.     Grab:Thor/data/BBS0/tmp/ThisTo
  123.     Work:Source/bbsread/data/BBS0/MsgData0
  124.     
  125. It is possible to stop GetQInfo while scanning and without destroying the
  126. database by pressing CTRL-C.
  127.  
  128. Arguments to GetQInfo can also be put in the environment variable
  129. "QuickTools/GetQInfoArgs". This variable will be scanned before your
  130. command line arguments. If you put all your drives in this variable you
  131. don't have to write them each time you want to build a new database.
  132.  
  133.  
  134. QFIND
  135. ~~~~~
  136. QFind uses the database to search for files. It takes just a few seconds to
  137. search trough the database, while ordinary file-searching program could use
  138. several minutes.
  139.  
  140. The parameters QFind takes are:
  141. FILE    - Partial path and/or partial filename to search for.
  142. USAGE/S - Show help. Same as using no parameters.
  143.  
  144. Examples:
  145.  QFind qfi
  146.   Search for files in database matching 'qfi#?'.
  147.  
  148.  QFind tes/qfi
  149.   Search for files in database matching 'qfi#?' and with a parent directory
  150.   matching 'tes#?'
  151.  
  152.  
  153. QPOP
  154. ~~~~
  155. QPop is a Workbench commodity which searches for files or directories with
  156. quicktools.library. It's quite simple to use, one just write the search
  157. specification in the string gadget and press enter. All the entries in the
  158. database that match the search spesification are then shown in the the
  159. ListViewGadget. The ListViewGadget can be scrolled with the cursor keys in
  160. combination with shift and ctrl. Located at the bottom of the window are
  161. gadgets labeled 'Hide', 'Cut', 'Copy' and 'Type'. The 'Hide' and 'Quit'
  162. gadgets are standard commodities gadgets. 'Cut' copies the selected entry
  163. in the ListViewGadget to the clipboard and hides QPop. 'Copy' does only the
  164. copying to the clipbroard. To retrive the text from the clipboard, you
  165. could use a tool for pasting text from the clipboard to the input stream
  166. (Snap could be used). It is also possible to paste text to a console window
  167. by using R-Amiga V if the program using the console supports it. The 'Find'
  168. cycle gadget switches between file and directory searching. Pressing return
  169. when the string gadget is not active has the same effect as pressing the
  170. 'Cut' gadget.
  171.  
  172. QPop takes its parameters as tooltypes:
  173. CX_PRIORITY, CX_POPKEY, CX_POPUP - Standard commodities toolstypes.
  174. FINDTYPE - Which searchtype to start with.  Possible values are 'File' and
  175.            'Dir'.
  176.  
  177.  
  178. QCD
  179. ~~~
  180. Qcd is the main reason for making this toolpackage, and is perhaps the CLI
  181. utility I use the most. With Qcd you could change to any directory on the
  182. disks in the database by just giving enough of the name and/or path to
  183. identify it. As the other QuickTools utilities Qcd also support use of
  184. wildcards. Before any searching in the database is done, Qcd tests if the
  185. parameter is a directory relative to the current directory by trying to
  186. change to a directory with the name of the parameter. If this fails the
  187. database will be searched. This means that after you have installed Qcd on
  188. your system you don't have to use the old CD command.
  189.  
  190. The parameters Qcd takes are:
  191. DIR        - Partial path and/or partial name of directory to change to.
  192. SEARCHES/N - Change to the n'th directory matching the DIR parameter.
  193. SHOW/S     - Show the full path and name of the directory Qcd changed to.
  194.              Handy in scriptfiles.
  195. NOGUI      - Don't pop up the match requester.
  196. USAGE/S    - Show help.
  197.  
  198. Special cases of the DIR-parameter:
  199. '-' : Changes to the directory which last was current.  Qcd stores the
  200.       previous current directory in a local environment variable called 
  201.       'QCDLASTPATH'.
  202. '..' '...' '....' :  Go up one [two][three] directory levels.
  203.  
  204. If more than one directory matches the DIR parameter and the SEARCHES
  205. parameter is not used, a requester with all the matched directories will
  206. pop up. This requester can be controlled with the mouse or cursor keys in
  207. combination with shift and ctrl. The return key equals the 'OK' gadget and
  208. the ESC key equals the 'Cancel' gadget.
  209.  
  210. If you set the NOGUI switch and use the same dir parameter more than once,
  211. will Qcd change to the next directory that matches the dir parameter.
  212.  
  213. Examples of how Qcd can be used:
  214. If you want to change to a directory with the following path: 
  215.  
  216. 'Harddisk0:Work/SAS/SelfMade/QuickCD'
  217.  
  218. There are several ways to do it:
  219. You can write: 'Qcd Harddisk0:Work/SAS/SelfMade/QuickCD' (the hard way)
  220. Or           : 'Qcd hard:/sas//quic'
  221. Or           : 'Qcd Self/Quick'
  222. Or           : 'Qcd :///#?cd'
  223. Or           : 'Qcd QuickCD' 
  224. Or just      : 'Qcd qui'   (the fast way)
  225.  
  226. And bang, you are in 'Harddisk0:Work/SAS/SelfMade/QuickCD' !!
  227. Quite nice eh!! 
  228.  
  229. Arguments to Qcd can also be put in the environment variable
  230. "QuickTools/QcdArgs". This variable will be scanned before your
  231. command line arguments. 
  232.  
  233. If you think it will be hard to remember to write Qcd instead of CD, you
  234. can use the alias command 'Alias CD Qcd'.
  235.  
  236.  
  237. QMAN
  238. ~~~~
  239. QMan is a documentation finding utility. By giving a program name will
  240. the QuickTools database be searched for .doc, .man and .guide files
  241. which matches the given program name. The found documentation file can
  242. be shown with a configurable viewer. If more than one documentation file
  243. is found can you choose which one to view in a selection requester
  244. containing the names of the found files.
  245.  
  246. The parameters QMan takes are:
  247. MANPAGE        - The program to find and show the documentation for. 
  248.                  Wildcards are of course allowed. The complete program name
  249.                  isn't necessary either.
  250. GUIDECOMMAND/K - Command to use for viewing guide files. The default
  251.                  command is "Sys:utilities/multiview".
  252. TEXTCOMMAND/K  - Command to use for viewing text files. The default command
  253.                  is "Sys:utilities/multiview".
  254. USAGE/S - Show usage information. Same as using no parameters.
  255.  
  256. Examples:
  257.   QMan QuickTools
  258.     Search for and show documentation file matching
  259.     "QuickTools#?.(guide|doc|man)".
  260.  
  261.   QMan A
  262.     Search for all documentation files with a "a" as the first letter. The
  263.     found files will be shown in the selection requester. (If there are
  264.     more than one.)
  265.  
  266. Arguments to QMan can also be put in the environment variable
  267. "QuickTools/QManArgs". This variable will be scanned before your command
  268. line arguments. You should put the GUIDECOMMAND and TEXTCOMMAND parameter
  269. here. Then you don't have to write them each time you use QMan.
  270.  
  271.  
  272. ENVIRONMENT VARIABLES
  273. ~~~~~~~~~~~~~~~~~~~~~
  274. Since environment variables is used to set your defaults to the most of the
  275. utilities in the QuickTools package I will take a short tutorial.
  276.  
  277. You set a environment variable with the SetEnv command (which comes with
  278. AmigaDos). SetEnv take two arguments: 
  279. NAME   - Name of the environment variable to set. 
  280. STRING - The string to set the environment variable to.
  281.  
  282. Examples:
  283.   SetEnv QuickTools/QManArgs TEXTCOMMAND Tools:myC/XMore
  284.     This will set the command to use for QMAn to show text files to 
  285.     "Tools:myC/XMore".
  286.   
  287.   SetEnv QuickTools/DataPath Data:
  288.     This will set the default path to store the datafiles in.
  289.  
  290. To keep you settings after a reboot, you must copy the changed environment
  291. variables to "ENVARC:" 
  292. This can be done by: "Copy ENV:QuickTools ENVARC:QuickTools"
  293.  
  294.  
  295. SCRIPTFILES
  296. ~~~~~~~~~~~
  297. There are also two scriptfiles which uses the Qcd utility.
  298.  
  299. Qasn:  With this script can you do assigns as quick and easy as CD's with 
  300.        Qcd.
  301. Usage: Qasn [logical_name:] [dir] [SEARCHES]
  302.  
  303. Qdir:  Dir any directory quick and easy.
  304. Usage: Qdir [dir] [SEARCHES]
  305.  
  306. If you want to use Qcd in your own scripts, here are the error codes Qcd
  307. returns:
  308.   OK    (0)  - Everything is ok.
  309.   ERROR (10) - The directory given as parameter doesn't match any
  310.                directorys in the database.
  311.   FAIL  (20) - A serious error has occured. Either are the datafiles 
  312.                missing, directorys in the database doesn't exist or the 
  313.                change to last current dir function failed.
  314.  
  315.  
  316. KNOWN PROBLEMS
  317. ~~~~~~~~~~~~~~
  318. When using Qcd in combination with custom shells, there could be problems
  319. with the path in the prompt update after changing directory. This is *not*
  320. a bug in Qcd. The problem is with custom shells who doesn't use the correct
  321. store for the path used in the prompt. So if you experience this problem
  322. flame the author of the shell and not me :-)
  323.  
  324. One workaround could be:
  325. Rename Qcd to Qcd.bin and use a script like this named Qcd:
  326. <--------------- cut here ----------->
  327. .key DIR,SEARCHES,SHOW,USAGE
  328. Qcd.bin <DIR> <SEARCHES> <SHOW> <USAGE>
  329. cd >NIL:
  330. <--------------- cut here ----------->
  331.  
  332.  
  333. RELEASE HISTORY
  334. ~~~~~~~~~~~~~~~
  335. 930915 - QuickTools Release 1.0:
  336. - quicktools.library 2.43
  337. - GetQInfo 3.120
  338. - Qcd 3.93
  339. - QFind 1.48
  340. - QPop 1.97
  341.  
  342. 940505 - QuickTools Release 1.1:
  343. o quicktools.library 2.46
  344.   - Fallback to default public screen if unable to get lock on public
  345.     screen given by QT_PubScreen.
  346.   - Added 2 tags to SetupMatchData(): QT_ExactLastPart and QT_ExactMatch.
  347.   - Uses the envirorment variable "QuickTools/DataPath" to determine where
  348.     to look for the datafiles.
  349.  
  350. o Qcd 3.112
  351.   - Opens now the selection requester on the active public screen if
  352.     possible.
  353.   - Default arguments for Qcd can be set in envirorment variable
  354.     QuickTools/QcdArgs. These will be parsed before the commandline.
  355.   - New switch: NOGUI. This switch makes Qcd not use the requester when 
  356.     more than one directory matches.
  357.   - New feature when using the NOGUI switch:
  358.     Using the same dir parameter again, change to the next directory 
  359.     witch matches the dirparameter.
  360.  
  361. o QFind 1.51
  362.   - Cleaned up some code.
  363.  
  364. o GetQInfo 3.137
  365.   - Default arguments for GetQInfo can be set in the envirorment variable
  366.     QuickTools/GetQInfoArgs. These will be parsed before the commandline.
  367.   - Will not longer give up scanning when a lock on a directory failes. 
  368.   - New parameters: 
  369.     o OLDERTHAN   - The drives will only be scanned if the database is 
  370.                     older than a given number of days.
  371.     o DELAY       - Seconds to delay before scanning drives.
  372.     o SAVEREQUEST - Pop up a requester before saving the database.
  373.     o EXCLUDEDIR  - Directories not to include in the database.
  374.     o EXCLUDEFILE - Files not to include in the database.
  375.  
  376. o QPop 1.98
  377.   - Uses newlook menues under V39+.
  378.  
  379. o QMan 1.3 (This is not a version of QMan 1.01 released by Torgeir Hovden,
  380.             but it works quite similar)
  381.   - New little utility to use the QuickTools database to search for and 
  382.     show documentation files.
  383.  
  384.  
  385. FUTURE PLANS
  386. ~~~~~~~~~~~~
  387. o Real font sensitive GUI for QPop. (Maybe MUI)
  388. o Possiblilties to keep the database contents for disks when doing a scan
  389.   with GetQInfo.
  390.  
  391.  
  392. THANKS
  393. ~~~~~~
  394. Thanks go to:
  395.  
  396. - All who have emailed me telling how usefull QuickTools is. :-)
  397. - The betatesters.
  398. - Marius Mortensen for thanking me for Qcd in Offline.doc. :-)
  399. - Torgeir Hovden for releasing a utility using quicktools.library. Sorry
  400.   that I stole your idea, but i needed a program to test some new tags :-)
  401. - Ola Fosheim Grøstad, Marius Mortensen and Espen Lyngaas for bug reports
  402.   and/or suggestions on earlier releases of Qcd.
  403. - Amiga for being such a great computer with such a great OS.
  404.  
  405.  
  406. HOW ABOUT SOME FEEDBACK
  407. ~~~~~~~~~~~~~~~~~~~~~~~
  408. Please send donations, bug reports or a list of features you would like to
  409. have included in future releases to:
  410.  
  411. Eivind Nordseth
  412. Herman Krags Vei 17-21
  413. N-7035 TRONDHEIM
  414. Norway
  415.  
  416. Email: eivindno@idt.unit.no
  417.  
  418. You can also get in touch with me at the following BBSes in Norway:
  419. Ultima Thule, Byte Bazzar, Crusaders, Rodeløkka and Mediafoto.
  420.