.; $Id: m1.rno,v 1.2 1985/01/27 20:06:12 tom Exp $
.ch Introduction to BROWSE
.; introduction
.; screen manipulation and command entry
.req "d0.req"
The BROWSE program permits you, the user, to browse a VMS file,
scrolling up, down, left or right.
By using cursor- and screen-update optimization,
BROWSE provides you with rapid response.
BROWSE is superior to the EDT screen editor
for applications which require examination, rather than modification.

.hl	Special Features
Besides the basic scrolling functions, BROWSE provides you with other
powerful screen-oriented functions:
.lm+8
.b.i-4
o	BROWSE always shows the current position of the display-page
in the file, as well as the filename.
.b.i-4
.x Highlighting>Overstruck text
o	Text which is underlined or overstruck is shown in the display
by highlighting.
.b.i-4
.x Highlighting>Searching
o	You may search for a string, either forward or backward.
Text matching the search-string is highlighted (instead of underlined text).
.b.i-4
o	You may interrupt a search, so that if you
accidentally begin a search while examining a
very large file, you can regain control of your terminal.
.b.i-4
o	You may alter the format of the display, causing characters
which normally are used for carriage control (and are invisible) to
become visible.
.b.i-4
.x Ruler-mode
o	BROWSE provides you with a "ruler" command which shows you the
line number and column of any point in the file.
.lm-8

.hl	Command Entry
Most commands recognized by BROWSE are single-keystroke.
It maps all alphabetic characters to the set of control characters
(e.g., "F", "f" and "CTRL/F" are equivalent).
.b
Commands which require more information than a single keystroke
prompt you in the status line for the required information.
There are two types of command which result in a prompt:
.ls
.le;Searches.
BROWSE accepts any combination of ^&printing\& characters for a search
target.
The DELETE key and CTRL/U, CTRL/X have their normal meaning (delete or cancel).
.le;Numeric arguments.
Certain commands (e.g., left/right scrolling) accept an optional numeric
argument.
If you type a numeric digit, BROWSE enters numeric-argument mode,
echoing this digit as the first character of your input and
listing in the prompt the letters which it will accept as a command.
If you type a number followed by one of these (alphabetic) characters,
BROWSE will then execute the command.
For example, if you typed "12R", BROWSE would scroll right by 12 columns.
.b
If you type a digit but do not wish to perform a command,
type CTRL/X or CTRL/U.
.els

.hl	Searches
BROWSE performs searches and displays their result in an unusual manner:
.lm+8
.b.i-4
o	The search string may contain only printable ASCII characters.
This restriction is made to eliminate the keypad-dependency of EDT.
The search itself is case-independent.
.b.i-4
o	Blanks within the search string are matched by any type of
blank in the file itself (e.g., space, TAB, RETURN, LINE-FEED and FORM-FEED).
Multiple blanks are treated as a single blank.
.b.i-4
o	Search-matches may not span a display-line.
(A display-line is normally synonymous with a record in the file).
.b.i-4
.x Highlighting>Searching
o	All positions on the display screen which match the search string
are highlighted.
Thus, you may see all matches at a glance, rather than by cursor movement.
.b.i-4
o	Positions which lie to the left or right of the screen cause the
corresponding end of the line to be highlighted.
BROWSE does not automatically scroll left/right to the search target.
.b.i-4
o	A search remains in effect until canceled (by searching for
an empty string).
If you scroll about with an active search, BROWSE will continue to
highlight locations in the file which match the search string.
.b.lm-8
Thus, rather than simply duplicate conventional searches (such as that
provided by EDT), BROWSE provides you with a powerful examination tool.
By treating all white-space the same, BROWSE allows you to ignore the
exact amount of spacing.
.x Highlighting>Searching
The highlighting makes searches simpler by showing you all occurrences,
rather than each one, one at a time.

.hl	Screen Organization
BROWSE reserves the last line of the screen for status display.
It uses the remainder of the screen to display your file.
.b
Figure#1 shows a typical screen using BROWSE.
.x Highlighting>Overstruck text
Overstruck text (e.g., the title "FLIST#-#Directory#Editor") is highlighted.
The file name is given in the status line,
as is the range of line numbers shown in the screen (i.e., "1:23").
The range of columns "1:69" is obtained from the current screen-width
(for this example, 70), and the amount by which the screen is shifted.
The length, in columns, of the longest line on the display is given
in parentheses, "(77)".

.tp30.b2.lm+3.k.nf.nj
Screen dumped: 21-JAN-1985 07:11:44
Image top: 0  bottom: 22

+---------------------------------------------------------------------+
|^&FLIST - Directory Editor\&                                             |
|                                                                     |
|  FLIST (directory editor) permits the  user  to  sort  directories, |
|  files,  delete  rename  or  alter  the  protection code on files, a|
|  dynamic display.                                                   |
|                                                                     |
|  Format:                                                            |
|                                                                     |
|        FLIST [_*._*;_*]                                                |
|                                                                     |
|                                                                     |
|^&Options:\&                                                             |
|                                                                     |
|  /NOALL         Suppress filename if no privilege for other data    |
|  /ALL (D)       Read  directory  entries  for  all  filenames,   eve|
|                 insufficient privilege.                             |
|  /DBACKUP       Show backup dates instead of creation dates         |
|  /NODATE        Suppress creation-date+time                         |
|  /FAST          Suppress all fields other than the filename (_*3 fast|
|  /NOFAST        Open each file  to  obtain  auxiliary  information  |
|                 date, size).                                        |
|  /NOOWNER       Suppress display of owner code                      |
|  /NOPROTECTION  Suppress display of protection mask                 |
|^&FL.HLP;   Lines 1:23  Cols 1:69 (77)\&                                 |
+---------------------------------------------------------------------+
.b.c;Figure#1##Sample Screen
.;.stc2,1,Sample Screen
.b2.lm.nk.f.j

You may direct BROWSE to display the same screen shifted to the right by
typing R.
Scrolling and shifting are single-keystroke commands in BROWSE.
.tp30.b2.lm+3.k.nf.nj
Screen dumped: 21-JAN-1985 07:12:03
Image top: 0  bottom: 22

+---------------------------------------------------------------------+
|                                                                     |
|                                                                     |
|the  user  to  sort  directories,  examine                           |
|  the  protection code on files, all via a                           |
|                                                                     |
|                                                                     |
|                                                                     |
|                                                                     |
|                                                                     |
|                                                                     |
|                                                                     |
|                                                                     |
|                                                                     |
|if no privilege for other data                                       |
|ntries  for  all  filenames,   even   if                             |
|lege.                                                                |
|instead of creation dates                                            |
|date+time                                                            |
|s other than the filename (_*3 faster)                                |
|  obtain  auxiliary  information  (e.g.,                             |
|                                                                     |
|f owner code                                                         |
|f protection mask                                                    |
|^&FL.HLP;   Lines 1:23  Cols 36:104 (77)\&                               |
+---------------------------------------------------------------------+
.b.c;Figure#2##Sample Screen, Shifted Right
.;.stc2,2,Sample Screen, Shifted Right
.b2.lm.nk.f.j

BROWSE permits you to change the display dynamically.
The overstruck text is composed by backspace-overstrikes.
.x Toggle-commands>O, overstrikes
By toggling the O-command, you may see these backspaces (i.e., "_^H"
is a CTRL/H, or backspace).
.tp30.b2.lm+3.k.nf.nj
Screen dumped: 21-JAN-1985 07:11:51
Image top: 0  bottom: 22

+---------------------------------------------------------------------+
.nfl uppercase
|D^HDI^HIR^HRE^HED^HD -^H- D^HDi^Hir^Hre^Hec^Hct^Hto^Hor^Hry^Hy E^HEd^|
|^M                                                                   |
|  FLIST (directory editor) permits the  user  to  sort  directories, |
|  files,  delete  rename  or  alter  the  protection code on files, a|
|  dynamic display.^M                                                 |
|^M                                                                   |
|  Format:^M                                                          |
|^M                                                                   |
|        FLIST [_*._*;_*]^M                                              |
|^M                                                                   |
|^M                                                                   |
|O^HOp^Hpt^Hti^Hio^Hon^Hns^Hs:^H:^M                                   |
|^M                                                                   |
|  /NOALL         Suppress filename if no privilege for other data^M  |
|  /ALL (D)       Read  directory  entries  for  all  filenames,   eve|
|                 insufficient privilege.^M                           |
|  /DBACKUP       Show backup dates instead of creation dates^M       |
|  /NODATE        Suppress creation-date+time^M                       |
|  /FAST          Suppress all fields other than the filename (_*3 fast|
|  /NOFAST        Open each file  to  obtain  auxiliary  information  |
|                 date, size).^M                                      |
|  /NOOWNER       Suppress display of owner code^M                    |
|  /NOPROTECTION  Suppress display of protection mask^M               |
.fl uppercase
|^&FL.HLP;   Lines 1:23  Cols 1:69 (89)\&                                 |
+---------------------------------------------------------------------+
.b.c;Figure#3##Sample Screen with Expanded Carriage Control
.;.stc2,3,Sample Screen with Expanded Carriage Control
.b2.lm.nk.f.j

Even more detail is possible.
You may direct BROWSE to show the file-address (cumulative character count)
of each display line, and the line number (modulo 100) before each line:
.;
.tp30.b2.lm+3.k.nf.nj
Screen dumped: 21-JAN-1985 07:12:36
Image top: 0  bottom: 22

+---------------------------------------------------------------------+
|        0.01:^&FLIST - Directory Editor\&                                |
|       70.02:                                                        |
|       74.03:  FLIST (directory editor) permits the  user  to  sort  |
|      156.04:  files,  delete  rename  or  alter  the  protection cod|
|      238.05:  dynamic display.                                      |
|      260.06:                                                        |
|      264.07:  Format:                                               |
|      278.08:                                                        |
|      282.09:        FLIST [_*._*;_*]                                   |
|      308.10:                                                        |
|      312.11:                                                        |
|      316.12:^&Options:\&                                                |
|      344.13:                                                        |
|      348.14:  /NOALL         Suppress filename if no privilege for o|
|      418.15:  /ALL (D)       Read  directory  entries  for  all  fil|
|      498.16:                 insufficient privilege.                |
|      542.17:  /DBACKUP       Show backup dates instead of creation d|
|      606.18:  /NODATE        Suppress creation-date+time            |
|      654.19:  /FAST          Suppress all fields other than the file|
|      730.20:  /NOFAST        Open each file  to  obtain  auxiliary  |
|      810.21:                 date, size).                           |
|      844.22:  /NOOWNER       Suppress display of owner code         |
|      896.23:  /NOPROTECTION  Suppress display of protection mask    |
|^&FL.HLP;   Lines 1:23  Cols 1:56 (77):79\&                              |
+---------------------------------------------------------------------+
.b.c;Figure#4##Sample Screen Showing File-Address
.;.stc2,4,Sample Screen Showing File-Address
.b2.lm.nk.f.j

Another keystroke transforms the file-address into record lengths:
.;
.tp30.b2.lm+3.k.nf.nj
Screen dumped: 21-JAN-1985 07:12:43
Image top: 0  bottom: 22

+---------------------------------------------------------------------+
|       68.01:^&FLIST - Directory Editor\&                                |
|        2.02:                                                        |
|       79.03:  FLIST (directory editor) permits the  user  to  sort  |
|       79.04:  files,  delete  rename  or  alter  the  protection cod|
|       20.05:  dynamic display.                                      |
|        2.06:                                                        |
|       11.07:  Format:                                               |
|        2.08:                                                        |
|       23.09:        FLIST [_*._*;_*]                                   |
|        2.10:                                                        |
|        2.11:                                                        |
|       26.12:^&Options:\&                                                |
|        2.13:                                                        |
|       67.14:  /NOALL         Suppress filename if no privilege for o|
|       77.15:  /ALL (D)       Read  directory  entries  for  all  fil|
|       42.16:                 insufficient privilege.                |
|       62.17:  /DBACKUP       Show backup dates instead of creation d|
|       46.18:  /NODATE        Suppress creation-date+time            |
|       74.19:  /FAST          Suppress all fields other than the file|
|       77.20:  /NOFAST        Open each file  to  obtain  auxiliary  |
|       31.21:                 date, size).                           |
|       49.22:  /NOOWNER       Suppress display of owner code         |
|       54.23:  /NOPROTECTION  Suppress display of protection mask    |
|^&FL.HLP;   Lines 1:23  Cols 1:56 (77):79\&                              |
+---------------------------------------------------------------------+
.b.c;Figure#5##Sample Screen Showing Record-Lengths
.;.stc2,5,Sample Screen Showing Record-Lengths
.b2.lm.nk.f.j

.x Ruler-mode
By selecting "ruler-mode", you may use BROWSE to determine the
column and line number of any point in your file.
.x Highlighting>Column-scale (see Ruler-mode)
The ruler is highlighted to make it more readable.
.;
.tp30.b2.lm+3.k.nf.nj
Screen dumped: 21-JAN-1985 07:13:27
Image top: 0  bottom: 22

+---------------------------------------------------------------------+
|^&FLIST - Directory Editor\&                                             |
|                                                                     |
|  FLIST (directory editor) permits the  user  to  sort  directories, |
|  files,  delete  rename  or  alter  the  protection code on files, a|
|  dynamic display.                                                   |
|                                                                     |
|  Format:                                                            |
|                                                                     |
|        FLIST [_*._*;_*&]                                                |
|                                                                     |
|                                                                     |
|^&Options:\&                                                             |
|                                                                     |
|  /NOALL         Suppress filename if no privilege for other data    |
|  /ALL (D)       Read  directory  entries  for  all  filenames,   eve|
|                 insufficient privilege.                             |
|  /DBACKUP       Show backup dates instead of creation dates         |
|  /NODATE        Suppress creation-date+time                         |
|  /FAST          Suppress all fields other than the filename (_*3 fast|
|  /NOFAST        Open each file  to  obtain  auxiliary  information  |
|                 date, size).                                        |
|  /NOOWNER       Suppress display of owner code                      |
|  /NOPROTECTION  Suppress display of protection mask                 |
|^&....+...10....+...20\&.^&...+...30....+...40....+...50....+...60....\&    9|
+---------------------------------------------------------------------+
.b.c;Figure#6##Sample Screen Showing Line/Column "Ruler"
.;.stc2,6,Sample Screen Showing Line/Column "Ruler"
.b2.lm.nk.f.j

Though BROWSE is designed primarily to browse ^&text\& files,
you may also examine ^&binary\& files with it.
Figure#7 was obtained by setting the qualifiers "/OVER:2" and "/MARK".
This causes all control characters to be shown as ".",
and the record-address and line numbers as a display-prefix.
.b
Note that unlike Figures 4 and 5, there are now four columns of numbers
shown in the prefix area.
BROWSE normally displays one file-record on each display line.
However, if a LINE-FEED is found embedded within a record,
BROWSE begins a new display line.
In Figure#7, the first column shows the ^&record file address\&,
and the second the offset of the new display-line within the
record.
Because the display lines and records are not synonymous,
the record number (third column) is shown separately,
from the line number (fourth column).
.tp30.lm+3.k.nf.nj
Screen dumped: 21-JAN-1985 07:14:33
Image top: 0  bottom: 22

+---------------------------------------------------------------------+
.nfl
|        0......01.01:..0.@.L.....0204....................;#Qv........|
|         .0141....02:......... .#.......$.......C.......D.......G... |
|         .0189....03:...H.......l.?....}$.......!...........         |
|         .0229....04:VMSRTL_001.....$.                               |
|         .0247....05:.....!.......T...                               |
|         .0265....06:SCRSHR_001......................................|
|      512......02.07:all.date.dbackup.drevised.fast.owner.protection.|
|         .0273....08:%s%s                                            |
|         .0278....09:..HLP.FLIST.more...... %s. ...Terminal must be V|
|         .0345....10:..>..=..[0m.[20l..[?4l.?[%d;%d?....             |
|         .0381....11:....-.%s: \%.8s\.$.%s                           |
|         .0403....12:. 00:00:00.00.no.%d%c.%s: %s.%s: %s             |
|         .0439....13:. .Reading: %3d files.Working.....Command failed|
|     1024......03.14:ontinue.?help.?columns.?date.?level.?quota.?size|
|     1536......04.15:inspect.more.next.nfind.print..LIS.protect.purge|
|     2048......05.16:.%d.locked.  .  .  .%%-%ds.%-6s. .%6.6d.%-6s. .%|
|     2560......06.17:licable.Repeated display-field: %s.%c., . (%s).D|
|     3072......07.18:u cannot view this file.EDIT.HOME.%s%s.HOME.EDTI|
|     3584......08.19:.OQ.Q.OR.R.OS.Op.?p.Oq.?q.Or.?r.Os.?s.Ot.?t.Ou.?|
|         .0180....20:....;%d.r...You are not the file's owner.(NO Pri|
|     4096......09.21:roll .Up/.Down 1/2 screen (arrow)..    R,L  - sc|
|     4608......10.22: or arrow keys.Special:.    K   - Copy screen to|
|         .0483....23:.  Lines %d:%d  Cols %d:%d (%                   |
.fl
|^&FL.EXE;   Lines 1:23  Cols 1:56 (512):512  Records 1+\&                |
+---------------------------------------------------------------------+
.b.c;Figure#7##Sample Screen Showing Binary File
.;.stc2,7,Sample Screen Showing Binary File
.b2.lm.nk.f.j
.;
The status line is extended to account for the additional information.
The ":512" indicates the longest record length.
The range of record numbers is shown "1+", because
(like the prefix line-numbers),
the prefix record-numbers are given modulo 100.

Scrolling and ruler mode work properly when record addresses and line
numbers are shown.
The prefix area is fixed on the screen;
the content alone is shifted:
.;
.tp30.b2.lm+3.k.nf.nj
Screen dumped: 21-JAN-1985 07:15:43
Image top: 0  bottom: 22

+---------------------------------------------------------------------+
|        0......01.01:06............_"....&.                            |
.nfl
|         .0141....02:                                                |
|         .0189....03:                                                |
|         .0229....04:                                                |
|         .0247....05:                                                |
|         .0265....06:................................................|
|      512......02.07:el: %d.%s.Total blocks: %d (%d allocated).%s.%s.|
|         .0273....08:                                                |
|         .0278....09:                                                |
|         .0345....10:                                                |
|         .0381....11:                                                |
|         .0403....12:                                                |
|         .0439....13:                                                |
|     1024......03.14:end./backward./home./middle./low./forward./colum|
|     1536......04.15:fix is legal only on sort-command.+.-.<number> u|
|     2048......05.16:;.%d.File '%s' is not a member of file-list.File|
|     2560......06.17:LIS.LOG.LST.MAP.OBJ.TMP.TM0.TM1.TM2.TM3.TM4.TM5.|
|     3072......07.18:ust be positive.Argument for QUIT must be '*' or|
|     3584......08.19:d..[H.[J...Two control/C's in succession trigger|
|         .0180....20:it..    ?    - display this message-screen.    _|
|     4096......09.21:umn (in scale-mode, move cursor up too).    I,J |
|     4608......10.22:   - Toggle .OVER mode (3 states if /OVER, else |
|         .0483....23:                                                |
.fl
|                     ^&....+..130....+..14\&0^&....+..150....+..160...\&    1|
+---------------------------------------------------------------------+
.b.c;Figure#8##Sample Screen Showing Shifted Binary File
.;.stc2,8,Sample Screen Showing Shifted Binary File
.b2.lm.nk.f.j

.hl	Configuration Requirements
BROWSE runs on any VT52, VT100 or other ANSI x3.64-compatible terminal.
.b
BROWSE is written in VMS-C, and requires approximately 50 kilobytes
of memory.
It has been tested under VMS versions 3.6, 3.7 and 4.0.
.b
You may use it to examine any sequential VMS disk file.