Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP
Posting-Version: version B 2.10.2 9/18/84; site watdcsu.UUCP
Path: utzoo!watmath!watnot!watdcsu!rsellens
From: rsellens@watdcsu.UUCP (Rick Sellens - Mech. Eng.)
Newsgroups: net.micro.pc
Subject: Conch Binary (3 of 4) manual (TeX)
Message-ID: <1701@watdcsu.UUCP>
Date: Thu, 26-Sep-85 14:48:47 EDT
Article-I.D.: watdcsu.1701
Posted: Thu Sep 26 14:48:47 1985
Date-Received: Fri, 27-Sep-85 04:19:10 EDT
Distribution: net
Organization: U of Waterloo, Ontario
Lines: 1139

--------------cut here----------------------------------------------------
\def\vertone{0in}				% vskip after section, heading titles
\def\verttwo{.1875in}			% vskip before section, heading titles
\def\vertthree{.5in}			% vskip between chap no. and title
\def\vertfour{.5in}				% vskip after chapter title
\def\vertfive{12pt}				% vskip between table of contents entries
\def\tcindent{\hskip 1em\relax}	% Size of table of contents indents.

\font\secfont=amr10 scaled\magstep1		% for section titles
\font\headfont=amr10 scaled\magstep1	% for heading titles
										% and "Chapter Number XX" lines
\font\chapfont=amr10 scaled\magstep2	% for chapter titles

\newbox\tcbox				% box to hold the table of contents
\global\setbox\tcbox=\vbox{ }

\newbox\refbox				% box to hold the refences list
\global\setbox\refbox=\vbox{ }

\newcount\chapno			% chapter number of current chapter
\newcount\chappage			% page current chapter began on
\newcount\secnoone			% current first level section number
\newcount\secnotwo			% current second level section number
\newcount\secnothree		% current third level section number
\newcount\secnofour			% current fourth level section number
\newcount\eqnumcount		% number of last equation
\newcount\refno				% number of last reference

\chapno=0
\chappage=1					% put the number at the bottom on page one
\secnoone=0
\secnotwo=0
\secnothree=0
\secnofour=0
\eqnumcount=0
\refno=0

% Adds a table of contents entry.
%
\def\addtblcon #1#2{
	\global\setbox\tcbox=\vbox{\unvbox\tcbox \vskip\vertfive
		\line{\rm{#1}\ifnum #2=0 \hfil \else \dotfill{#2} \fi}}}

% Adds a two line table of contents entry.
%
\def\addtblcontwo #1#2#3{
	\global\setbox\tcbox=\vbox{\unvbox\tcbox \vskip\vertfive
		\rm\baselineskip=14pt
		\line{{#1}\hfil}\nobreak
		\line{{#2}\ifnum #3=0 \hfil \else \dotfill{#3} \fi}\nobreak}}

% Produces a table of contents starting at page number #1.
%
\def\outputtc #1{\vfill\eject\centerline{\headfont Table of Contents}
	\vskip .5in
	\pageno=#1
	\unvbox\tcbox}

% Produces a section heading -- no section number.
%
\def\heading #1{\penalty -1000
	\vskip \verttwo
	\vbox{{\noindent\headfont #1}}
	\nobreak\vskip \vertone\nobreak
	\addtblcon{\ifnum\chapno=0\else\tcindent\fi
		\ifnum\secnoone=0\else\tcindent\fi
		\ifnum\secnotwo=0\else\tcindent\fi
		\ifnum\secnothree=0\else\tcindent\fi
		\ifnum\secnofour=0\else\tcindent\fi{#1}}{\number\pageno}}

% Produces a section title with a section number.
%
\def\sectitle #1{\penalty -1000
	\vskip\verttwo
	\vbox{{\noindent\secfont \secnum #1}}
	\nobreak\vskip\vertone\nobreak}

% Produces a section number for a section heading.
% (Screws up if you call too deep, i.e. a secthree right after a secone.)
%
\def\secnum {\ifnum\chapno>0 \number\chapno .\fi
	\ifnum\secnoone>0 \number\secnoone .\fi
	\ifnum\secnotwo>0 \number\secnotwo .\fi
	\ifnum\secnothree>0 \number\secnothree .\fi
	\ifnum\secnofour>0 \number\secnofour .\fi
	\ }

% Start a new chapter with title {#1}.
%
\def\chapter #1{
	\advance\chapno by 1
	\secnoone=0
	\secnotwo=0
	\secnothree=0
	\secnofour=0
	\eqnumcount=0
	\vfill\eject
	\chappage=\pageno
	\centerline{\headfont Chapter \number\chapno}
	\vskip \vertthree
	\centerline {\chapfont #1}
	\vskip \vertfour
	% add a blank line in the table of contents
	\addtblcon{\null}{0}
	% add a two line T of C entry with the chapter number line and
	% the chapter title line with a page number
	\addtblcontwo{Chapter \number\chapno}{#1}{\number\pageno}}

\def\secone #1{
	\advance\secnoone by 1
	\secnotwo=0
	\secnothree=0
	\secnofour=0
	\sectitle {#1}
	\addtblcon{\tcindent\secnum #1}{\number\pageno}}

\def\sectwo #1{
	\advance\secnotwo by 1
	\secnothree=0
	\secnofour=0
	\sectitle {#1}
	\addtblcon{\tcindent\tcindent\secnum #1}{\number\pageno}}

\def\secthree #1{
	\advance\secnothree by 1
	\secnofour=0
	\sectitle {#1}
	\addtblcon{\tcindent\tcindent\tcindent\secnum #1}{\number\pageno}}

\def\secfour #1{
	\advance\secnofour by 1
	\sectitle {#1}
	\addtblcon{\tcindent\tcindent\tcindent\tcindent\secnum #1}{\number\pageno}}

% Put the page number in the middle at the bottom if the page
% is page one, is less than zero (roman), or if the page begins
% a chapter. Otherwise put it at the top right.
\footline={\ifnum\chappage=\pageno {\hfil\rm--\ \folio\ --\hfil}
				\else {\ifnum\pageno<0 {\hfil\rm--\ \folio\ --\hfil}
						\else {\hfil}\fi}\fi}
\headline={\ifnum\chappage=\pageno {\hfil}
				\else {\ifnum\pageno<0 {\hfil}
						\else {\hfil\rm\folio}\fi}\fi}

% Macros for producing sequentially numberred endnote references.
% \ref, \rref, etc. should appear *immediately* following the word
% and any punctuation the reference is to be attached to.
% e.g. these references are dirty,\ref
%      {Text for endnote number one.}
%      and they make no\rref
%      {Text for endnote number two.}
%      {Text for endnote number three.}
%      sense at all.
%
\def\ref #1{\global\advance\refno by 1
	\refsuperscript {\number\refno}\addref{\number\refno}{#1}}

\def\rref #1#2{\global\advance\refno by 1
	\refsuperscript{\number\refno,
	\addref{\number\refno}{#1}
	\global\advance\refno by 1
	\number\refno}\addref{\number\refno}{#2}}

\def\rrref #1#2#3{\global\advance\refno by 1
	\refsuperscript{\number\refno,
	\addref{\number\refno}{#1}
	\global\advance\refno by 1
	\number\refno,%
	\addref{\number\refno}{#2}
	\global\advance\refno by 1
	\number\refno}\addref{\number\refno}{#3}}

\def\refsuperscript #1{\mathsurround=0pt $^{#1}$}

\def\raisedrefs{
	\def\refsuperscript ##1{\mathsurround=0pt $^{##1}$}}

\def\bracketrefs{
	\def\refsuperscript ##1{\mathsurround=0pt $\,[{##1}]$}}

\def\addref #1#2{\global\setbox\refbox=\vbox{\unvbox\refbox
		\vskip\parskip
		\vbox{\parindent=0pt
			\hangindent=25pt
			\hangafter=1
			{[#1]~{#2}}\par}}}

% Produces a list of references.
%
\def\outputref{\vfill\eject\centerline{\headfont References}
	\vskip\parskip
	\unvbox\refbox}

% End of numberred endnote macros

% Produces an equation number enclosed in parentheses.
% If the chapter is non-zero the number will be of the
% form 1.17 for the seventeenth equation in chapter one,
% otherwise the number will be a simple integer.
%
\def\eqnum {(\ifnum\chapno>0 {\number\chapno .}\fi
	\global\advance\eqnumcount by 1
	\number\eqnumcount)}

% Use for putting the lower argument of limits a little lower
\def\sub #1{{\lower 2pt\hbox{$\scriptstyle{#1}$}}}

\magnification=\magstep1	% make everything 1.2 times larger
\baselineskip=20pt			% vertical line spacing
\parskip=12pt				% additional space between paragraphs
\hsize=6 true in			% horizontal line width
\vsize=8.5 true in			% vertical height of text
\voffset=-.75 true in		% correction fx80 past tof

% Make the space around displays bigger than standard
\abovedisplayskip=18pt plus 3pt minus 9pt
\belowdisplayskip=18pt plus 3pt minus 9pt
\widowpenalty=300
\clubpenalty=300

\footline={\ifnum\pageno<1 {\hfil}
				\else {\hfil\rm--\ \folio\ --\hfil}\fi}
\headline={\hfil}

\baselineskip=12pt			% vertical line spacing
\parskip=8pt				% additional space between paragraphs
\hsize=6 true in			% horizontal line width
\vsize=8.5 true in			% vertical height of text
\voffset=-.75 true in		% correction fx80 past tof
\pageno=0

\def\point {\parindent=0in\hangindent=.75in\hangafter=1}

\ 

\kern 1in
{\chapfont\centerline{Conch}}
\kern 3em
{\baselineskip=20pt\headfont
\centerline{An Enhanced Command Shell}
\centerline{For IBM PCs And Compatibles}
\centerline{Running MS-DOS}
\kern .5in
\centerline{Version 1.00}
\kern .5in
\centerline{Written by}
\centerline{Richard W. Sellens}
}

\vfil
\centerline{\copyright\ R.W. Sellens 1985}
\kern 2em

\noindent Trademarks

{\sevenrm
\settabs\+\quad&MS-DOS\qquad&\cr
\+&IBM&- International Business Machines Corporation\cr
\+&MS-DOS&- Microsoft, Inc.\cr
\+&Unix&- AT\&T, Bell Labs\cr
\+&DeSmet&- DeSmet Software\cr}
\eject
\pageno=0
This program is shareware.

You are encouraged to copy the executable code and documentation and
distribute it to others, subject to these simple conditions:

{
\point\qquad$\bullet$
This program and documentation are copyright. The copyright and all 
other rights to this program remain the property of the author, 
Richard W. Sellens.

\point\qquad$\bullet$
This program and documentation are not to be distributed in modified 
form.

\point\qquad$\bullet$
This program and documentation are not to be distributed for profit.

\point\qquad$\bullet$
The author will not be responsible for any damages arising from the 
use, misuse, or inability to use this program.

}

The essentially unrestricted distribution of this program allows you, 
the end user, to test the program under your own operating
conditions and determine whether or not it is useful to you. If you 
make regular use of this program I ask that you make a contribution to 
my continuing software development efforts. Please send \$25 license 
fee to:

\kern\parskip
{\settabs\+\kern 1in&\cr
\+&Richard W. Sellens\cr
\+&372A Churchill Court\cr
\+&Waterloo, Ontario\cr
\+&Canada\quad N2L 6B4\cr}

\noindent A receipt will be provided on request.

If you find any bugs in the program, or have any suggestions for 
improvements, please let me know by mail at the above address.

\vfill\eject
\heading{Introduction to Conch}

As anyone who has used MS-DOS must have noticed, the command processor supplied
with the operating system is quite simple.  People who have used the facilities
available on Unix systems must long for a more sophisticated, powerful shell. 
Those who spend a lot of time interacting with the computer at the command line
level could benefit from a more comfortable way to make use of the basic
command processor features.  Conch does not provide a fully programmable shell,
but it does provide many of the comfort features.

{
\point
{\bf Command line editing} - Conch uses the PC editing keys in just the manner that
one would expect.  This makes it much easier to enter commands and correct
errors.

\point
{\bf I/O redirection} - Conch performs I/O redirection and piping itself, using
the same command line format as the DOS shell.

\point
{\bf History} - Conch maintains a buffer of previously entered command lines
which can be recalled to the command line, edited, and re-executed.  This is
done using the vertical cursor motion keys to select the desired command.

\point
{\bf Command Aliasing} - It is often desirable to call a given command sequence
by another name.  This allows the shortening of long command strings to simple
mnemonics as well as the reassignment of the standard command names to names
which make more sense to the user.

\point
{\bf Virtual Device Names} - On hard disk systems with complex directory tree
structures it can be difficult to remember the exact paths to directories that
are in common use.  Also, it is painful to type a long path name for every
directory reference.  Conch allows you to define virtual device names to
shorten and simplify command line path references.

}

Conch is written in DeSmet C, and uses only standard MS-DOS function calls,
with one exception: IBM PC BIOS interrupt 10 hex is used to access the video
screen.  The net result is that Conch should run on any machine that makes a
half hearted attempt to be compatible with the IBM PC.

\vfill\eject   
\heading{Starting Conch}

Two things should be done at the DOS level, perhaps in an autoexec.bat file,
before starting Conch:

{
\point
\qquad$\bullet$\quad The command search path should be set to the desired value
using the DOS path command.  This cannot be changed from within Conch.

\point
\qquad$\bullet$\quad The prompt string should be set to the desired value using
the DOS prompt command.  This cannot be changed from within Conch.

}

\noindent Conch is then invoked by typing 

{\tt conch}

\noindent Conch will load, display a banner with the version number and
copyright notice and initialize itself.  As part of this initialization Conch
will look for a file named {\tt conchrc} in the current directory.  Commands
will be taken from this file and executed, just as if they had been typed at
the command line, but they will not be recorded as history.

If the default directory is changed before Conch is invoked, then Conch will
take {\tt conchrc} from the new directory, rather than the root directory. 
This makes it possible to provide different initialization procedures for
different users.  A simple start-up program can be used to switch to a user's
home directory before Conch is invoked, thus controlling the initialization
file used.

\vfill\eject   
\heading{The Command Line Editor}

When Conch is started it will perform some initialization and then display the
command prompt, just as the DOS shell does.  You may then enter a command, just
as you would with DOS, using the alpha-numeric keys followed by a carriage
return.  If your typing is perfect then you will notice no difference.  If
however, you are prone to error like the rest of us, the following features
will make it easy to modify the command as typed so far.

{
\point
{\bf Motion} - The left and right arrow keys will move the cursor one space
left or right, but will move no further left than the first character of the
command line and no further right than the first space beyond the end of the
current command line.  The {\tt Home} and {\tt End} keys will move the cursor
to the beginning and end of the command line respectively, while the {\tt Esc}
key will move the cursor to the beginning of the command line and erase
anything typed so far.

\point
{\bf Delete} - The {\tt Del} key will delete the current character, unless the
cursor is at the end of the line, in which case it has no effect.  The
backspace key deletes the character immediately to the left of the cursor and
moves the remainder of the line in, unless the cursor is at the beginning of
the line, in which case it has no effect.

\point
{\bf Insert} - Normally a character typed at the keyboard will overtype the
character under the cursor.  The {\tt Ins} key toggles the insert mode on and
off.  When in insert mode, characters typed at the keyboard are inserted before
the current character.  When insert mode is on the cursor will appear as a
block, rather than the usual underbar.

}
If this sounds familiar, it is because it duplicates the line editing
facilities of the BASIC interpreter at the command line.  This capability
simplifies the entry of commands and makes it easy to edit previous commands
called up from the history facility of the shell.

In addition to these editing capabilities, there are two key combinations that
have a special effect at the command line.  {\tt Alt-H} will cause the current
contents of the command line to be added to the history buffer.  {\tt Alt-P}
will cause the current contents of the command line to be added to the pending
commands list.  In neither case will the command be executed, it will just be
stored.

\vfill\eject   
\heading{What Does a Command Line Look Like?}

The most general form of the command line is:

{\tt [;]...}

\noindent Any number of command groups may be entered on a line, separated by
semicolons, subject only to the maximum allowable length of a line.  (The DOS
imposed maximum is 128 characters.) Each command group will be executed in
sequence, just as if they had been entered on succeeding command lines.  This
feature is an extension of the DOS command processor.

Conch will treat any command line which starts with a period (.) as a null
line.  This is consistent with DOS, and provides a way to include comments in
command lists.

A command group has the same form as the command line described in the DOS
manual.  In its simplest form a command group contains only the name of the
command to be executed, but it may also contain arguments, pipes, and I/O
redirection.

{\tt  [arg...][| [arg...]...][]>outfile]}

\noindent If a pipe ({\tt |}) is used to join commands, then the data sent to
standard output by the first command is fed to the standard input of the second
command.  Any number of commands may be piped together in this way.  See the
section titled Pipes and/or the DOS manual for further details.

If arguments are found that begin with one of `{\tt <}', `{\tt >}', or `{\tt
>>}' the remainder of that argument is used as a source or destination for I/O
redirection.  `{\tt <}' indicates a source file or device which is to replace
the current standard input device.  `{\tt >}' indicates a destination file or
device that is to replace the current standard output device.  If the file
exists the current contents will be replaced.  `{\tt >>}' is the same as `{\tt
>}', except that the output will be appended to the current contents of the
file, if any.  See the DOS manual for further details.

Commands and arguments are separated by spaces or tabs as delimiters.  Spaces
are optional around pipes, semicolons, and preceding I/O redirection.  Quotes
may be used to prevent special characters such as `{\tt |}', `{\tt ;}', `{\tt
<}', `{\tt >}', tabs and spaces from being interpreted by the shell.  See the
section titled Parsing of the Command Line for details.

\vfill\eject   
\heading{Command History Mechanism}

Conch automatically saves each command typed at the keyboard in a buffer for
future reference.  When the buffer fills, the oldest commands are discarded to
make room for new ones.  The number of commands that are available is dependent
on the size of the buffer, buffer utilization by the other features of Conch,
and the lengths of the commands that were saved.  Generally the buffer will
hold more history than you need, but if the amount saved is insufficient it
will be necessary to move up to a version of the shell that was created with a
larger buffer.

When Conch gives you the command prompt you may enter a command using the
editing keys as described in the Command Line Editor section, or you may select
a previously typed command from the history buffer.  While on the command line,
the up and down arrow keys will move you through the history buffer, displaying
a previously entered command on the current command line.  The up arrow moves
backward in time, while the down arrow will move you forward.  The buffer does
not wrap, so that eventually you will reach the oldest available command entry
and go no further.

Additionally, if the {\tt PgUp} key is pressed while on the command line, it
will provide a display of a page of the history buffer so that commands appear
in context.  Each line of the display will contain an old command, or just the
first part of the command if the complete command would have run off the
screen.  An indicator points out the currently selected line of history and, as
before, the selected history line will appear in its entirety on the
current command line.  In this display mode the up and down arrow keys will
still move through the history buffer one command at a time, while the {\tt
PgUp} and {\tt PgDn} keys will move up or down in larger increments.

Once the desired command has been selected it may be executed as is, simply by
pressing carriage return, or it may be edited just as if the text of the
command had been entered from the keyboard.  Any modifications made to the text
on the command line will have no effect on the image of the old command stored
in the history buffer.  Also, when you re-execute the command it will be stored
in the history buffer again, whether or not it was modified.

In addition to the history buffer, Conch maintains a pending commands buffer. 
Commands are added to the buffer by using {\tt Alt-P} to store the current
command line, or by reading them in using the {\tt -r} option of the {\tt
pending} command.  The {\tt pending} command also allows you to display the
contents of the buffer, execute the commands in the buffer, write them to a
file, or flush the buffer.  See the command summary for details.

\vfill\eject
\heading{Command Aliasing}

Conch maintains a list of command aliases which are input by the user.  A
command alias is essentially a statement that ``When I say this, I really mean
that.''.  An alias is added to the shell's list by using the {\tt alias}
command.

{\tt alias  }

\noindent {\tt } is the name that you will use to request a particular
action and {\tt } is the command line to be used to produce
that action.  For example

{\tt alias dir ls -l}

\noindent tells Conch that each time you enter the command {\tt dir}, it should
execute the command {\tt ls -l}.  This can be extremely useful, especially for
the more complex commands.

{\tt } must be a string of less than 64 characters containing only the
letters {\tt A} through {\tt Z}, the digits {\tt 0} through {\tt 9} and the
characters

{\tt   \$   \#   \&   @   !   \%   (   )   -   $\{$   $\}$   \_}

\noindent All alias names are converted to lower case for storage, making Conch
case independent just like DOS.

If the previously aliased {\tt } is followed by arguments on the command
line they are usually just transferred to the end of the {\tt }, and separated from it by whitespace.  The command entry

{\tt dir $\backslash $temp$\backslash $idea}

\noindent would be translated into

{\tt ls -l $\backslash $temp$\backslash $idea}

\noindent for execution.  The exception comes when {\tt }
contains one or more occurrences of the tail substitution character.  (The tail
substitution character is initially set as `{\tt\$}' but it can be changed to
any other character using the {\tt tsub} command.) If the tail substitution
character occurs in the replacement string, in each instance it will be
replaced with the command tail.  The command tail will be stripped of leading
and trailing whitespace so that if this alias is set,

{\tt alias killer "del file\$.bak ; del dud\$.*"}

\noindent (Note that quotes are required around the replacement string to
prevent Conch from interpreting the semicolon before it is sent to the {\tt
alias} command.)

{\tt killer 1}

\noindent will be expanded to

{\tt del file1.bak ; del dud1.*}

\noindent and

{\tt killer test}

\noindent will be expanded to

{\tt del filetest.bak ; del dudtest.*}

If the {\tt alias} command is issued with a name which is already aliased, then
the new alias definition will replace the old.  No warning or diagnostic
message will be issued.  If an alias is to be removed, rather than redefined,
the {\tt unalias} command is used.  It takes the form:

{\tt unalias  }

\noindent where {\tt } is the name of a previously defined alias.

The aliasing mechanism is fully recursive, so aliases may be defined in terms
of other aliases.  There is a check on the recursion to prevent either direct,
or indirect circular recursion.

{\tt alias ls ls -l}

\noindent will result in one substitution, giving {\tt ls -l} whenever {\tt ls} is entered.

{\tt alias ls dir -l}

{\tt alias dir ls}

\noindent will result in two substitutions, giving {\tt ls -l} whenever {\tt
ls} is entered.

\vfill\eject   
\heading{Virtual Device Names}

When tree structured directories grow, the paths to the directories can become
long, and perhaps hard to remember.  The use of virtual device names makes it
easier to remember the names of commonly used directories, as well as easing
the typing load.  A virtual device is defined by the {\tt vdev} command

{\tt vdev  }

\noindent and can be redefined by issuing another {\tt vdev} command for the
same name.  {\tt } must be at least 2 characters long, so as not to
conflict with the single letter disk drive identifiers.

For example, the text of my thesis might be stored in a directory named\break
{\tt c:$\backslash $rick$\backslash $school$\backslash $thesis$\backslash $}. 
A virtual device could be created by

{\tt vdev thesis c:$\backslash $rick$\backslash $school$\backslash $thesis$\backslash $}

\noindent Any time the characters {\tt thesis:} appear at the start of a token
they will be replaced by the replacement string; in this case {\tt
c:$\backslash $rick$\backslash $school$\backslash $thesis$\backslash $}.  Thus

{\tt type thesis:chap1}

\noindent will be expanded to

{\tt type c:$\backslash $rick$\backslash $school$\backslash $thesis$\backslash $chap1}

\noindent In the special case where the name and colon form the entire token,
any trailing backslash will be removed, so that

{\tt cd thesis:}

\noindent will be expanded to

{\tt cd c:$\backslash $rick$\backslash $school$\backslash $thesis}

\noindent just the way it should be.

Also, simply declaring a virtual device name on the command line will take you
to the directory it represents.  This is analogous to using {\tt a:} to move to
drive A.  This means that

{\tt thesis:}

\noindent is almost equivalent to

{\tt cd thesis:}

\noindent The difference is that {\tt cd thesis:} will change the default
directory of drive C to {\tt $\backslash $rick$\backslash $school$\backslash
$thesis} without changing the default drive, while {\tt thesis:} will also
change the default drive to ``take you there''.  On machines with a single hard
disk, where the default drive is likely to remain constant, the two are
interchangeable.

The virtual device name facility is fully recursive, so virtual device names
may be defined in terms of other virtual device names.

{\tt vdev old thesis:old$\backslash $}

\noindent will set up {\tt old:} to be expanded into {\tt c:$\backslash
$rick$\backslash $school$\backslash $thesis$\backslash $old$\backslash $}.  Any
circular reference, where a virtual device name is defined in terms of itself,
will cause an error.

To complement the virtual device naming capability, Conch keeps a list of
reserved device names.  The {\tt rdev} command is used to add a device name to
the list.

{\tt rdev }

\noindent The {\tt vdev} command will generate an error if the user tries to
create a virtual device with the same name as a previously defined reserved
device.  This is the only purpose of the reserved device name facility.

The rules given for legal characters in {\tt alias} names also apply to both
{\tt vdev} and {\tt rdev} names.  They are also stored in lower case, making
them case independent.

\vfill\eject
\heading{Summary of Conch Internal Commands}

This section lists all of the Conch internal commands, and provides the
mechanical details of their use.  For further information, and examples of the
more complex commands, see the narrative sections of the manual.

\vskip .125in
{\tt\noindent alias [ ]}

{\parindent=.25in\hangindent=.25in
Instructs the shell to substitute a replacement string for the command {\tt
} in future.  If {\tt } contains special characters
like `{\tt |}', `{\tt ;}', `{\tt >}', `{\tt <}, etc., enclose the string in
either single ({\tt ''}) or double ({\tt ""}) quotes to prevent their
evaluation before substitution.  If no arguments are given, the current list of
aliases is printed.

}
\vskip .125in
{\tt\noindent cd [d:][]}

{\parindent=.25in\hangindent=.25in
Behaves just like the DOS {\tt cd}, except that {\tt } may include a
virtual device name.

}
\vskip .125in
{\tt\noindent exit}

{\parindent=.25in\hangindent=.25in
Leaves Conch and returns to DOS.

}
\vskip .125in
{\tt\noindent history [-n []]}

{\parindent=.25in\hangindent=.25in
Prints out the complete history buffer, in the order in which the commands were
entered.  If an argument is included the results will be:

}
\vskip 8pt
{\settabs\+&\kern .375in{\tt -w[n] }\quad&\cr
\+&\hfill{\tt -f}\quad&the history buffer is flushed, eliminating all previous\cr
\+&\hfill&entries.\cr
\+&\hfill{\tt -w[n] }\quad&writes the most recent {\tt n} commands
from the contents\cr
\+&\hfill& of the history buffer to {\tt }.\cr
\+&\hfill{\tt -r }\quad&reads in command lines from {\tt 
} and adds\cr
\+&\hfill&them to the history buffer.\cr
}

\vfill\eject
{\tt\noindent pending [-n []]}

{\parindent=.25in\hangindent=.25in
Prints out the list of pending commands if no arguments are given.  If
arguments are included the results will be:

}
\vskip 8pt
{\settabs\+&\kern .375in{\tt -w }\quad&\cr
\+&\hfill{\tt -e}\quad&the pending commands are executed. They will 
not be\cr
\+&\hfill&recorded as history, since they were not entered from\cr
\+&\hfill&the command line.\cr
\+&\hfill{\tt -f}\quad&the pending command list is flushed, 
eliminating all\cr
\+&\hfill&previous entries.\cr
\+&\hfill{\tt -w }\quad&writes the contents of the pending 
command list to\cr
\+&\hfill&{\tt }.\cr
\+&\hfill{\tt -r }\quad&reads in command lines from {\tt 
} and appends\cr
\+&\hfill&them to the pending command list.\cr
}

\vskip .125in
{\tt\noindent rdev []}

{\parindent=.25in\hangindent=.25in
Adds {\tt } to the reserved device name list.  If no argument is given, a
list of the defined reserved device names is printed.

}
\vskip .125in
{\tt\noindent source }

{\parindent=.25in\hangindent=.25in
Takes command input from a file, rather than the keyboard.  This provides the
most rudimentary of batch facilities.  The commands in {\tt } will
not be recorded as history, since they were not entered from the command line.

}
\vskip .125in
{\tt\noindent tsub []}

{\parindent=.25in\hangindent=.25in
Sets the tail substitution character to the first non-blank character after
{\tt tsub}.  If there is no argument, the current tail substitution character
is displayed.

}
\vskip .125in
{\tt\noindent unalias }

{\parindent=.25in\hangindent=.25in
Removes the alias entry, if any, for {\tt }.

}
\vskip .125in
{\tt\noindent vdev [ ]}

{\parindent=.25in\hangindent=.25in
Adds {\tt } to the virtual device name list, so that in future {\tt
name:} at the beginning of a token will be replaced with {\tt }.  If no arguments are given, the current virtual device name list will
be printed.

}
\vfill\eject
\heading{Parsing of the Command Line}

To interpret the Conch command line it is necessary to take it apart, massage
it a bit, and reassemble it.  This is called parsing and processing.

For the most part Conch parsing is very simple; a command is composed of tokens
which are separated by whitespace.  (Whitespace is the generic term for
characters such as spaces or tabs, appearing singly or in a group.) When the
command is processed the tokens are separated, and the whitespace between the
tokens is thrown away.  After the tokens are processed, they are reassembled
into a command with new whitespace between them.  This will have no effect on
the execution of the command, unless the exact configuration of the whitespace
was important.  Conch will not preserve bizarre combinations of whitespace
between tokens.  Thus, if your application is sensitive to the configuration of
whitespace, special measures may be needed.

After the command line is broken into tokens, it is checked for semicolons.  If
any are found the line is broken into separate command groups which are
sequentially fed back into the top of the processor.  Then any I/O redirection
is stripped out.  (Conch is not sensitive to the position of I/O redirection
tokens in the command group.) If a command group contains pipes it is broken
into separate commands, with appropriate redirection to temporary files, and
fed back into the top of the processor.

Once it is dealing with a single command the processor tests the first word for
alias substitution.  If a substitution results in multiple commands (using
either semicolons or pipes) the command group is fed back into the top of the
processor.  The processor then tests each token to see if it begins with a
recognized virtual device name, and if so, makes the necessary substitution.

Any I/O redirection required is set up.  Any quotes within the command string
are removed, unless they are preceded by a backslash ($\backslash$), in which
case the backslash is removed.  If the command is one of the internal commands
the appropriate function is called.  Otherwise, Conch looks in the current
directory and down the search path for the named command as either a .com,
.exe, or .bat file.  If found, it is executed and passed a tail composed of all
the remaining tokens, separated by spaces.

The tail will also have one leading space, so that it will appear to the
application that it was invoked from the DOS command line with exactly one
space between the command name and the arguments.  Some badly written programs
process the command tail based on the assumption that it has exactly one
leading space.

\vfill\eject
\heading{Quotation Marks}

Single ({\tt ''}) and double ({\tt ""}) quote pairs can be used to keep the
parser from messing with portions of the command line.  Anything within single
or double quotes will be untouched by the parser.  The quotes will be removed
before the command tail is passed to the command itself.

This is useful for maintaining peculiar whitespace combinations, and for
slipping normally significant characters past the command processor.  The
command

{\tt grep " ;"}

\noindent will result in {\tt grep} being invoked and passed a command tail
composed of two spaces and a semicolon.  (The first space is the one separating
the command and the tail, while the second comes from within the quoted
string.) If the quotes were not present, Conch would interpret the semicolon as
a command separator, and would ignore the superfluous space.  The result would
be the same if single quotes ({\tt ''}) had been used, rather than double
quotes.

The next question is ``How do you include quotes on the command line as
characters, rather than delimiters?''.  To include quotes as characters they
must be preceded by a backslash ($\backslash $).  For example

{\tt grep $\backslash $'"$\backslash $" ;"}

\noindent would invoke {\tt grep}, and pass it a command tail made up of a
space, a single quote, a double quote, a space and a semicolon.
   
\heading{Pipes}

Since DOS is not multi-tasking, it is not possible to implement ``true'' pipes. 
The technique used by Conch is the same as that used by {\tt command.com}. 
Piped commands are converted into a sequentially executed series of commands
with I/O redirection through temporary files.

Under Conch these files have names of the form {\tt temp:\%pipexx} where {\tt
xx} is a two letter combination that varies to differentiate between files, and
{\tt temp:} is a virtual device name which must be defined by the user before
piping is used.  If a RAM disk is being used, setting {\tt temp:} to represent
a directory on the RAM disk will result in much faster execution of piped
commands.

Conch ensures that the {\tt xx} in the pipe filenames are different for each
file created, but if multiple copies of Conch are active, then the pipe
filenames will not be unique.  This will cause problems if commands containing
pipes are piped into a second copy of Conch.  For example, the command:

{\tt dummy | conch | cat}

\noindent will not behave properly if {\tt dummy} feeds piped commands to {\tt
conch}, because the pipefile names will conflict.  This is a bug, but one that
is unlikely to cause significant inconvenience, or even be evident to most
users.

\vfill\eject   
\heading{Command.com and MS-DOS Internal Commands}

Conch installs itself on top of {\tt command.com}, and uses some of the
features provided by {\tt command.com}, such as the 4B hex function call for
executing a program.  This is not as much of penalty as might be expected. 
Only the resident portion of {\tt command.com} is retained, and its size is
only a couple of Kbytes.

Conch does not provide most of the internal commands that exist in {\tt
command.com}.  These commands are not lost to the user.  They can still be run
by invoking {\tt command.com} with the {\tt /c} option; i.e.,

{\tt command /c dir}

\noindent This is extremely bulky, but the internal commands can be aliased.

{\tt alias dir command /c dir}

\noindent will make {\tt dir} behave just the way it does when issued at the
DOS command line.

Invoking {\tt command.com} to perform DOS tasks takes a little longer.  On my
PC with a 10 Mbyte hard drive it takes about three quarters of a second longer
to start the task.  In my opinion, this delay is not particularly noticeable,
as the commonly used DOS internal commands are I/O bound anyway, so the
response is never instantaneous.

Using {\tt command.com} to perform program loading and internal commands allows
for complete compatibility with a bare DOS system, so that you will be hit with
a minimum number of surprises.  It also means that Conch is independent of DOS
version.  If a new version of DOS is issued, with an expanded or different
command set, just change the aliases.  I feel that these advantages outweigh
the minor performance disadvantage.

It is a quirk of DOS that whenever a new {\tt command.com} is invoked, it must
be the same copy as the machine was booted from.  Because of this, the first
copy of {\tt command.com} found down the search path must be the one that you
booted from.  This will usually mean including {\tt c:$\backslash $} as one of
the path elements.  Alternatively you could alias {\tt command} to {\tt
c:$\backslash $command}, so as to be specific.

\vfill\eject
\heading{Batch Files}

Conch runs batch files by invoking {\tt command.com}.  This means that none of
the features of Conch are available inside the batch file.  However, when a
batch file is run, the command line arguments will be processed by Conch before
they are passed to {\tt command.com}, so virtual device names, etc.  may be
used on the command line.

Commonly used batch files tend to be just lists of commands, without any use of
the flow control and other batch file features provided by DOS.  Batch files of
this type can be replaced by aliasing, if the list of commands is short, or by
using the {\tt source} command if the list of commands is longer.  See the
sample {\tt conchrc} for an aliasing example.

\vfill\eject
\heading{Error Messages Produced by Conch}

If Conch detects an error it will print out one of the messages contained in
this section.  It may also print a line of text to provide a clue concerning
the cause of the error, or an explanation.  Most error messages produced by
Conch are self explanatory.

{\tt\noindent Bad Alias Name.}

{\tt\noindent Bad Command Name.}

{\tt\noindent Bad Device Name.}

{\tt\noindent Bad Filename.}

{\tt\noindent Bad Path Name.}

If Conch says something is ``bad'', then that thing either does not exist, or
Conch was unable to find it, or in the case of a device it has already been
defined as a reserved device name.

{\tt\noindent Illegal Character in Name -- A-Z, 0-9, \$\#\&@!\%()-${}$\_ Permitted.}

An attempt was made to define an alias, virtual device name or
reserved device name containing characters other than those
permitted.

{\tt\noindent Command Too Long When Expanded.}

DOS restricts commands to a maximum of 128 characters.  Conch will not allow
you to input a command that is longer than that, however, if subsequent
expansion of the command would make it longer than 128 characters this error
message is generated.

{\tt\noindent Extra Arguments Supplied to Internal Command.}

Too many arguments were given when invoking a Conch internal command.

{\tt\noindent Insufficient Pointer Space.}

{\tt\noindent No More Space in Main Buffer.}

{\tt\noindent Out of Memory.}

{\tt\noindent Recursion Too Deep -- Need Larger Memory Version.}

Any of these errors indicate that you were asking Conch to do something that
was too big or too complex for the version of the program installed.  This
includes things such as defining more aliases, etc.  than will fit in the space
allotted for the buffer or pointers, or asking Conch to evaluate a complex
command group involving many levels of recursion in the definition of aliases
or virtual device names.

The solution to the problem is to use a larger memory version of the program. 
On the distribution disk are several sequentially numbered versions of the
program.  ({\tt conch1.exe, conch2.exe,} etc.) The higher the number, the
larger the amount of working space provided for Conch.  Naturally, using a larger
memory version of the program will leave less of your machine's memory
available to run applications in.

{\tt\noindent Warning -- Unmatched Single or Double Quotes.}

If Conch finds unmatched quotes it will issue this warning message.  It will
proceed with the execution of the command, but the entire portion of the line
after the last quotation mark will be treated as a single token.  The effect
will be the same as if a closing quotation mark had been added at the end of
the line.

{\tt\noindent Could Not Open File -- Probably Disk Full.}

{\tt\noindent Error Writing File -- Probably Disk Full.}

These two are self explanatory

{\tt\noindent Unspecified error.}

This message will appear if the program just run terminated with a non-zero
exit code.  The exit code is mechanism provided by DOS which allows a program
to communicate its exit status to the program that invoked it.  Usually a
non-zero exit code means the program terminated due to some error condition.

This message will also be displayed if one of Conch's internal routines returns
an unforseen error code.  This should not happen.  If it does please contact
the author with details of how the error occurred, and how it can be repeated.

\outputtc {0}
\vfill\eject
\pageno=0
\heading{Ordering Information for the Program and Source Code}

A complete copy of the source code for Conch is available for personal use
only.  It is written in the DeSmet C language, with some imbedded assembly
code.  A signed and dated copy of the declaration below must accompany your
order.

\parskip=4pt

Please send me a copy of the complete source code for Conch.  This source code
is to be used only by me, or by my agents under my supervision.  No portion of
the source code, or any executable code produced from it will be distributed to
a third party.

I understand that this program and documentation are copyright and that the
copyright and all other rights to this program remain the property of the
author, Richard W.  Sellens.

I also understand that the author will not be responsible for any damages
arising from the use, misuse, or inability to use this program.

\kern\parskip
\kern\parskip
{
\settabs\+\quad&Address\quad&\kern 1.7in&\qquad&Signature\quad&\cr
\+&\hfill Name\quad&\hrulefill&&\hfill Signature\quad&\vrule height0pt 
depth.4pt width1.5in\cr
\+&\hfill&\hfill&&\hfill Date\quad&\vrule height0pt 
depth.4pt width1.5in\cr}
\kern\baselineskip
\hrule

\heading{Order Form\qquad -- \qquad Conch Shell Program}

\hangindent=1in\hangafter=1
Demo Diskette -- Software and manual text on diskette.

\qquad\qquad\vrule height0pt depth.4pt width.5in\quad copies at \$10 
each\hfill\$\vrule height0pt depth.4pt width1in

\hangindent=1in\hangafter=1
Conch Program Package -- Software on diskette complete with hardcopy manual. 
Includes \$25 license fee.

\qquad\qquad\vrule height0pt depth.4pt width.5in\quad copies at \$35 
each\hfill\$\vrule height0pt depth.4pt width1in

\hangindent=1in\hangafter=1
Conch Source Package -- Software and source code on diskette complete 
with hardcopy manual. Includes \$25 license fee. A signed and dated 
copy of the declaration above must be provided for each copy ordered.

\qquad\qquad\vrule height0pt depth.4pt width.5in\quad copies at \$50 
each\hfill\$\vrule height0pt depth.4pt width1in

\hfill Total\qquad\$\vrule height0pt depth.4pt width1in

\hfill Ontario residents add 7\% P.S.T.\qquad\$\vrule height0pt 
depth.4pt width1in

\hfill Enclosed with this order\qquad\$\vrule height0pt depth.4pt width1in

\kern\parskip
\kern\parskip

Name\quad\vrule height0pt depth.4pt width2in

Address\quad\vrule height0pt depth.4pt width3in

\qquad\qquad\vrule height0pt depth.4pt width3in
\vskip .1in
\noindent Mail to: R.W. Sellens, 372A Churchill Ct., Waterloo, Ont., 
Canada  N2L 6B4
\bye