2009/228 ls enhancements

[Don Cragun]

Hi Jason,
	Please find comments in-line below...

	Cheers,
	Don

On Mon, 18 May 2009 21:21:53 -0500 Jason King wrote:
> To accompany my earlier message, I've attached the updated man page
> changes for the case materials.  These do not reflect any change in
> behavior or architecture, merely making the initial manpage changes
> submitted with the case agree with the results of the case discussion.

Thanks for sending the update.  There are still a few more changes that
need to be made.

>
> A brief summary of the changes from the original ls.txt:
>
> 1. --color invocation is changed to show correct usage of --color[=WHEN].
> 2. Values for --block-size are elaborated (based on pervious message).
> 3. LS_COLOR is fixed to the correct LS_COLORS.
> 4. LS_COLORS and TERM added to the environment variable section.
> LS_COLORS use was already detailed in the color output section, just
> not listed under environment variables.  TERM was an implicit
> dependency due to the use of terminfo, it was added to make the
> dependency explicit.
> -------------- next part --------------
>
>
> User Commands                                               ls(1)
>
>
>
> NAME
>      ls - list contents of directory
>
> SYNOPSIS
> |     /usr/bin/ls [-aAbcCdeEfFghHiklLmnopqrRsStuUwvVx1@]
>      [-/ c | v] [-% atime | crtime | ctime | mtime | all] [file]...

You have added the new short options, but these SYNOPSIS lines give no
indication that new long options have been added that don't have short
option equivalents.  I think the last line above needs to be changed to:
  |        [-/ c | v] [-% atime | crtime | ctime | mtime | all]
  |        [--block-size size] [--color[=when]] [--file-type] [--si]
  |        [--time-style style] [file]...

>
>
> |     /usr/xpg4/bin/ls [-aAbcCdeEfFghHiklLmnopqrRsStuUwvVx1@]
>          [-/ c | v] [-% atime | crtime | ctime | mtime | all] [file]...

The same change needs to be applied to the line above.

>
>
> |     /usr/xpg6/bin/ls [-aAbcCdeEfFghHiklLmnopqrRsStuUwvVx1@]
>          [-/ c | v] [-% atime | crtime | ctime | mtime | all] [file]...

The same change needs to be applied to the line above.

>
>
> DESCRIPTION
 ... ... ...
>
> OPTIONS
 ... ... ...
> |     -U         Output is unsorted.  This overrides the -t and
> |                -s setting.
>

I assume you mean -S rather than -s (-s doesn't affect sorting).
Do you really mean that -U overrides the other options, or does the last
-S, -t, or -U option on the command line determine the behavior.
(Either way is OK, I just want to be sure that the man page correctly
documents the behavior.)  For some options, the behavior of mutually
exclusive options depends on which version of ls you invoke.)

This last sentence probably also needs to be moved to the discussion on
mutually exclusive options below...

 ... ... ...

> |    --file-type
> |         Display a suffix after a file depending on it's type, similar
> |         to the -F option, except * is not appended to executable files.

See notes below about mutually exclusive options.

> |
> |    --si
> |         Display human scaled sizes similar to the -h option, except
> |         powers of 10 instead of powers of 2 are used.

See notes below about mutually exclusive options.

> |
> |    --time-style style
> |         Display times using the specified style.  This does not effect
> |         the times displayed for extended attributes (-%).
> |         Possible values for style are:
> |             full-iso: Equivalent to -E
> |             long-iso: Display in YYYY-MM-DD HH:MM for all files
> |                  iso: Display older files using YYYY-MM-DD and newer files
> |                       with MM-DD HH:MM
> |               locale: Use the default locale format for old and new files.
> |                       This is the default.
> |              +FORMAT: Use a custom format.  Values are the same as described
> |                       in strftime(3c).  If a newline appears in the string,
> |                       the first line is used for older files and the
> |                       second line is used for newer files, otherwise the
> |                       given format is used for all files.
>
>
>   /usr/bin/ls
>      -F    Marks directories with a  trailing  slash  (/),  doors
>            with  a  trailing  greater-than  sign  (>), executable
>            files with a  trailing  asterisk  (*),  FIFOs  with  a
>            trailing  vertical  bar  (|),  symbolic  links  with a
>            trailing "at" sign (@),  and  AF_UNIX  address  family
>            sockets  with a trailing equals sign (=). Follows sym-
>            links named as operands.
>

Note that -F always follows symlinks for /usr/bin/ls and
/usr/xpg4/bin/ls, but /usr/xpg6/bin/ls does not follow symlinks unless
-H or -L is also present.  What does --file-type do?

A new paragraph should be added here to talk about the interactions
between -S, -t, and -U.

What happens if both --file-type and -F are given on the command line?
Does the last one specified win, or does one override the other?

What happens if both --si and -h are given on the command line?  Does
the last one specified win, or does one override the other?

The above four issues need to be addressed here and in the following
sections describing how mutually exclusive options are handled by
/usr/xpg4/bin/ls and by /usr/xpg6/bin/ls.

>
>
>      Specifying more than one of the  options  in  the  following
>      mutually  exclusive pairs is not considered an error: -C and
>      -l (ell), -m and -l (ell), -x and -l (ell), -@ and -l (ell).
>      The  -l  option overrides the other option specified in each
>      pair.
>
>
>      Specifying more than one of the  options  in  the  following
>      mutually  exclusive pairs is not considered an error: -C and
>      -1 (one), -H and -L, -c and -u, and -e and -E,  and  -t  and
>      -S. The last option specifying a specific timestamp (-c, -u,
>      -% atime , -% crtime, -% ctime, and -% mtime) determines the
>      timestamps used for sorting or in long format listings.
>
>   /usr/xpg4/bin/ls
>      -F    Marks directories with a  trailing  slash  (/),  doors
>            with  a  trailing  greater-than  sign  (>), executable
>            files with a  trailing  asterisk  (*),  FIFOs  with  a
>            trailing  vertical  bar  (|),  symbolic  links  with a
>            trailing "at" sign (@),  and  AF_UNIX  address  family
>            sockets  with a trailing equals sign (=). Follows sym-
>            links named as operands.
>
>
>
>      Specifying more than one of the  options  in  the  following
>      mutually  exclusive pairs is not considered an error: -C and
>      -l (ell), -m and -l (ell), -x and -l (ell), -@ and -l (ell),
>      -C and -1 (one), -H and -L, -c and -u, and -e and -E, and -t
>      and -S. The last option specifying a specific timestamp (-c,
>      -u, -% atime , -% crtime, -% ctime, and -% mtime) determines
>      the timestamps used for sorting or in long format listings.
>
>   /usr/xpg6/bin/ls
>      -F    Marks directories with a  trailing  slash  (/),  doors
>            with  a  trailing  greater-than  sign  (>), executable
>            files with a  trailing  asterisk  (*),  FIFOs  with  a
>            trailing  vertical  bar  (|),  symbolic  links  with a
>            trailing "at" sign (@),  and  AF_UNIX  address  family
>            sockets with a trailing equals sign (=). Does not fol-
>            low symlinks named as operands unless  the  -H  or  -L
>            option is specified.
>
>
>
>      Specifying more than one of the  options  in  the  following
>      mutually  exclusive pairs is not considered an error: -C and
>      -l (ell), -m and -l (ell), -x and -l (ell), -@ and -l (ell),
>      -C and -1 (one), -H and -L, -c and -u, and -e and -E, -t and
>      -S. The last option specifying a specific timestamp (-c, -u,
>      -% atime , -% crtime, -% ctime, and -% mtime) determines the
>      timestamps used for sorting or in long format listings.
>
> | COLOR OUTPUT
 ... ... ...
> ATTRIBUTES
>      See attributes(5) for descriptions of the  following  attri-
>      butes:
>
>   /usr/bin/ls
>      ____________________________________________________________
>     |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
>     |_____________________________|_____________________________|
>     | Availability                | SUNWcsu                     |
>     |_____________________________|_____________________________|
>     | CSI                         | Enabled                     |
>     |_____________________________|_____________________________|
>     | Interface Stability         | Committed                   |
>     |_____________________________|_____________________________|
>     | Standard                    | See below.                  |
>     |_____________________________|_____________________________|
>
>
>
>      For all options except -A, -b, -e,  -E, -h, -S, -v, -V,  -@,
>      -/ and -%, see standards(5).

The new non-standard options need to be added to the above list:
 |     For all options except -A, -b, -e, -E, -h, -S, -U, -v, -V, -@,
 |     -/, -%, and all of the long options, see standards(5).

>
>   /usr/xpg4/bin/ls
>      ____________________________________________________________
>     |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
>     |_____________________________|_____________________________|
>     | Availability                | SUNWxcu4                    |
>     |_____________________________|_____________________________|
>     | CSI                         | Enabled                     |
>     |_____________________________|_____________________________|
>     | Interface Stability         | Committed                   |
>     |_____________________________|_____________________________|
>     | Standard                    | See below.                  |
>     |_____________________________|_____________________________|
>
>
>
>      For all options except -A, -b, -e,  -E, -h, -S, -v, -V,  -@,
>      -/ and -%, see standards(5).

The new non-standard options need to be added to the above list:
 |     For all options except -A, -b, -e, -E, -h, -S, -U, -v, -V, -@,
 |     -/, -%, and all of the long options, see standards(5).

>
>   /usr/xpg6/bin/ls
>      ____________________________________________________________
>     |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
>     |_____________________________|_____________________________|
>     | Availability                | SUNWxcu6                    |
>     |_____________________________|_____________________________|
>     | CSI                         | Enabled                     |
>     |_____________________________|_____________________________|
>     | Interface Stability         | Committed                   |
>     |_____________________________|_____________________________|
>     | Standard                    | See below.                  |
>     |_____________________________|_____________________________|
>
>
>
>      For all options except -A, -b, -e,  -E, -h, -S, -v, -V,  -@,
>      -/ and -%, see standards(5).

The new non-standard options need to be added to the above list:
 |     For all options except -A, -b, -e, -E, -h, -S, -U, -v, -V, -@,
 |     -/, -%, and all of the long options, see standards(5).

>
 ... ... ...