.;******************************************************************************
.;* Copyright 1985 by Thomas E. Dickey.  All Rights Reserved.                  *
.;*                                                                            *
.;* You may freely copy or redistribute this software, so long as there is no  *
.;* profit made from its use, sale trade or reproduction. You may not change   *
.;* this copyright notice, and it must be included in any copy made.           *
.;******************************************************************************
.; $Id: m2.rno,v 1.2 1985/01/27 20:08:36 tom Exp $
.ch BROWSE Commands
.; more commands
.;.req "d0.req"
This chapter describes in detail the BROWSE browsing commands.

.hl	Scrolling Commands
BROWSE permits you to scroll forward or backward in units of a half-screen,
or left or right in units of a column.
The restriction to half-screen scrolling is made to reduce the
overhead required to examine a file.
This permits you to examine files which are larger than those which
you could edit.
.b
Most scrolling operations are performed in a single keystroke.
You may provide a repeat-count to modify the basic half-screen
operations.

.hl+1	Forward/Backward
You may scroll through your file in either direction.
BROWSE provides you with several commands for this purpose:
.lm+8
.b.i-4
.x Control characters>CTRL/U
.x U, up
U	The UP command (also CTRL/U)
directs BROWSE to scroll up by one half-screen.
You may not scroll up past the beginning of the file.
.b.i-4
.x Control characters>CTRL/D
.x D, down
D	The DOWN command (also CTRL/D)
directs BROWSE to scroll down by one half-screen.
You may not scroll past the end of the file.
.b.i-4
.x Control characters>CTRL/F
.x F, forward
F	The FORWARD command (also CTRL/F and space)
directs BROWSE to scroll down by a full screen.
.b.i-4
.x Control characters>CTRL/B
.x B, backward
B	The BACKWARD command (also CTRL/B)
directs BROWSE to scroll up by a full screen.
.b.i-4
.x Control characters>CTRL/T
.x T, top
T	The TOP command (also CTRL/T)
directs BROWSE to scroll to the top of the file (i.e., the first line).
.b.i-4
.x Control characters>CTRL/E
.x E, end
E	The END command (also CTRL/E)
directs BROWSE to scroll to the end of the file.
.b.lm-8
As you scroll or skip forward through a file,
BROWSE constructs a table which permits it to rapidly return to
the places where you have been.
This is useful for returning to the end of the file.
It also permits BROWSE to return to the same point on upward scrolling.
Each half-screen display overlaps by one line.
The overlap-lines are the tabulated positions in the file.
.b
.x Number>Repeat count
By supplying a number before the scrolling command,
you direct BROWSE to repeat that operation (without, of course
the extra screen operations).
For example, if you type
.b;########10D
.b;BROWSE will scroll forward by ten half-screens (normally 110 lines).
(Repeat counts are not applicable to the TOP and END commands.)
.b
Whenever BROWSE skips forward into a part of the file it has not read
before, it displays (in the status line) the half-screen number
which it is currently reading.
Because I/O on a heavily-loaded VMS system may be slow,
this tells you how far BROWSE has gotten.
Scrolling to parts of the file which you have previously viewed
is much more rapid;
BROWSE need reread only the text to display on that screen.
.b
.x Arrow keys>UP-ARROW
.x Arrow keys>DOWN-ARROW
The arrow keys (UP-ARROW and DOWN-ARROW) are normally assigned
to the UP and DOWN half-screen scrolling commands.

.hl	Aborting a Scrolling Operation
.x X, aborting I/O
If you direct BROWSE to scroll to the end of a file,
it will attempt to do just that.
However, you may change your mind;
you hadn't realized just how big the file really was.
To stop BROWSE, type "X".
This will cause BROWSE to cease reading new pages.
The last screen read will be displayed.

.hl	Left/Right
You may direct BROWSE to display the file shifted to the left or the right.
Unlike vertical scrolling, you may scroll left or right by single columns.
BROWSE provides you with several horizontal-scrolling commands:
.lm+8
.b.i-4
.x Control characters>CTRL/H
.y Control characters>Backspace, see CTRL/H
.x H, home
H	The HOME command (also CTRL/H, or backspace) returns the
display to the "home" column (the leftmost one).
.b.i-4
.x Control characters>CTRL/J
.y Control characters>LINE-FEED, see CTRL/J
.x J, jump to end-of-line
J	The JUMP command (also CTRL/J, or LINE-FEED) causes BROWSE
to scroll right until the end of the longest line (in the current
range of lines) is visible in the display.
.b.i-4
.x Control characters>CTRL/L
.x L, left
L	The LEFT command (also CTRL/L) causes BROWSE to scroll left
by one half-screen.
You may not scroll left past the home-column.
.b.i-4
.x Control characters>CTRL/R
.x R, right
R	The RIGHT command (also CTRL/R) causes BROWSE to scroll right by
one half-screen.
Right-scrolling is limited, based on the current display mode and
the maximum record length of the file.
.lm-8
.b
You may modify the operation of the HOME, LEFT and RIGHT commands
by providing a number before the command:
.lm+8
.b.i-4
.x Number>Columns
o	A number provided for the HOME command directs BROWSE to
scroll left or right, placing that particular column at the leftmost
position in the screen.
.b.i-4
.x Number>Repeat count
o	A number provided for the LEFT or RIGHT command directs
BROWSE to scroll left or right by that number of columns.
.lm-8
.b
.x Arrow keys>LEFT-ARROW
.x Arrow keys>RIGHT-ARROW
The arrow keys (LEFT-ARROW and RIGHT-ARROW) are normally assigned to
the LEFT and RIGHT commands.

.hl	Column and Line Display
There are many applications in which you need to know the exact location
of parts of the file which you are examining.
.x Ruler-mode
.x Toggle-commands>"__", Ruler-mode
BROWSE provides you with a "ruler" mode.
When you select ruler-mode (by typing an underscore, "__")
BROWSE changes the status line to a combined scale plus line number.
The cursor's column is reflected in the scale;
its line number is shown as well.
Examples of ruler-mode display are reproduced in Figures 1-6 and 1-8.
.b
You may move the cursor in units of single columns or lines using
the arrow keys.
You may temporarily exit ruler mode, and return.
The cursor will return to the point at which you exited ruler mode
(unless, of course, you scroll to a new screen).
.b
.x Ruler-mode
The following commands are provided in ruler mode:
.lm+8
.x Arrow keys>UP-ARROW
.b.i-4;UP-ARROW
.br;moves the cursor up one line.
If the cursor is already at the top-of-screen,
BROWSE scrolls up by a half-screen.
.x Arrow keys>DOWN-ARROW
.b.i-4;DOWN-ARROW
.br;moves the cursor down one line.
If the cursor is already at the bottom of the current screen,
BROWSE scrolls down by a half-screen.
.x Arrow keys>LEFT-ARROW
.b.i-4;LEFT-ARROW
.br;moves the cursor left one column.
If the cursor is in the leftmost display-column,
BROWSE scrolls left by a half-screen.
.x Arrow keys>RIGHT-ARROW
.b.i-4;RIGHT-ARROW
.br;moves the cursor right one column.
If the cursor is at the end of the scale,
BROWSE scrolls to the right by a half-screen.
.x Control characters>CTRL/H
.x H, home
.b.i-4;H	(also CTRL/H, or backspace)
moves the cursor to the HOME-column.
If the cursor is already in the HOME-column,
BROWSE moves the cursor up one line.
.x Control characters>CTRL/I
.y Control characters>TAB, see CTRL/I
.x I, tab
.b.i-4;I	(also CTRL/I, or TAB)
moves the cursor right, to the next tab stop (multiples of 8 columns).
.x Control characters>CTRL/J
.x J, jump to end-of-line
.b.i-4;J	(also CTRL/J, or LINE-FEED)
moves the cursor to the end of the current display line.
If the cursor is already at the end of the display line,
BROWSE moves the cursor down one line.
.b.lm-8
You may modify the effect of the arrow keys, as well as the
I-command by prefixing the command with a repeat count.
.b
.x Ruler-mode
In ruler mode, you may use the other BROWSE commands as well.

.hl-1	Searching
.x Highlighting>Searching
BROWSE provides you with a simple, easy to use search command.
It displays the points in the file at which the target is found
by highlighting each occurrence.
.;
.hl+1	Initiating a Search
.x "/", search forward
.x "_\", search backward
To initiate a search, type "/" or "_\".
A forward slash ("/") initiates a forward search;
a backward slash ("_\") a backward search.
BROWSE will prompt you for a search target.
You may provide only printing characters (counting space).
.x Control characters>CTRL/U
.x Control characters>CTRL/X
.x CTRL/U, abort input
.x CTRL/X, abort input
To make corrections, use the DELETE key, or CTRL/U or CTRL/X to abort the
input.
Hit the RETURN or ENTER key to complete the text-entry.
.b
Whatever you have entered becomes the current search target.
A space in your target matches any number of white-space characters
(i.e., space, TAB, FORM-FEED or RETURN) in the display.
BROWSE begins searching in the current screen for matches against this target.
If no matches are found, BROWSE continues the search in the given direction.
If BROWSE reaches the end of the file without finding a match,
it sounds an alarm, and retains its original position.
If a match is found, BROWSE scrolls to the corresponding screen
and highlights all matching positions.
.x Highlighting>Searching
Matching positions which happen to lie to the left or right of
the current column limits are flagged by highlighting the end of
the display line closest to the match.
.b
.x Control characters>CTRL/U
.x Control characters>CTRL/X
.x CTRL/U, abort input
.x CTRL/X, abort input
If you provide no input (i.e., by hitting CTRL/U or CTRL/X, or by simply
hitting RETURN), this clears the search target.
.x Highlighting>Overstruck text
If no search target is active, BROWSE highlights overstruck text.
.;
.hl	Continuing a Search
You may continue a search in either direction,
regardless of the direction in which you initiated it:
.lm+8
.b.i-4
.x Control characters>CTRL/N
.x N, next
N	The NEXT command (also CTRL/N) directs BROWSE to search forward
in the file, for the next matching positions.
.b.i-4
.x Control characters>CTRL/P
.x P, previous
P	The PREVIOUS command (also CTRL/P) directs BROWSE to search backward
in the file, for the previous matches.
.lm-8
.;
.hl	Aborting a Search
.x X, aborting I/O
Searching a file always requires I/O, and can be slow.
If you wish to stop a search, type "X".
This will cause BROWSE to halt the search, and return to its original position.

.hl-1	Altering the Display Format
BROWSE is used to examine ^&text\& files, rather than ^&binary\& ones.
You may direct BROWSE to display your file in alternate forms to see its
structure (i.e., the actual characters used to make up overstrikes,
and the record numbering).
The alternatives are intentionally limited to those which are applicable
to text (or printer) files.
You may not, for instance, use BROWSE as a screen-oriented hexadecimal dump
(it strips parity from all characters).
Nor does BROWSE interpret escape sequences (it prevents them from
affecting your screen).
.b
BROWSE, in fact, is designed to be quite robust.
It can display the contents of any sequential file without
causing your terminal to lock up.
Any control characters which are not in its repertoire are
converted to "_^"-form (e.g., ESCAPE becomes "_^_[").
You may use BROWSE to examine binary (".EXE" and ".OBJ") files.
Note, however, that a LINE-FEED always causes BROWSE to begin a
new line.
.;
.hl+1	Overstrikes
.x Highlighting>Overstruck text
Normally BROWSE interprets overstruck text (created by either backspacing
or embedded RETURN characters) and highlights it.
For binary files, this may be inappropriate.
Or you may wish to expand the sequence of characters which make up
the overstruck text.
.x Control characters>Noncommand>CTRL/O
To do this, use the O-command ("O" only, not CTRL/O).
BROWSE will alter its interpretation of backspace and RETURN characters.
Backspaces are shown as "_^H", and RETURN as "_^M".
Tab characters also are shown as "_^I".
.x Toggle-commands>O, overstrikes
.y O, see Toggle-commands
To undo this command, type "O" again; it simply toggles the display.
.b
If you have invoked BROWSE with the qualifier
.b;########/OVER:2
.b;then the O-command becomes a three-state toggle.
The third state shows all control characters (except LINE-FEED) as a ".".
This permits you to examine a binary file looking only for character
strings.
.b
Figure 1-3 illustrates the second state of the O-command.
Figures 1-7 and 1-8 illustrate the third state of the O-command.
.;
.hl	Marks and Record Numbers
You may also use BROWSE to examine the record structure of a text file.
VMS files are organized in records
which may be of any length up to 32768 characters.
Files may have either variable record lengths, or fixed (i.e., all the same).
For most text files, records are synonymous with lines,
i.e., the record attributes imply carriage control at the end of each
record.
However, there are files (such as those produced by RUNOFF) which
do not have carriage control.
Also, even for files having carriage control attributes,
carriage control characters (e.g., LINE-FEED) may be embedded within
a record.
BROWSE makes sense of all this and shows your file as it really is.
.b
When it opens a  file for examination, BROWSE allocates a buffer large
enough to show the longest display line which could be made.
Files with no carriage control attributes are assumed to be like those
produced by RUNOFF:
each record contains characters as needed to produce the desired
carriage control.
BROWSE appends records until a LINE-FEED is found, either explicitly,
or as part of the record attributes.
(You may override this action with the "/NOJOIN" qualifier).
.b
A record may correspond to a fraction of a display line,
or it may be one or more display lines.
You may examine the record structure of the display by using the
"_^"- and M-commands:
.lm+8
.b.i-4
.x Toggle-commands>"_^", Set temporary MARK-mode
.y M, see Toggle-commands
.x Toggle-commands>M, mark (file-address)
o	The "_^" command sets MARK-mode.
BROWSE redisplays the current screen with a prefix before each
line (see Figures 1-4, 1-5, 1-7 and 1-8).
There are either two or four columns of numbers shown in the prefix:
.lm+8
.b.i-4
-	If two, the first is the record file address (the number of
characters from the beginning of the file), and the second is the
display line number.
.b.i-4
-	If four, the first is the record file address,
the second is the offset into a record, and the third and
fourth are the record number and line number.
.lm-8
.b.i-4
.x Toggle-commands>M, mark (file-address)
.y Control characters>RETURN, see CTRL/M
.x Control characters>CTRL/M
o	The M-command (also CTRL/M or RETURN) toggles this prefix mode,
showing the record lengths, rather than their offsets.
It is a three-state toggle; the third state resumes the original
display mode.
.b.lm-8
Normally the M-command becomes inactive again on reaching the
original display mode.
.x /MARKS qualifier
If you use the qualifier
.b;########/MARKS
.b;however, it is permanently enabled.

.hl-1	Other Commands
The remaining BROWSE commands are all one-of-a-kind,
but all useful:
.;
.hl+1	Exiting from BROWSE
.x Control characters>Noncommand>CTRL/Q
.x Control characters>CTRL/Z
.x Q, quit
.x Z, end-of-input (quit)
To exit from BROWSE, use the Q (quit) command, or Z (also CTRL/Z).
.;
.hl	Help-Screen
.x "?", help
.x PF2, help
You may obtain online help from BROWSE by typing "?" (or PF2).
BROWSE displays the help-screen shown in Figure 1:
.;
.;
.req "d0.req"
.lm+3.k.nf.nj
Screen dumped: 21-JAN-1985 06:39:56
Image top: 0  bottom: 22

+---------------------------------------------------------------------+
|BROWSE - Browsing program                                              |
|Commands:                                                            |
|    Q,Z  - ^&Quit\&.                                                     |
|    _?    - display this message-screen                               |
|    __    - toggle scale/normal mode (alters arrow keys also)         |
|    T,E  - scroll to ^&Top\&/^&End\& of file.                                |
|    F,B  - scroll ^&Forward\&/^&Backward\& by a full-screen.                 |
|    U,D  - scroll ^&Up\&/^&Down\& 1/2 screen (arrow).                        |
|    R,L  - scroll ^&Right\&/^&Left\& 1/2 screen (arrow)                      |
|    H    - scroll left to ^&Home\&-column (in scale-mode, move cursor up |
|    I,J  - (scale-mode) move cursor to next ^&tab\& stop or to next ^&end-o\&|
|    /,_\  - search (if '_\', backward) for a string                    |
|    N,P  - search for ^&Next\&/^&Previous\& occurrence of string.            |
|    W    - refresh display ^&Window\&                                    |
|    X    - ^&aborts\& search/skip                                        |
|    _<number_> - Permit H,L/R scroll by specified ^&number\& of columns,   |
|           or ^&repeat\& of U,D,B,F,I or arrow keys                      |
|Special:                                                             |
|    K   - Copy screen to SNAPSHOT.CRT                                |
|    M   - Toggle ^&MARK\& mode (active if /MARK option)                  |
|    O   - Toggle ^&OVER\& mode (3 states if /OVER, else 2)               |
|    V   - Display current ^&Version\&                                    |
|    _^   - Toggle ^&MARK\& (^&DEBUG\&) modes                                  |
|^&FL.HLP;   Lines 1:23  Cols 1:71 (77)\&                                 |
+---------------------------------------------------------------------+
.lm.nk.f.j
.b2.c;Figure#1##^*Help Summary\*
.;.stc2,1,Help Summary
.b
.;
.;
.hl	Screen-Refresh
If your screen becomes corrupted by line noise, or by unexpected
system messages,
you may direct BROWSE to refresh the screen.
The W command causes BROWSE to re-read the current page and then redisplay it.
.x Control characters>CTRL/W
.x W, window refresh
.x Control characters>Differences from noncontrol>CTRL/W
A CTRL/W may be given at any time (even while entering a search target),
and refreshes the screen without re-reading the page.
The re-read operation is provided to make BROWSE cleaner:
.lm+8
.b.i-4
o	If you have directed BROWSE to display the help-screen,
the W command will redisplay the file, rather than the help-screen.
.b.i-4
.x Toggle-commands>M, mark (file-address)
o	If you are using the M-command to display record marks,
BROWSE may discover in the middle of a page that the file actually
has records with embedded carriage control.
The prefix jumps, from two columns of numbers, to four.
Requiring BROWSE to read each page first to determine this case
would make it slower.
The W command re-reads the page and makes the prefix columns all the
same width.
.lm-8
.;
.hl	Screen-Dump
.x Control characters>CTRL/K
.x K, copy screen
You may obtain a copy of the screen contents by using the
K command (also CTRL/K).
All of the figures in this document were generated using
this facility.
.b
When you issue a screen-dump command, 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 BROWSE, this file is closed and you may print it.
.x Highlighting>Screen dump
Highlighting is represented in the snapshot-file by underlining.
The time and date of the snapshot are written to the file as well.
Each time you invoke the screen dump, BROWSE informs you of how many
times you have done so.
.b
.x Control characters>CTRL/K
.x Control characters>Differences from noncontrol>CTRL/K
The CTRL/K screen dump is recognized at all times by BROWSE.
The K command, of course, is not recognized during prompts.
.;
.hl	Version
.x Control characters>CTRL/V
.x V, version
Typing a V (also CTRL/V) causes BROWSE to display its version number
in the status line.