home *** CD-ROM | disk | FTP | other *** search
/ Fish 'n' More 2 / fishmore-publicdomainlibraryvol.ii1991xetec.iso / disks / disk429.lzh / Dr / Dr.doc < prev    next >
Text File  |  1991-01-10  |  19KB  |  344 lines
  1.  
  2.                                     DR         (release 1.2)
  3.  
  4. What we got here is Yet Another CLI Directory Listing Command, called Dr
  5. (pronounced "dr") because it leaves out icons.  (Like, the missing I in Dir
  6. stands for icon...?  never mind.)  It is a => Fast And Full Featured <=
  7. program which is superior to all of the eight other Amiga directory listers
  8. I've tried.  I couldn't live without it.  Even its half-finished versions
  9. were preferable to Dir.  The features it offers are:
  10.  
  11.   + By default, .info files are not mentioned in the output.  Instead, it
  12.     shows you which files have xxxxx.info files associated with them by
  13.     writing their names in orange.  This makes it much quicker and easier to
  14.     find the information you want, since more of the text on the screen is
  15.     actually relevant.  Any xxxxx.info file that is not associated with a
  16.     regular file or directory is shown normally, e.g. Disk.info.  You can see
  17.     all .info files normally with the -I option.
  18.  
  19.   + It is fully reentrant and reexecutable.  The "pure" bit is set.  Make it
  20.     resident, and AmigaShell has a classy built-in directory command.  (And I
  21.     didn't use any fancy new purifying startup code either.  I made it pure
  22.     the old fashioned way, by writing actual reentrant code in Aztec C.)
  23.  
  24.   + It is about as fast as a directory listing program can possibly be on the
  25.     Amiga.  (Which is still slow.)  Other allegedly fast listing programs are
  26.     often slower (I have one that is sometimes slower than regular Dir), and
  27.     sometimes can't handle some devices, or have errors where others don't,
  28.     and some methods can sometimes fail to turn a floppy drive's motor off.
  29.     Benchmarks: the root directory of the SoundScape disk (v1.4) has 57 files
  30.     and directories.  Dir takes 16 seconds to scan it, eless takes 11,
  31.     fd takes 10, Dir with FSDirs takes 11, and Dr takes 6.5 seconds.  (All
  32.     times include writing output to a CON: window, with FastFonts.)  When I
  33.     created a floppy disk directory with 200 files of varying sizes in it,
  34.     Dir took 60 seconds to scan it, eless took 34 seconds, fd fired up
  35.     "read/write error" requesters, and Dr took 16 seconds.  When using the
  36.     Fast File System, Dir is almost the same speed as Dr, but there's still a
  37.     slight improvement.
  38.  
  39.   + Other commands might be available which will scan a single directory this
  40.     fast, but I bet nothing else does recursive listing of subdirectories as
  41.     fast as Dr does with its -R option.  Even with the Fast File System, the
  42.     speedup is considerable.  Benchmarks:  The (very slow) hard disk I used
  43.     to have, using the Fast File System, took 120 seconds to list with Dir
  44.     Opt A.  Dr -R took 75 seconds.  (The difference got smaller when I
  45.     defragmented the disk.)  A couple of floppy disks with lots of
  46.     fragmentation and complex directory structures gave times of 71 vs 30
  47.     seconds, and 23 vs 10 seconds.
  48.  
  49.   + It arranges the output in a variable number of columns, with spacing
  50.     based on both the length of the longest filenames and the width of the
  51.     window.  It assumes a width of 77 when output is going to some file or
  52.     device other than a CON: window.  By default, it sorts the entries in
  53.     columns, not in rows.  This makes it easier to find things alphabetic-
  54.     ally.  The -H option makes it sort in rows.
  55.  
  56.   + It handles AmigaDOS wildcard patterns, like #?.(c|o) to list all xxxxx.c
  57.     and xxxxx.o files.  And if an actual directory has a name with pattern
  58.     characters in it, like maybe a directory called "Doesn't-work?", it will
  59.     list that directory instead of expanding the pattern.  You can force it
  60.     to expand by adding an extra percent sign to the pattern, so it doesn't
  61.     match the name.
  62.  
  63.   + It can sort alphabetically (the default) or chronologically (newest
  64.     last) with the -C option.
  65.  
  66.   + It has an option (-O) to list each filename on a separate line as a
  67.     complete pathname.  This is useful for generating input to other
  68.     programs, such as ForEvery (included with Dr).  Especially when combined
  69.     with -F (don't show directory names) and -R (show contents of
  70.     subdirectories).  Files are listed in "natural" order (actually reverse
  71.     natural order) when you use this, instead of sorted.  This makes the list
  72.     more efficient for other programs to process, sometimes.
  73.  
  74.   + It can list the size of each file in bytes with the -S option, or list
  75.     complete information about each file and directory (size, protection,
  76.     datestamp, filenote) like the List program with the -L option.  -L is
  77.     automatic if the argument you give it is the name of a single file
  78.     instead of a directory.  The -X option makes it give this information
  79.     about a directory instead of showing that directory's contents.
  80.  
  81.   + The -U option makes it like "du", showing only disk space consumption.
  82.  
  83.   + New: the -P option makes it show only files and directories that have a
  84.     certain protection bit set or clear.
  85.  
  86.   + It uses a significant amount of memory, but if that much isn't available,
  87.     it won't fail.  (Well not TOO often anyway...)  It will simply work less
  88.     efficiently.  When there's only a little extra room, it will work at the
  89.     same speed as Dir.
  90.  
  91.   + And last but certainly not least, it's public domain and the source
  92.     code is provided.  This includes the fast directory scanning routines
  93.     FastExamine and FastExNext, which many programs may find useful since
  94.     they are almost compatible with regular Examine and ExNext.  See the file
  95.     FastExNext.doc.  CREDIT:  the pattern matching code is PatMatch by Jeff
  96.     Lydiatt, available on Fish disk 85.
  97.  
  98. Directory names are listed before file names, separated with a line of
  99. dashes, unless one or the other came up empty.  Each directory name is
  100. followed by a slash.  Only the name itself, not the slash, is orange if it
  101. has an icon.  Things with associated .info files will be marked as such even
  102. if the .info file itself is excluded by the pattern, or by the -D option.  If
  103. you list just a single file, it will check whether it has a .info file,
  104. unless you use the -I option.  It does not check to see whether files with
  105. names ending in .info are actual valid icon files.
  106.  
  107. Note that if the output is not a CON window, it doesn't show you which files
  108. had icons.  It used to precede iconed names with a plus sign, but I concluded
  109. that this was not a win.  If you want to find icons when you're saving the
  110. output, you just gotta use the -I option.  Let me know if you want this
  111. changed.  I heard that the numerous .info files are gonna disappear in
  112. AmigaDOS 2.0 anyway.  That and FFS in ROM will eliminate most of my reasons
  113. for writing Dr in the first place.  Sigh.  So the 2.0 version of Dr might
  114. be two thirds the size of this one, but not really better than some other
  115. programs.  Damn, a lot of the work I did in 1989 is turning out to be wasted.
  116. It would have been less wasted of course if I had gotten this thing out the
  117. door a year earlier ...  "Dr:  the Video Toaster of directory listers."
  118.  
  119. Pattern wildcard characters are currently only recognized at the end of
  120. a pathname (that is, after the last slash or colon if any); you can't yet go
  121. "Dr #?/src/#?.c" to find all .c files in subdirectories named src.  This
  122. ability will be added someday.  If anybody cares.
  123.  
  124. USAGE:  type Dr followed by zero or more file names, directory names,
  125. patterns, or options.  The options in this version are:
  126.  
  127.     ?   Briefly explain all of the options.
  128.  
  129.     -I  List .info files like normal files instead of marking the other
  130.         files they are associated with.
  131.  
  132.     -S  Show the size of each file in bytes, and (new in release 1.2) totals.
  133.  
  134.     -C  Sort chronologically (newest last) instead of alphabetically.
  135.  
  136.     -H  Sort into rows instead of columns, if more than one column.
  137.  
  138.     -O  Put each filename on a separate line, as a complete pathname.  There
  139.         is no other extraneous output and no sorting.  Overrides -L, -S, and
  140.         -C.  The beginning of the pathname is the directory arg you
  141.         specified, not the absolute path.  (The pathname has a maximum length
  142.         of 300 characters.)
  143.  
  144.     -D  Do not show file names, only subdirectory names.  Cancels -F.
  145.  
  146.     -F  Do not show subdirectory names, only file names.  Cancels -D.
  147.  
  148.     -L  Show sizes, protection bits, datestamps and filenotes like List.
  149.         Overrides -S.  Show total bytes/blocks used.
  150.  
  151.     -X  Show directory args as if they were in a -L listing, instead of
  152.         scanning their contents.  Ignored if -R or a pattern is used. 
  153.     Overrides -F, -D, and -P.
  154.  
  155.     -R  Recursively show contents of all subdirectories.  If you're going to
  156.         descend a whole lot of levels (like more than about nine) you might
  157.         need a bigger stack than the default 4K.  It checks for adequate
  158.     stack before entering each subdirectory.  An 8K stack would let you
  159.     go about 40 levels deep.
  160.  
  161.     -U  Show only disk space consumed, and a count of files and directories,
  162.         without listing any names.  Overrides -S, -L, -O, and -I.
  163.  
  164.     -P  A bit more complicated than the options above; the letter P may have
  165.     a tilde (~) after it, and immediately after that a letter, one of H,
  166.     S, P, A, R, W, E, or D (lowercase OK).  This letter represents a
  167.     protection bit.  If the tilde is between the P and the letter, Dr
  168.     will show only files for which that protection bit is not set.  If
  169.     there is no tilde it will show only those for which it is set.  For
  170.     instance, to show all "pure" files, use -PP.  To show all files which
  171.     have not been backed up, use -P~A.  Use -P with a space after it to
  172.     cancel earlier -P options, making it ignore protection bits.  For the
  173.     bits R, W, E, and D, "set" means that the bit shows as present when
  174.     you use List or Dr -L.  The bit is actually a zero in this case.  So
  175.     for example -PD means show deletable files, -P~D means show files
  176.     protected from deletion.  You can use ^ instead of ~.
  177.  
  178. Handy trick:  With Dr you might be able to turn Lharc into a hard disk backup
  179. utility!  First go "Dr >Tempfile -orfip~a disk:", which will put a list of
  180. all the files in disk: that have been altered since the last backup into
  181. Tempfile.  Then give the command "Lharc -x -iTempfile a Vol:ArchiveName" and
  182. it will archive all the files named in Tempfile into Vol:ArchiveName.LZH. 
  183. Then you need some means of setting the archive bit on the files you've
  184. archievd ... for that, use my hack ForEvery.  Just go "ForEvery <TempFile
  185. Protect [] +a".  You should make the Protect command resident first.
  186.  
  187. Some other options and features I might add someday:
  188.  
  189.     -G:  Show file's timestamp as age; days and hh:mm:ss before present.
  190.  
  191.     -Anumber (example: -A30):  Show all files dated within the last (number)
  192.     days.  The cutoff point would be midnight before the day (number)
  193.     days ago.  Thus -A0 would show today's files.
  194.  
  195.     -Bnumber:  Show all files more than (number) days old.
  196.  
  197.     -K:  Show the disk addresses (block keys) of files and directories.
  198.  
  199.     Some way to cause a pattern at the end of the path to apply to files in
  200.         all subdirectories scanned.  That is, path/foo#? would now be
  201.         essentially also equivalent to path/#?/foo#? and path/#?/#?/foo#?,
  202.         etc.  Maybe a pattern that ends with :: would act this way.  This
  203.     would implicitly use -R descent.
  204.  
  205.     Along that line ... a pattern starting with ~ would mean, all files and
  206.         directories that do NOT fit the pattern.
  207.  
  208.     Make -P able to make a mask of several bits.
  209.  
  210.     -{formatstring}  Format output sort of like List's LFORMAT option.  In
  211.     the string, maybe \n = newline, \e = escape, \} = }, \\ = \, \d = the
  212.     name of the dir being scanned, \f = the current filename, with a /
  213.     prepended if preceding character not whitespace or : / ".
  214.  
  215.     -[formatstring]  Format output and execute the result as a command instead
  216.         of writing it out, so you won't need ForEvery, which is really just a
  217.     temporary stopgap.  \] = ].
  218.  
  219. You can give several option letters after one dash, like "Dr -ch foo".  The
  220. case of the letters doesn't matter.  Each option affects those files and
  221. directories that come after it on the command line, except that any options
  222. at the end, after the last filename, act as if they were entered at the
  223. beginning.  Example:  "dr foo -s bar" lists directory foo without showing
  224. sizes, and directory bar with sizes shown.  If a directory name begins with a
  225. dash, put quotes around so that it isn't taken as options.  If you give an
  226. option twice, the second one cancels the first.  This means that if you make
  227. an alias like "alias list dr -lc []", you can make it sort alphabetically by
  228. saying "list -c".  Or, you can show directory foo with sizes, and directory
  229. bar without sizes, with the command "Dr -s foo -s bar".  (Note: since options
  230. at the end act like they are at the beginning, "Dr -s directory -s" will show
  231. the directory without the -s option!)
  232.  
  233. When you combine -R with a pattern, the complete contents of those outermost
  234. subdirectories whose names match the pattern will be shown.  If you combine
  235. -R with -D or -F, all subdirectories will be listed, with only the directory
  236. or file contents of each, according to the option, shown.
  237.  
  238. If you give more than one directory/pattern in the command line, each one's
  239. listing will be preceded by the name you gave, written like this:
  240.                               -- name --
  241. unless you use -O in which case the different listings will not be
  242. separated.  If you give no directory or pattern, it lists the current
  243. directory, of course.  Or you can specify the current directory as empty
  244. quotes: "".
  245.  
  246. Note that the usage totals given at the end of a -S, -L, or -U output count
  247. only the files and dirs actually listed.  If some of the files are marked as
  248. having icons, then the blocks used by those .info files are not counted (they
  249. are in the case of -U).  Likewise things excluded by a pattern or -D or -F. 
  250. But the total count of blocks used by all files and directories is given in
  251. parentheses.  If you want complete totals for everything, use the -I option
  252. (if you're using -L and not -U) and don't use -D or -F or a pattern.  Note
  253. that it does not actually count all the blocks in each file, it just guesses
  254. from the file's length.  This is to avoid unnecessary disk access to read
  255. file extension blocks.  There are occasionally files that are bigger than
  256. they look; fake files made to contain bad tracks are often like this.
  257.  
  258. There is another version of Dr which is called Dr-S here.  It is smaller and
  259. slower (and eats less ram as it runs) because it uses regular ExNext instead
  260. of FastExNext.  To make it, compile dr.c with SMALLSLOW defined, and don't
  261. link with fastex.o; with make, just say "make s".  (Use "make d" for the
  262. regular version.)  Dr-S is actually faster in some cases when AddBuffers is
  263. of some use, e.g. if you list the same dir twice on the slow file system.  It
  264. is about 5k bytes smaller than the regular Dr.  Some users might prefer it,
  265. especially those who don't use floppy disks very much.
  266.  
  267. I did not give it a BCPL style argument template for reasons of size.  17k
  268. is plenty for a resident command.  (That's sure a lot bigger than Dir or
  269. List, but it's smaller than both together, and it pretty much replaces both. 
  270. It also replaces du (with the -u option) and Donald Kindred's rls (with
  271. options -orf).)  Maybe I should have used arp.library ... would use less
  272. memory *IF* you would routinely have that library loaded anyway.  I did make
  273. sure that quoted quotes are done with *" instead of Manx's default "", and
  274. that quotes make -options be treated as directory names.
  275.  
  276. The Amiga is now the fourth system I have written a directory lister for.
  277. First was TOPS-20 (one that showed only files that you are the owner of),
  278. next Kaypro II (fast, 2K long, sorted, showed size), third 4.2 BSD Un*#%$!x
  279. (like ls -ls but faster because don't look up group names, just indicate
  280. whether your group).  So this one is like the crowning achievement of a great
  281. career in directory lister writing.  There is now almost no use at all for
  282. any other directory lister, except maybe if you're using the LFORMAT, KEYS,
  283. SINCE, or UPTO options of List (I'll cover these features eventually), or you
  284. actually find Dir's interactive mode to be of any use.  My original goal was
  285. just to produce an adequate alternative that left out .info files; my goal
  286. now is for Dr to be the best available.
  287.  
  288. Dr is in the public domain, written by
  289.  
  290.         bbses: try                      Paul Kienitz
  291.         Winners Circle 415-845-4812     6430 San Pablo ave.
  292.         Triple-A 415-222-9416           Oakland, CA  94608
  293.         FAUG 415-595-2479               USA
  294.  
  295. Feature suggestions and bug reports are appreciated.  I think it's pretty
  296. bulletproof, but there might be some file devices it can't read properly, one
  297. never knows.  Shareware incentive:  anyone who sends in a financial
  298. contribution will receive...  (drum roll) a nice thank-you note.  Which is
  299. more than I've gotten from some of our better known hackers.  If you want the
  300. source and didn't get it with the executable, you should be able to download
  301. it from any of those bbses.
  302.  
  303.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  304.  
  305.               Differences between release 1.2 and release 1.1:
  306.  
  307. -P option was added.
  308.  
  309. My god!  I never noticed that the PatMatch functions I used were not pure! 
  310. In this version I use a modified patmatch.c instead of the original.
  311.  
  312. ForEvery (and Whichever just for the halibut) bundled with Dr.
  313.  
  314. 1.2 has been redone into ANSI C.  It's a bit smaller.
  315.  
  316. By request, the -s option now reports totals like the -l option.
  317.  
  318. The feature wherein recent files would show their dates as "Today" or
  319. "Wednesday" instead of the actual date has been removed.  To get it back,
  320. recompile dr.c with the symbol WEEEEK defined.  See makefile.
  321.  
  322. I wrote, but did not use, code to show directory names in boldface or against
  323. a black background or both instead of above a line of dashes.  See the
  324. makefile for how to compile this way.
  325.  
  326. Oops, the -- Name -- thing between different command line args' output was
  327. not eliminated by -o as documented, in older versions.
  328.  
  329.               Differences between release 1.1 and release 1.0:
  330.  
  331. 1.0 gurued on many device drivers which did not support ETD_READ.  1.1 uses
  332. CMD_READ when ETD_READ fails, and the dumb mistake which caused a guru when
  333. it tried to report the error was fixed.  IF YOU SEE A COPY OF 1.0 GET RID OF
  334. IT, IT'S NO GOOD!
  335.  
  336. 1.1 pays attention to the MaxTransfer mount parameter, and if it is an
  337. integral fraction of the track size it pretends that this fraction is a
  338. "track", otherwise (gotta fix this someday) falls through to ExNext.
  339.  
  340. 1.0 did not check for adequate stack.  1.1 makes sure there is stack each
  341. time it descends another level with the -r option.
  342.  
  343. 1.0 had a small bug in reporting .info files with the -o option.
  344.