LS 4.1ljr 
                            USER DOCUMENTATION
               Last update: Mon Nov 26 22:53:10 1990 by LJR

-----------------------------------------------------------------------

     LS 4.1ljr - A versatile Amiga directory listing utility.
                 For revision history and changes see ChangeLog.

Copyright (C) 1990, 1991  Loren J. Rittle
Original program upon which ls 4.1ljr is based was written by 
Justin V. McCormick, and placed into the public domain (see notices below).
I am adding the following restriction upon the branch of ls that
I am working on (not really a restriction if you ask me!):

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 4.1ljr, or (at your option)
any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

I can be reached at the following address:
Loren J. Rittle
1008 Landing Rd.
Naperville, IL  60540
(708)420-7942
EMail: lrg7030@uxa.cso.uiuc.edu
       and the MicroTech BBS (708)851-3929


		Thanks Justin for allowing others to add to your fine
		LS program.  Loren J. Rittle 1/4/90
/*
 *	Original Notices by Justin:
 *
 *	  This program is placed in the public domain with the
 *	understanding that the author makes no claims or guarantees with
 *	regard to its suitability for any given application, and that
 *	the author assumes no responsibility for damages incurred by its
 *	usage.  Any resemblance of this program to any other program,
 *	either living or dead, is purely coincidental.
 *
 *	  Feel free to borrow this code and make millions of dollars
 *	from its sale or commercial use, but please give credit where
 *	credit is due.
 *
 *	  Please do not send me money or stolen software!  I enjoy mail,
 *	phone calls, and legitimate software contributions of all kinds.
 *
 *	             Thanks for your encouragement and support,
 *	                      Justin V. McCormick
 *
 *
 *	Justin V. McCormick can be reached via:
 *
 *	  BIX: jmccormick
 *	PLINK: JVM
 *
 *	PHONE: 303-290-8429
 *
 *	USMAIL: 8330 E. Quincy Ave.
 *	        Bldg. C, #312
 *	        Denver CO, 80237
 */

Synopsis:
---------

  Features intelligent columnar listing, versatile sort options,
UNIX-style pattern matching, recursive subdirectory listing,
customized output formatting and much more!

Usage:  ls [-h?acdfklnprstvDFHMNOPRTXY1 <args>] [path] ... (LJRchange)


Installation:
-------------
LS can be put in your C: directory where LIST and DIR are
normally found.  LS can be made resident in your
startup-sequence, but you must set the pure bit on LS after
dearchiving to prevent spurious warnings:

    PROTECT C:LS +P

Or you can ignore the pure bit warning in the startup-sequence:

    RESIDENT >NIL: C:LS PURE
    (resi c:ls  for WShell users! (LJRchange))

The Command Line:
-----------------

  All arguments are optional.  The default action is to give a
short columnar listing, sorted alphabetically, using the current
directory.  Alphabetizing is always case insensitive.

You can group your options together in any order, like this:

    LS -tlr df0:

Or you can have options specified independently:

    LS -t -l -r df0:

However, if you specify several file or path names, the options
will *not* (as opposed to version 3.1 by Justin) (LJRchange) return 
to their default settings between paths.  For example:

    LS -l df0: df1:    - this will cause ls to print the long listing of 
			 df0: then the long listing of df1:

    LS -l df0: -r df0: - This would give you a two listings of df0:, the
                         first one a long listing, and the second one a 
                         reverse sorted long listing.


Options:
--------

  There are many command options for LS.  You can get a quick
reference list of options by typing:

    LS -? or LS -h

Here is the complete list and description of the options:

a   List all entries (LS usually skips those files which have
		      their 'h' protection bit set or their file
		      name's of the form .* (Like unix ls) or 
		      *.info (Because I hate to see the damn things).
		      With the -a option, LS will reveal all entries
		      in a directory) (LJRchange)
c   Show filenotes, implies long listing.
d   Show directory entries only.
k   Do not use ANSI escape codes in output (for colored text).
l   Give long listing. (LJRchange as to how the dates are formatted)
n   Do not sort entries before displaying.
r   Reverse sort direction.
s   Sort entries by size.
t   Sort entries by date.

A   Force listing to flow across a line instead of down a column. (LJRchange)
	For example:
	Without -A option you might see: 
		apple  far    zip
		blue   ghost
		cars   jacks

	But with the -A option you would see:
		apple  blue   cars
		far    ghost  jacks
		zip                              

D   Show directory entries last.
H   Do not print directory headings or subtotals.
I <pattern> (LJRchange)
  Do not show entries that match the given pattern.
  May be given multiple times on a command line.  (As per GNUUnix ls)  

***Removed*** I   Non-interactive short listings, no "MORE" prompt between pages.
(LJRchange was to remove all pagination that was done by LS. So this option
 was obsolete.  If you want pagination of LS output, get a real shell, like
 the WShell.  Then you can say "ls | less" in order to pipe output from ls
 into less to get pagination)

M   Mix directory and file entries together in final output list.
N <date> (LJRChange, now takes date)
    Show entries that are newer than the given date.
O <date> (LJRChange, now takes date)
    Show entries that are older than the given date.
P   Print full pathnames for all entries, implies one entry per line.
R   Recursive listing, descend into subdirectories that matches pattern.
T   Print grand total of all entries.
1   Forces one entry per line of output. Useful when piping ls output to
    other programs. (LJRchange)

  If LS cannot read the current CLI window size, LS assumes the
output is 77 columns by 23 rows.  The following two options let
you control the output page width and length of the short
columnar listing:

X <wide>
  Set short listing page width to the given number of columns.
Y <high>
  Set short listing page length to the given number of rows.

Formatted Output:
-----------------

  For customized output, there is a special option that expects
a format rule as the next "option":

F <format>
  Format output with <format), with the following special symbols:

    %p   Print the protection bits
    %d   Print the date, DD-MM-YY (LJRchange)
    %t   Print the time, hh-mm-ss
    %b   Print the number of filesystem blocks used by this entry.
    %s   Print the number of bytes used by this entry.
    %n   Print the name of the entry.
    %%   Print a percent symbol.
    \n   Print a linefeed.
    \t   Print a tab.
    \\   Print a backslash symbol.

The default format rule that LS uses for long listings looks like this:

    -F "%p %d %t %4b %8s %n\n"

  Any of the format options that begin with the '%' symbol can
have an optional pad count that lets you specify how many
columns to use.  For example:

    -F "%40n\n"

would print each entry name right justified in a field of 40 columns.

  You can use this feature of LS to help create simple batch
command files.  For example, look at this command:

    LS -PF "copy %n RAM:\n" df0:*.h

  This tells LS to perform a listing using full pathnames with a
special format, matching only filenames that end with ".h" in
directory df0:.  Suppose df0:  has the following files in it:

    joe.h  fred.h  pete.h  ted.h

Our example LS command would result in the following list of commands:

    copy df0:fred.h RAM:
    copy df0:joe.h RAM:
    copy df0:pete.h RAM:
    copy df0:ted.h RAM:

We could create a script file from this by redirecting the
output of LS to a temporary file:

    LS >ram:templist -PF "copy %n RAM:\n" df0:*.h
    EXECUTE ram:templist    ;Do the script
    DELETE ram:templist     ;Delete it


Wildcards:
----------

  Wildcards may be used in file names and in the last level of a
directory path name.  The UNIX-style '*' character is used to
match any number of characters, and a '?' matchs any single
character.  If you need to specify a pathname with spaces in it
like "Wombat Soup", you need to put quotes around it.  LS can
process up to 100 separate pathname patterns in per command line.

Here are some simple examples:

    LS df0:*.info      ; List all .info files in df0:
    LS df0:*/*.info    ; List all dirs and .info files in df0:
    LS df0:L*/*.info   ; List dirs that start with 'L' and .info files

  Also, wildcards are helpful when you are trying to avoid showing
certain files with the "-I <pattern>" option.  For instance:

    LS -I *.o        ; List current dir, do not show .o files.
    LS -I *.o df0:   ; Same as above but lists df0: instead.
    LS -I *.o df0:C* ; List entries that start with the letter "c"
                        ; in df0:, but do not list .o files.

---------------------------------------------------------------------
             May all your directory listings be more readable,
                            Justin V. McCormick

                            and Loren J. Rittle