.; $Id: d3.rno,v 1.2 1995/10/25 01:02:55 tom Exp $
.req	"d0.req"
.; directory sorting and display format commands
.;
FLIST's most powerful function is the dynamic display formatting,
which permits you to view the directory in a wide variety of
formats.

.hl	Directory Sorting
.x Sorting commands
Using FLIST, you may sort by anything on the screen:
.lm+8
.b.i-4
o	Name fields (e.g., the file name, type and directory-path).
.b.i-4
o	Date fields (the creation, backup, expired and revision dates),
and their major components (day-of-week, hour-of-day).
.b.i-4
o	Size (of the file, in blocks, or its allocated space).
.b.i-4
o	Anything (file protection, format, record attributes).
.b.lm-8
For each display-column on the screen, FLIST defines a normal
and reverse sorting function.
The names for the sorting commands are derived from the sorting
sense and the column type.
Normal sorting commands begin "/S", reverse sorting with "/R".
The remainder of the command is the column-keyword (e.g., "/SDATE").
.;
.hl+1	Sorting and Column Keywords
.x Column keywords
The display column names are chosen to be unique with the first
character (the minimum abbreviation):
.lm+16
.b.i-12;ALLOC
.x Column keywords>ALLOC
.x Sorting commands>/SALLOC, sort by allocation
.x /SALLOC, sort by allocation
.x Sorting commands>/RALLOC, sort by allocation
.x /RALLOC, sort by allocation
	The file allocation, in blocks (generally larger than the file size).
.b.i-12;BACKUP
.x Column keywords>BACKUP
.x Sorting commands>/SBACKUP, sort by BACKUP date
.x /SBACKUP, sort by BACKUP date
.x Sorting commands>/RBACKUP, sort by BACKUP date
.x /RBACKUP, sort by BACKUP date
	The last date on which the file was backed-up.
.b.i-12;CREATED
.x Column keywords>CREATED
.x Sorting commands>/SCREATED, sort by CREATED date
.x /SCREATED, sort by CREATED date
.x Sorting commands>/RCREATED, sort by CREATED date
.x /RCREATED, sort by CREATED date
	The creation date of the file.
.b.i-12;DATE
.x Column keywords>DATE
.x Sorting commands>/SDATE, sort by DATE
.x /SDATE, sort by DATE
.x Sorting commands>/RDATE, sort by DATE
.x /RDATE, sort by DATE
	Any of the file dates, depending on the current display mode
.x DATE-toggle
(see "/D" commands).
.b.i-12;EXPIRED
.x Column keywords>EXPIRED
.x Sorting commands>/SEXPIRED, sort by EXPIRED date
.x /SEXPIRED, sort by EXPIRED date
.x Sorting commands>/REXPIRED, sort by EXPIRED date
.x /REXPIRED, sort by EXPIRED date
	The expiration date of the file.
.b.i-12;FORMAT
.x Column keywords>FORMAT
.x Sorting commands>/SFORMAT, sort by format
.x /SFORMAT, sort by format
.x Sorting commands>/RFORMAT, sort by format
.x /RFORMAT, sort by format
	The file format (e.g., VAR for variable,
VFC for variable-with-fixed-control).
.b.i-12;HOUR
.x Sorting commands>/SHOUR, sort by hour of DATE
.x /SHOUR, sort by hour of DATE
.x Sorting commands>/RHOUR, sort by hour of DATE
.x /RHOUR, sort by hour of DATE
	The hour-of-the-day component from the DATE field.
.b.i-12;MASK
.x Column keywords>MASK
.x Sorting commands>/SMASK, sort by protection mask
.x /SMASK, sort by protection mask
.x Sorting commands>/RMASK, sort by protection mask
.x /RMASK, sort by protection mask
	The file's protection mask, from left to right
is SYSTEM, OWNER, GROUP and WORLD.
.b.i-12;NAME
.x Column keywords>NAME
.x Sorting commands>/SNAME, sort by NAME
.x /SNAME, sort by NAME
.x Sorting commands>/RNAME, sort by NAME
.x /RNAME, sort by NAME
	The file name.
This field always appears in the leftmost display column.
.b.i-12;OWNER
.x Column keywords>OWNER
.x Sorting commands>/SOWNER, sort by owner
.x /SOWNER, sort by owner
.x Sorting commands>/ROWNER, sort by owner
.x /ROWNER, sort by owner
	The file owner's identification code
(two octal numbers separated by ",").
.b.i-12;PATH
.x Column keywords>PATH
.x Sorting commands>/SPATH, sort by PATH
.x /SPATH, sort by PATH
.x Sorting commands>/RPATH, sort by PATH
.x /RPATH, sort by PATH
	The file's node-device-directory path.
FLIST displays the PATH for the current file in the status line.
It may also be put in a display column.
.b.i-12;REVISED
.x Column keywords>REVISED
.x Sorting commands>/SREVISED, sort by REVISED date
.x /SREVISED, sort by REVISED date
.x Sorting commands>/RREVISED, sort by REVISED date
.x /RREVISED, sort by REVISED date
	The file's revision date (i.e., when it was last modified).
.b.i-12;SIZE
.x Column keywords>SIZE
.x Sorting commands>/SSIZE, sort by SIZE
.x /SSIZE, sort by SIZE
.x Sorting commands>/RSIZE, sort by SIZE
.x /RSIZE, sort by SIZE
	The file size, in blocks.
.b.i-12;TYPE
.x Column keywords>TYPE
.x Sorting commands>/STYPE, sort by TYPE
.x /STYPE, sort by TYPE
.x Sorting commands>/RTYPE, sort by TYPE
.x /RTYPE, sort by TYPE
	The file type (without the leading ".").
TYPE always appears as the second display column.
.b.i-12;VERSION
.x Column keywords>VERSION
.x Sorting commands>/SVERSION, sort by VERSION
.x /SVERSION, sort by VERSION
.x Sorting commands>/RVERSION, sort by VERSION
.x /RVERSION, sort by VERSION
	The file's version number, left-justified and separated from the
TYPE field by a ";".
VERSION always appears as the third display column.
.b.i-12;USER
.x Sorting commands>/SUSER, sort by file owner's user name
.x /SUSER, sort by file owner's user name
.x Sorting commands>/RUSER, sort by file owner's user name
.x /RUSER, sort by file owner's user name
	The file's owner in symbolic format
.b.i-12;WEEK
.x Sorting commands>/SWEEK, sort by DATE's weekday
.x /SWEEK, sort by DATE's weekday
.x Sorting commands>/RWEEK, sort by DATE's weekday
.x /RWEEK, sort by DATE's weekday
	The day-of-the-week component of the DATE display field.
.b.i-12;XAB
.x Column keywords>XAB
.x Sorting commands>/SXAB, sort by extra attributes
.x /SXAB, sort by extra attributes
.x Sorting commands>/RXAB, sort by extra attributes
.x /RXAB, sort by extra attributes
	Literally "extra-attributes", this is the set of record attributes.
It is considered an augmentation of the FORMAT display column, and is
always sorted within the FORMAT field's value.
.lm-16
.;
.hl	Sorting Order
The normal sorting order for text fields (PATH, NAME, TYPE) is in
increasing ASCII collating order.
For all numeric fields (e.g., DATE, MASK) the normal sorting order
is in decreasing numeric order.
.b
FLIST makes adjustments to the PATH string so that it will sort properly
(i.e., in the conventional order used by VMS) rather than in a strict
collating order.
It also treats specially the date-fields of file entries which are
not initialized properly by the directory lookup operation:
.lm+8
.b.i-4
o	Files which cannot be viewed (due to insufficient privilege)
have a date of zero (the oldest).
This field is blanked in the display.
.b.i-4
o	Backup dates of files which are otherwise accessible may
be internally set to a large number if the file has not been backed-up.
This forces files which have not been backed-up to appear at the
top of a normal sort-by-date.
.b.lm-8
There are two types of sorts performed by FLIST.
Either it is sorting some combination only of PATH, NAME, TYPE and VERSION,
or it is sorting one of the non-filename fields.
In the latter case, FLIST always follows the non-filename comparison
with NAME, TYPE, PATH and VERSION.
The name-only sorts are performed by permuting the filename components:
.b.lm+8
.br;PATH####NAME####TYPE####VERSION
.br;NAME####TYPE####PATH####VERSION
.br;TYPE####NAME####PATH####VERSION
.br;VERSION#NAME####TYPE####PATH
.lm-8
.b;The ordering of the sort keys (e.g., NAME, TYPE, PATH, VERSION)
is designed to yield the most informative display:
.lm+8
.b.i-4
o	Sorting by PATH (PATH, NAME, TYPE, VERSION) corresponds to
the ^*normal\* sorting order obtained by a wildcard directory listing
of the form
.b;########DIRECTORY#[...]
.b;All files for each directory are listed before proceeding to
the next directory.
All files are listed alphabetically by name, and by type within
the name.
Versions are listed in descending order.
.b.i-4
o	Sorting by NAME (NAME, TYPE, PATH, VERSION), on the other
hand, permits you to easily see files which appear in more than one
directory, or those which differ only by type.
It is the most natural way of sorting the directory entries,
because the file name carries the most ^*meaning\*.
.b.i-4
o	Sorting by TYPE (TYPE, NAME, PATH, VERSION)
groups together files having the same type.
This is valuable when managing a large collection of different
types of files.
The file type is usually related to the ^*use\* of the file.
.b.i-4
o	Sorting by VERSION (VERSION, NAME, TYPE, PATH)
shows the files with the highest version numbers.
Using this sort, you may easily determine the files which
have been most ^*modified\*.
.b.lm-8
The sort-by-NAME (NAME, TYPE, PATH, VERSION) is the default sorting
order used by FLIST.
NAME is first, because this is most natural to users.
VERSION is last, because this will cause files having the same version
in different directories to be display on consecutive lines.
PATH, then, is a super-version of the file, and is sorted immediately
above VERSION.
.;
.hl	Fixed-Point Sorting
When performing a sort, FLIST normally concludes the operation by
scrolling the cursor to the top of the display list.
You may inhibit this scrolling by making one file entry into a fixed-point.
There are two types of fixed-point sorting, temporary and latching:
.lm+8
.b.i-4
o	A temporary fixed-point sort is invoked by typing the sort-command
with an extra "/" prefix (e.g., "//SD" instead of "/SD").
The current file entry acts as a fixed-point;
after the sort the cursor will be scrolled to wherever this entry has been
moved.
.b.i-4
o	A latching fixed-point sort is invoked by the mark-command:
.lm+8
.b.i-4
.x Sorting commands>/MARK, latch fixed-point
.x Fixed-point sorting>/MARK
-	The "/MARK" (/MAR) command sets the current file entry as a
fixed-point, which lasts until it is explicitly reset.
.x Highlighting>fixed-point sorting
FLIST highlights the selected filename in the display.
.b.i-4
.x Sorting commands>/NOMARK, unlatch fixed-point
.x Fixed-point sorting>/NOMARK
-	The "/NOMARK" (/NOM) command clears a latched fixed-point,
wherever it is.
.lm-8
.b.lm-8
.b
If no changes are made to display as a result of the sort,
FLIST will not move the cursor.
If changes are made, and a fixed-point is active, FLIST will
always reposition the cursor to the fixed-point with higher priority.
A temporary fixed-point overrides a latching fixed-point.
.b
FLIST may make changes to the display, even if no change has
occurred in the ^&order\& of display entries.
When you delete files, FLIST blanks the entries which appear
on the screen, rather than redrawing the screen.
When FLIST performs a sort, it also compacts the portion of the
display list which is visible.
.x Display list>compaction
(The portion of the display-list which is not visible is always
kept up to date, since this requires much less time).

.hl-1	Display Format Commands
.x Display commands
Using simple FLIST commands you can easily alter the screen format
to show various file attributes.
.;
.hl+1	/COLUMNS (/C)
.x Display commands>/COLUMNS
.x Column-list
The principal display command is the column-set command "/COLUMNS".
This command accepts a list of the display-columns which FLIST displays.
It may be invoked at any time.
.b
The "/COLUMNS" command accepts an optional list of keywords.
These keywords (which may be abbreviated to a single character) are
the portions of the FLIST display which are not permanently
assigned:
.b.lm+8.nj
ALLOC, BACKUP, CREATED, DATE, EXPIRED, FORMAT, MASK, OWNER, PATH, REVISED,
SIZE, USER, XAB
.j.lm-8
.b;The remaining display keywords
.b;########NAME, TYPE, VERSION
.b;and
.b;########HOUR, WEEK
.b;are respectively fixed, or part of other display fields.
.b
If no arguments are given, "/COLUMNS" restores the display to its
default state:
.b;########/COLUMNS SIZE DATE MASK
.b;If the token "_*" is given, the current column-list is used
as an argument to simplify appending a new column to the current display.
No column may be repeated, however.
.;
.hl	DATE Toggle Commands
.y	Display commands>see also DATE-toggle
.x	DATE-toggle
There is one instance in which FLIST permits you to display the
same information twice on the screen.
The DATE display column is treated specially,
and is separate from the BACKUP, CREATED, EXPIRED and REVISED columns.
The contents of the DATE column may be changed without issuing a
"/COLUMNS" command.
By providing a toggle-command "/D", FLIST can reserve a single key
.x Key assignments>Keypad#2, sort by DATE
on the keypad for sort-by-date without losing generality.
FLIST interprets the sort-by-DATE function as
"sort by whatever DATE is assigned to."
.tp5.b
To toggle DATE, type the command "/D" with the (abbreviated) name of
the type of date you wish:
.b.lm+8
.x	DATE-toggle>/DBACKUP
.br;/DBACKUP (/DB)
.x	DATE-toggle>/DCREATED
.br;/DCREATED (/D)
.x	DATE-toggle>/DEXPIRED
.br;/DEXPIRED (/D)
.x	DATE-toggle>/DREVISED
.br;/DREVISED (/DR)
.b.lm-8
You may also change the date format.
Normally FLIST displays the date in the form
.x	Date format
.b;########dd-mmm-yyyy hh_:mm
.b;By issuing the command "/DLONG" (/DL), you make FLIST show the day of the
.x	Date format>/DLONG
.y	DATE-toggle>see also Date format
.x	DATE-toggle>/DLONG
week as well:
.b;########www dd-mmm-yyyy hh_:mm
.b;Normally FLIST does not show the day of the week, since it costs
four extra columns of the display for each date-field.
To restore the date to the shorter form, type
.x	Date format>/DSHORT
.x	DATE-toggle>/DSHORT
"/DSHORT" (/DS).
.;
.hl	Display Column Rotation
.x	Column-rotation
Under VMS version 4, file names may be quite long (up to 39 characters
in each of the NAME and TYPE fields).
FLIST automatically reserves enough space on the screen that the
NAME, TYPE and VERSION columns line up properly.
However, this may leave little room on an 80-column terminal for
auxiliary information.
In particular, the protection-edit
.x Protection edit
will not run unless the entire protection mask is visible.
(The PROTECT command can still be issued, but the cursor cannot
move about.)
.b
To make FLIST somewhat more agile (and to avoid retyping "/COLUMNS"
simply to juggle existing columns),
FLIST provides column-rotation commands
.y	Column-list>see also Column-rotation
.x Column-rotation>/CLEFT
"/CLEFT" (/CL) and
.x Column-rotation>/CRIGHT
"/CRIGHT" (/CR).
These functions are assigned to the PF4 key.
.x Key assignments>PF4>/CLEFT
.x PF4>/CLEFT
.x Key assignments>PF4>/CRIGHT (GOLD)
.x PF4>/CRIGHT (GOLD)
The column rotation commands rotate the column-list left or right.
They use no arguments.

.hl-1	Status Commands
.x	Status commands
FLIST provides a set of status commands,
analogous to the VMS "SHOW" commands.
.lm+8
.b.i-4;?COLUMNS
.x Display columns>Showing status
.x Status commands>?COLUMNS, show column-list
.br;The COLUMNS status command summarizes the current display format,
by showing the keywords which describe it.
Its primary use is to show which date-columns correspond to
the various file dates (BACKUP, CREATED, EXPIRED, REVISED).
.;
.b.i-4;?DATE
.x Status commands>?DATE, show current date
.br;The DATE status command shows the current time and date.
.;
.b.i-4;?HELP
.y Status commands>?HELP>see also /HELP
.y Status commands>?HELP>see also HELP
.x Status commands>?HELP, show command summary
.br;The HELP status command is one of several ways you may invoke
FLIST's help-display.
.;
.b.i-4;?LEVEL
.x Status commands>?LEVEL, show display level
.x Display level>?LEVEL
.y Display level>see also QUIT
.br;The LEVEL status command shows you the current display level
(i.e., how many times you have told FLIST to enter a new display-list).
If you wish to quit one or more levels of FLIST, but do not wish to
exit it entirely, this command can tell you how deep you actually are.
.;
.b.i-4;?SIZE
.x Status commands>?SIZE, show blocks in display list
.br;The SIZE status command displays the total number of blocks
both used (size) and allocated by the files in the current display
level.
This is analogous to the "/TOTAL" option of DIRECTORY.
.;
.b.i-4;?TIMES
.x ?TIMES, show timer
.x Status commands>?TIMES, show timer
.y Status commands>?TIMES>see also /TIMES
.x Key assignments>Keypad#6, display timer
.br;FLIST keeps track of the amount of time you have spent in
this process, both in elapsed time and CPU time.
Use this command to interrogate the timer.
.;
.b.i-4;?VERSION
.x Status commands>?VERSION, show FLIST version
.br;The VERSION status command displays the version and date
of the copy of FLIST which you are running.
.lm-8

.tp10
.hl	Other Display Commands
.hl+1	Refresh-Hold
Occasionally you will attempt to perform an operation with FLIST
which does not succeed, and it will not be clear why, because
FLIST gets rid of the message before you can read it.
This will happen in operations which FLIST spawns,
waits for a response, and gets an ambiguous return status from VMS.
To prevent FLIST from eradicating VMS's message, use the
"/HOLD" (/HOL) command.
.x Display commands>/HOLD
.y Display commands>/HOLD>see also SPAWN
.x Spawned subprocesses
.x VMS error messages>/HOLD
With /HOLD, FLIST waits after spawned commands (even editor calls)
for you to hit RETURN.
.x Display commands>/NOHOLD
To clear this mode (it is really only useful when you are not
successfully issuing commands), use "/NOHOLD" (/NOH).
.;
.hl	Screen Refresh
Even the best terminal driver occasionally makes a mess of your screen.
Or the system operator persists in sending you messages.
Unsolicited messages make FLIST's display difficult to read.
.x Key assignments>CTRL/W, refresh display
.x CTRL/W, refresh display
.x Display commands>CTRL/W, refresh display
To restore your screen to what it should be, type CTRL/W.
.;
.hl	Screen Dump
Figure#1-1 was generated via a screen-dump.
FLIST (and the BROWSE program) provide a screen-dump command
which may be invoked at any point where FLIST (or BROWSE) is accepting input.
(The VMS editor does not presently support this feature).
.x Key assignments>CTRL/K, screen dump
.x CTRL/K, screen dump
.x Display commands>CTRL/K, screen dump
.x Screen dump>CTRL/K
.x Screen dump>see Files
When you type CTRL/K, the screen driver makes a copy of the
current screen, and writes it to a file:
.b;########SYS_$LOGIN:SNAPSHOT.CRT
.b
When you exit from FLIST, this file is closed and you may print it.
Highlighting is represented in the snapshot-file by underlining.
.x Highlighting>screen dump
The time and date of the snapshot are written to the file as well.
Each time you invoke the screen dump,
FLIST informs you of how many times you have done so.
.;
.hl	Reset Timer
.x /TIMES, reset timer
.x Display commands>/TIMES
.y Display commands>/TIMES>see also ?TIMES
FLIST keeps track of the amount of time (both elapsed and CPU) which
you have used in running (current process only).
To reset the timer, use the "/TIMES" (/TI) command.
To display the elapsed time, use the status command "?TIMES".