gno/doc/refs/gsh/interact.docbook

<!--
;; $Id: interact.docbook,v 1.1 2012/08/25 07:19:02 gdr Exp $
-->

<chapter id="gsh-interact">
<title>Interacting with the GNO Shell</title>

<section id="gsh-interact-exec">
<title>Executing Commands</title>

<para>A command consists of two parts: a name and
its arguments. The command name is the name used to start the
command. The name is usually the name of a file which can be
executed. The only exceptions are commands which are built-in to
the shell. These commands are documented in 
<xref linkend="gsh-commands"/>.
Any shell utility command with a filetype of EXE,
SYS16, or EXEC, can be executed in this fashion. The command name
must be separated from the command arguments with a space.</para>

<para>The command arguments are parameters that
the command takes as data to work with (In Applesoft BASIC,
"HELLO WORLD" would be an argument for the <command>PRINT</command>
command).
Command arguments are separated from each other with a space.
Note that although arguments extend the usefulness of a command,
not all commands have arguments. Any arguments entered after the
command will be passed by the shell to the program when it starts
exectuting. </para>

<para>The examples below use the following
commands:</para>

<informalexample>
<screen>
qtime		displays time in English text
echo		prints arguments to the screen
</screen>
</informalexample>

<para>Examples:</para>

<informalexample>
<screen>
<prompt>% </prompt><userinput>qtime</userinput>
It's almost five.
<prompt>% </prompt><userinput>echo II Infinitum</userinput>
II Infinitum
</screen>
</informalexample>


<para>At the simplest level the user enters
commands to the shell by typing them on the keyboard. <command>gsh</command>
includes a command-line editor to help the user enter and edit
commands. The editor also provides a way to modify and execute
previous commands. Additionally the editor can help complete the
names of commands, filenames and variables.</para>

</section>

<section>
<title>Commandline Editing</title>

<para>The following sections provide a complete description of the
functions of the command-line editor with short examples
depicting how each editing key works.</para>

<para>Throughout the examples the underline character, "_", 
will be used to represent the current cursor
position. In addition, "OA" is used to represent the
Open Apple key and the term <parameter>word</parameter> is used to indicate a
string of characters consisting of only letters, digits, and
underscores. To the right of a editing key entry is the 
<command>bindkey</command> function name which is used to remap
editing functions to new keys. This information is included for
reference purposes only. See <xref linkend="gsh-commands"/> for
more information on the <command>bindkey</command> command.
</para>

<para>It should be pointed out that at this stage
that the user should not be concerned with what the actual
commands used in the examples do, rather the user should
concentrate on how the command-line editor functions work.</para>

</section>

<section>
<title>Command Input</title>

<para>
These command-line editor keys
deal with entering text directly on the command-line.</para>

<variablelist>

<varlistentry>
<term>
RETURN
</term>
<listitem>
<para>
Newline.
</para>
<para>
The return key is used to terminate
line input. <command>gsh</command> then interprets the command on the
line and acts accordingly. The position of the cursor on the
command-line does not matter.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
CTRL-D
</term>
<listitem>
<para>
(no bindkey name)
</para>
<para>
Causes <command>gsh</command> to exit if it was the first
character typed on the command-line. If there are still jobs
running in the background or stopped, <command>gsh</command> will display
the message "There are stopped jobs".  If you press CTRL-D a
second time without an intervening command, <command>gsh</command> will
terminate all the jobs in the job list and exit.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
CTRL-R
</term>
<listitem>
<para>
redraw
</para>
<para>
Moves to the next line and re-displays
the current command-line. Use this to redraw the current line
if the screen becomes garbled.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
CTRL-L
</term>
<listitem>
<para>
clear-screen
</para>
<para>
Clears the screen, moves the cursor to
the top line, and redraws the prompt and any command-line
that was in the process of being edited.
</para>
</listitem>
</varlistentry>

</variablelist>

</section>

<section>
<title>Command Editing</title>

<para> 
These command-line editor keys
allow editing of the command-line text.
</para>
<variablelist>

<varlistentry>
<term>
CTRL-B
</term>
<term>
LEFT-ARROW
</term>
<listitem>
<para>
backward-char
</para>
<para>
Moves the cursor one character to the left. You
cannot move past the first character on the line. If so, <command>gsh</command>
will output an error beep.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
CTRL-F
</term>
<term>
RIGHT-ARROW
</term>
<listitem>
<para>
forward-char
</para>
<para>
Moves the cursor one character to the right. You
cannot move past the last character on the line. If so, <command>gsh</command>
will output an error beep.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
DELETE
</term>
<listitem>
<para>
backward-delete-char
</para>
<para>
Deletes the character to the left of the
cursor. You can delete up to the first character on the
command-line.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
CLEAR
</term>
<term>
CTRL-X
</term>
<listitem>
<para>
kill-whole-line
</para>
<para>
Deletes all characters on the command line and positions the
cursor after the prompt.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
CTRL-Y
</term>
<listitem>
<para>
kill-end-of-line
</para>
<para>
Deletes all characters from the cursor to
the end of the command-line.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
CTRL-D
</term>
<term>
OA-D
</term>
<listitem>
<para>
delete-char
</para>
<para>
Deletes the character under the cursor.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
CTRL-A
</term>
<term>
OA-&lt;
</term>
<listitem>
<para>
beginning-of-line
</para>
<para>
Moves the cursor to the beginning of the line.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
CTRL-E
</term>
<term>
OA-&gt;
</term>
<listitem>
<para>
end-of-line
</para>
<para>
Moves the cursor to the first position past the last character on
the line.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
OA-RIGHT-ARROW
</term>
<listitem>
<para>
forward-word
</para>
<para>
Moves the cursor right to the last
character of the current word.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
OA-LEFT-ARROW
</term>
<listitem>
<para>
backward-word
</para>
<para>
Moves the cursor left to the beginning of
the current word.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
OA-E
</term>
<listitem>
<para>
toggle-cursor
</para>
<para>
Toggles input mode between insert and
overstrike. Overstrike mode is distinguished by a solid inverse
cursor and insert mode by a blinking '_' (underscore) cursor. In
overstrike mode, any characters that are typed directly
over-write those characters below the cursor. In insert mode, the
characters typed are inserted before the character below the
cursor.
</para>
</listitem>
</varlistentry>

</variablelist>

</section>

<section id="gsh-interact-hist">
<title>History Editing</title>

<para>
These command-line editor keys allow access
to previously entered commands. The GNO shell automatically keeps
track of previous commands in what is called a history buffer.
</para>

<para>
The maximum number of command-lines saved
in the history buffer is determined by the shell variable . A
default value for this variable is set in the <filename>gshrc</filename> file
that the GNO Installer creates. The lines saved to the history
buffer are kept between sessions. That is, when you exit 
<command>gsh</command>, $SAVEHIST command-lines are saved to your
<filename>$HOME/history</filename> file.
When <command>gsh</command> is invoked again, all
command-lines saved in the history buffer will be available using
history editing keys. See <xref linkend="gsh-shellvars-predef"/>
for more information on the HISTORY and SAVEHIST shell variables.
</para>

<variablelist>

<varlistentry>
<term>
CTRL-P
</term>
<term>
UP-ARROW
</term>
<listitem>
<para>
up-history
</para>
<para>
Fetches the previous command-line. If the current
command-line is the first line in the history buffer, the
next line fetched will be an empty command-line. If
invoked again, the last line in the history buffer will
be displayed.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
CTRL-N
</term>
<term>
DOWN-ARROW
</term>
<listitem>
<para>
down-history
</para>
<para>
Fetches the next command-line. If the
current command-line is the last command line in the
 history buffer, the next line fetched will be the first
command-line in the history buffer.
</para>
</listitem>
</varlistentry>

</variablelist>

</section>

<section>
<title>Command, Filename, and Variable Completion</title>

<para>
These command-line editor keys can
be used to complete filenames, commands and variables.
</para>

<variablelist>

<varlistentry>
<term>
CTRL-D
</term>
<listitem>
<para>
list-choices
</para>
<para>
Lists commands and pathnames that match the current word.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
TAB
</term>
<listitem>
<para>
complete-word
</para>
<para>
Command, pathname and variable
completion. If the cursor is positioned on the first word
of the command-line, command pathname is performed, else
pathname or variable completion is performed. The word is
expanded to the closest matching command, pathname or
variable. Characters are appended up to the point that
they would cause more than one. If a complete pathname
results for pathname completion, <command>gsh</command> appends a "/"
if the pathname is a directory; otherwise, it appends a space.
</para>

<para>
Note that if there is more than one
match for the partial command, <command>gsh</command> will sound a
beep on the speaker. You can use the CTRL-D (list-choices)
command to see the list of possible
matches, and should either finish entering the command
manually or type enough additional characters to
guarantee a unique match.
</para>

<para>
If the FIGNORE environment variable
is set, <command>gsh</command> ignores filenames (when doing
completion) that end with any of the suffixes in $FIGNORE.
See <xref linkend="gsh-shellvars-predef"/>
for more information regarding the FIGNORE environment variable.
</para>

</listitem>
</varlistentry>

</variablelist>

</section>

<section>
<title>Other Ways of Entering Commands</title>

<section>
<title>Terminal Input</title>

<para>
An example involving the connection of a
terminal will be shown in 
<xref linkend="gsh-productive-redirect"/>
but it is necessary to mention here that when
using <command>gsh</command> over a terminal, some keystrokes must be
slightly modified. This is because there are no terminals that
can transmit the OA key. Instead, a two-key sequence must be used
which replaces OA with ESC. For example, instead of pressing OA-E
to toggle insert mode, you can type ESC-E over a terminal to do
the same thing.
</para>

<para>
If you will be using terminals seriously
then you should install the Remote Access package.
</para>
</section>

<section>
<title>Script File</title>

<para>
While you would normally type commands on
the command-line, you can also store a series of often used
commands in a file. A file containing such a series of commands
is called a script. A script is normally created by using a text
editor.
</para>

<para>
By typing the name of the script file, the
shell will execute it, line by line, as if you had typed each
command separately. The <filename>gshrc</filename> file presented in
<xref linkend="gsh-start-custom"/>
is an example of a script file.
</para>
</section>

</section>

</chapter>