dlnash@ut-ngp.UUCP (Donald L. Nash) (12/07/85)
Here's the User's Guide for PC-More.
Don Nash
UUCP: ...!{ihnp4,allegra,seismo!ut-sally}!ut-ngp!dlnash
APRA: dlnash@ngp.UTEXAS.EDU
-------------------------cut here-------------------------
PC-Write
by Donald L. Nash
December, 1985
Version 1.2
Section 1: Introduction
PC-More is a pager program similar to the UNIX* more program. It is
designed to work on the IBM Personal Computer, PC XT, and PC AT, as well as
compatibles. The purpose of PC-More is to display a file one screenful at a
time for easy viewing. The PC-DOS "type" command can do this, but the text
scrolls too fast for most people to read. Beginning with version 2.0, PC-DOS
supplied its own version of a more filter, but it is extremely limited in its
usefulness, since it can only display one screenful at a time. People who are
used to the UNIX version of more expect to be able to move through the file in
any increment they choose, not just a screenful at a time. PC-More corrects
this problem.
Section 2: Invoking PC-More
PC-More can be used to read from a file or to read from a pipe. To invoke
PC-More to read from a file, simple type the following in responce to the PC-
DOS prompt:
A>more file1.ext [file2.ext ... ]
The part in brackets is optional. It simply means that you can type any
number of filenames after the word "more." When PC-More reaches the end of one
file, it will automatically go on to the next one on the command line. Moving
between files is explained below.
If you want PC-More to read from a pipe, where it will read the output of
some other command as its input, then you would invoke it like this:
A>command | more
where "command" is some program or PC-DOS command which writes to the PC-DOS
stdout device (usually the console screen). In either case, PC-More accepts
the same commands once it is invoked, with a few exceptions explained below.
Constructs like this:
A>command | more file1.ext [file2.ext ... ]
*UNIX is a trademark of ATT Bell Laboratories.
- 1 -
should ALWAYS be avoided. If you would expect PC-More to read from the pipe
first, then go on to the files, you would be wrong. Under PC-DOS, there is no
way to tell directly if the stdin and stdout devices have been redirected
through a pipe. PC-More simply assumes that if there are no filenames on the
command line, then it must be reading from a pipe. This is somewhat risky, but
it is the only way to go when using PC-DOS. The above construction will
confuse PC-More into thinking that stdin has not been redirected, producing
potentially hazardous results for some of the commands (explained in the next
section).
Section 3: PC-More Commands
Part 1: Motion Commands
If you have used programs like PC-More before, then you should skip the
first four parts of this section, since they are something of a tutorial
description of the PC-More commands. Part 5 has a summary of all the commands
which will probably be enough for you.
Once PC-More has been invoked, it will clear the screen and display the
first screenful of data. When the screen fills, the following message appears
on the bottom line of the screen:
--filename.ext--
where "filename.ext" is the name of the file from which PC-More is reading. If
it is reading from a pipe, then "filename.ext" will be "stdin." You may now
type any of the PC-More commands.
To see the next screenful of data, simply type a space. The screen will
clear and the next screenful will appear. PC-More will clear the screen every
time it reaches the bottom with the following exceptions:
1. Advancing one line at a time will never clear the screen, even if it is
full. This is a feature which allows you to display two lines which
may be on different (but consecutive) screens.
2. If the screen is not full when the prompt appears and command is given
which will fill the screen and cause scrolling, then PC-More will not
clear the screen when it fills. An example of this would be the
following situation: The screen is currently full. The user types 'h'
to request the next half screen of data. The screen is cleared and the
next half screen appears at the top of the screen. The user then types
- 2 -
a space to see the next full screen. The text will scroll down until
it hits the bottom of the screen. PC-More will not clear the screen to
display the rest of the data. Instead, it will scroll up the text
already on the screen.
Now that the issue of screen clearing is out of the way, the other two
motion commands can be described. To advance only one line, hit the return
key. The next line will appear and the prompt will reappear. To advance half
a screen, which would be the next 12 lines, hit the 'h' key in responce to the
prompt. The screen will be cleared if necessary and the next 12 lines will
appear, followed by the prompt.
These three commands can be preceded by a numeric argument up to three
digits long. This argument will tell the following motion command to repeat
itself the specified number of times. Note that when the "advance one line"
command is given an argument, it will clear the screen when necessary. As an
example of using arguments, the following command will show the next five
screenfuls of data without pausing or clearing the screen when given to the
prompt:
5<sp>
Here, <sp> means "hit the space bar." Similarly, <cr> would mean "hit the
enter key." Only the three motion commands will use the argument. The other
commands will simply ignore the argument and clear it when they finish.
The final motion command is 'r', for "rewind file." This will reset the
read/write pointer to the beginning of the file. This is handy if you
accidently pass up what you are looking for. You can rewind the file and start
over at the beginning. While this is not as handy as backward paging commands
would be, it is all that is available at the moment. Backward paging commands
may come out in future versions of PC-More. Important Note: "rewind file"
will not work if you are reading from a pipe! There is no way to tell PC-DOS
to rewind the pipe.
Part 2: File commands
If you listed more than one filename on the command line which invoked PC-
More, then you can move between them with the 'n' "next file" and 'p' "previous
file" commands. When PC-More reaches the end of a file, it pauses and prints
out the following prompt:
--filename.ext [EOF]--
- 3 -
This means that there is no more data in the current file. Any of the forward
motion commands described above will automatically move to the next file on the
command line. You can go on to the next file at any time by simply typing 'n'
in responce to the prompt. The current file is closed and the next file is
opened. If you are on the last file (or if you are reading from a pipe), then
typing 'n' will cause PC-More to exit, since there is no next file.
If you wish to go to the previous file on the command line, then simply
type a 'p'. The current file is closed and the previous file is opened. If
you are reading from the first file on the command line (or from a pipe), then
'p' will have no effect other than printing a message on the last line which
says that you are already on the first file.
If you wish to read from some file that is not listed on the command line,
type 'f'. The prompt is replaced with the message:
New file:
You may now type the name of the file you wish to read from. If you make a
typo, use the backspace key to fix it. If you try to backspace over the
prompt, then the command is aborted. Likewise, if you type a control-G at any
time while entering the new filename, the command will be aborted. Control-G
can be used at any time to erase either the numeric argument or any text
arguments that some of the commands prompt for.
You may use "open new file" at any time, even when you are reading from a
pipe. The rest of the pipe is ignored. However, you will not be able to edit
the new file or push to an inferior command interpreter. These commands and
their restrictions are explained below in Part 3 of this section.
Part 3: Running Other Programs Under PC-More
If you wish to execute a PC-DOS command, run a program, or load in inferior
command interpreter, then use the '!' "push to DOS" command. '!' may be
followed by an optional command which PC-DOS is to execute. This command may
an internal PC-DOS command or a program on disk. If the '!' is not followed
by any text, then the DOS command interpreter is loaded. When a DOS command
finishes, or when a program exits, or when you type "exit" to the inferior
shell, control returns to PC-More and the last screen of data is redisplayed.
This command will NOT work properly when reading from a pipe. If you try
to push to an inferior shell, PC-More will prevent this from happening. If
you try to execute a PC-DOS command or run a program, you are asked to confirm
that you really want to do this. To confirm, type 'y'. These precautions are
- 4 -
necessary. If you were to push to an inferior shell or any program which
reads from the DOS stdin device, then the lines of data from the pipe will be
executed as if PC-DOS was reading from a batch file. This is because stdin
has been redirected, so any calls to it go to the pipe. Because of this
misfeature of PC-DOS, PC-More tries to protect you from disaster. Note that
when you are reading from a pipe and you use the 'f' "open new file" command,
stdin is still redirected and this command is still disabled.
WARNING: If you invoke PC-More from a pipe and with arguments on the
command line as you were warned not to do in Section 2, then strange things
will happen if you try to use '!'. PC-More will not know that stdin has been
redirected and will blindly let you push to an inferior shell. You will then
find out first hand what happens. No harm is done, but you must reboot you PC
to stop the process. Since a file is open when this happens, you may loose
data.
As a special case of the above command, you can call up an editor on the
current file by typing 'e', for "edit current file." The name of the editor
to use is obtained by translating the environment variable EDITOR. If EDITOR
is not set, then the PC-DOS line editor "edlin" is used. To set the environ-
ment variable EDITOR, type the following to PC-DOS before invoking PC-More:
A>set editor=whatever.exe
The word "editor" does not need to be capitalized. However, there must be no
spaces to the left of the = sign. Spaces are significant and will be part of
the variable name. PC-More will NOT recognize the following:
A>set editor = whatever.exe
If you type something like this, you will get "edlin" when you type 'e'.
If you are reading from a pipe, then 'e' is disabled, even if you use the
'f' command to switch to a real file. This is done as a precaution. If your
editor uses PC-DOS function calls to read from stdin, then you are in the same
trouble as you would be in if you pushed to an inferior shell. You editor
would begin reading from the pipe. The same warning about invoking PC-More
from a pipe and with arguments applies here as well.
Part 4: Other commands
If you forget what the PC-More commands are, type '?', which is the help
command. It will print a summary of the commands known to PC-More.
- 5 -
Typing a 'v' will print the version number of your copy of PC-More.
If you are entering a numeric argument for the motion commands or a text
argument for the '!' or 'f' commands, then you can cancel the argument by
typing control-G. This will also abort the '!' and 'f' commands and return
you to the PC-More command level.
Of course, there is a quit command for PC-More as well. Type 'q' and you
will be returned to the process which called PC-More (usually PC-DOS).
Part 5: Command Summary
Here is a summary of all PC-More commands. If you have used programs like
PC-More before (which most of you probably have), then this is probably all
you will need to be able to use PC-More:
<sp> next screen
<cr> next line
h next half screen
r rewind the current file
e edit the current file
n go to the next file
p go to the previous file
f open a new file
! push do DOS
^G clear argument or abort '!' or 'f'
? help
v print the version number
q quit to DOS
Section 4: Source Notes and Portability Concerns
PC-More is written in Computer Innovations C86 version 2.20G. The code is
pretty straight-forward and heavily commented. It should not be very hard to
determine what a piece of code does.
I made extensive use of external variables in PC-More. There are 8
external variables in the program. This is necessary because they are used by
several functions. Some of the external variables are used by only two
functions, but one function does not always call the other one directly.
Instead, funtion a() and funtion c() may both use a variable, but a() does not
call c(). Rather, a() calls b() which then calls c(). This isn't the best
style of programming, but PC-More is small and not very complicated. Besides,
- 6 -
all external variables start with the characters "x_", to they are easy to
spot.
There are only three functions used in PC-More which may not be supplied
with other C compilers. These are:
key_getc() This function reads a character directly from the keyboard
rather than from stdin. It returns an int with the ASCII
code of the character typed in the lower byte and the scan
code of the key struck in the upper byte. In PC-More, the
scan code is masked off to zero. This function will wait
for a key to be struck and the return key is not needed to
make it return.
crt_cls() This function is used to clear the screen and home the cursor.
crt_mode() The crt_cls() function has a bug in it. When it clears the
screen, the forground color (the color in which the characters
are printed), is set to zero. The call crt_mode(7) corrects
this bug. You probably don't need to use this function.
If you don't want to clear the screen each time, or you don't
have a function to clear the screen, simply eliminate all
calls to crt_cls() and crt_mode(). You should also eliminate
all references to the variable npl in the main() routine.
All the other functions I used in PC-More are available in the standard UNIX
C libraries under 4.2 BSD. If your compiler does not come with some of these
functions, look them up in section 3 of the UNIX manual to find out what they
do.
Section 5: Conclusion
As a final note to add to the end of this manual, I'd like to say that PC-More
is a public domain program. You can copy it, modify it chop it up, whatever
you want to do, but please don't sell it. I welcome any comments, bug fixes,
new features (searches and backward paging would be nice), etc. My e-mail
address is:
UUCP: ...!{ihnp4 | allegra | seismo!ut-sally}!ut-ngp!dlnash
ARPA: dlnash@ngp.UTEXAS.EDU
- 7 -