mirror of https://github.com/GnoConsortium/gno.git
converted gsh manual to docbook
This commit is contained in:
gdr
parent
61afe2ce33
commit
c0e86cdeba
|
|
@ -0,0 +1,37 @@
|
|||
#
|
||||
# $Id: GNUmakefile,v 1.1 2012/08/25 07:19:00 gdr Exp $
|
||||
#
|
||||
|
||||
|
||||
SRCROOT = ../../..
|
||||
WEB_HOME_BASE = refs/gsh
|
||||
SUBPROJECTS =
|
||||
|
||||
include $(SRCROOT)/doc/etc/constpriv.mk
|
||||
include $(SRCROOT)/doc/etc/const.mk
|
||||
|
||||
WEB_HOME = $(DOCROOT_INSECURE)/$(WEB_HOME_BASE)
|
||||
HTML_DIR = $(WEB_HOME)/html
|
||||
TARGET_DIR = $(GNO_PUBLIC_HTML)/$(WEB_HOME_BASE)
|
||||
HEAD_PAGE =
|
||||
TAIL_PAGE =
|
||||
TARGETS = buildDocbookHtml buildDocbookPdf
|
||||
DOCBOOK_TOP = gsh.docbook
|
||||
|
||||
default: build
|
||||
|
||||
clean::
|
||||
/bin/rm -rf $(HTML_DIR)
|
||||
|
||||
include $(SRCROOT)/doc/etc/rules.mk
|
||||
include $(SRCROOT)/doc/etc/tailcat.mk
|
||||
|
||||
install:
|
||||
@/bin/rm -rf $(TARGET_DIR)
|
||||
install -d -m755 $(TARGET_DIR)
|
||||
@echo "copying files to $(TARGET_DIR)"; \
|
||||
cd $(WEB_HOME); tar -cf - . | \
|
||||
(cd $(TARGET_DIR); tar -xpBf -);
|
||||
@echo "setting permissions on $(TARGET_DIR)"; \
|
||||
find $(TARGET_DIR) -type d \! -perm 0755 -exec chmod 0755 {} \; ; \
|
||||
find $(TARGET_DIR) -type f \! -perm 0644 -exec chmod 644 {} \;
|
||||
|
|
@ -25,10 +25,19 @@ gsh.ltr.ps: gsh.sgml $(CHAPTERS)
|
|||
sgmltools -b ps gsh.sgml
|
||||
mv gsh.ps gsh.ltr.ps
|
||||
|
||||
bork:
|
||||
true; echo "result is $$?"; exit 0
|
||||
|
||||
# echo "$(SHELLMETAS)"
|
||||
|
||||
gsh.sgml: main.sgml $(CHAPTERS)
|
||||
@date="`../getdate -date main.sgml $(CHAPTERS)`"; \
|
||||
mydate=`../getdate -date main.sgml $(CHAPTERS)`; \
|
||||
echo "generating $@"; \
|
||||
perl -pe "s,%%%date%%%,$$date,g;" < main.sgml > $@
|
||||
true perl -pe "s,%%%date%%%,$$mydate,g;"
|
||||
|
||||
# < main.sgml
|
||||
|
||||
# > $@
|
||||
|
||||
clean:
|
||||
rm -f gsh.sgml *~
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,60 @@
|
|||
<!--
|
||||
$Id: comply.docbook,v 1.1 2012/08/25 07:19:01 gdr Exp $
|
||||
-->
|
||||
|
||||
<appendix id="gsh-app-comply">
|
||||
<title>Non-Compliant Applications</title>
|
||||
|
||||
<para>
|
||||
GNO/ME wasn't really designed with the
|
||||
intention of making
|
||||
<emphasis>every</emphasis>
|
||||
program you currently run work under
|
||||
GNO/ME; that task would have been impossible. Our main goal was
|
||||
to provide a UNIX-based multitasking environment; that we have
|
||||
done. We made sure as many existing applications as we had time
|
||||
to track and debug worked with GNO/ME.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
However, due to the sheer number of
|
||||
applications and authors, there are some programs that just plain
|
||||
don't work; and some that mostly work, except for annoyances such
|
||||
as two cursors appearing, or keyboard characters getting "lost".
|
||||
The problem here is that some programs use their own text drivers
|
||||
(since TextTools output was very slow at one time); since GNO/ME
|
||||
doesn't know about these custom drivers, it goes on buffering
|
||||
keyboard characters and displaying the cursor. There is a way,
|
||||
however, to tell GNO/ME about these programs that break GNO/ME's
|
||||
rules.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
We've defined an auxType for S16 and EXE
|
||||
files, to allow distinction between programs that are GNO/ME
|
||||
compliant and those that are not. Setting the auxType of an
|
||||
application to $DC00 disables the interrupt driven keyboard
|
||||
buffering and turns off the GNO/ME cursor. Desktop programs use
|
||||
the GNO/ME keyboard I/O via the Event Manager, and thus should
|
||||
<emphasis>not</emphasis>
|
||||
have their auxType changed.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You can change a program's auxType with the
|
||||
following shell command:
|
||||
<screen>
|
||||
<command>chtyp -a \$DC00</command> <filename>filename</filename>
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
where <filename>filename</filename> is the name of the
|
||||
application. As more programmers become aware of GNO/ME and work
|
||||
to make their software compatible with it, this will become less
|
||||
of a problem, but for older applications that are unlikely to
|
||||
ever change $DC00 is a
|
||||
reasonable approach.
|
||||
</para>
|
||||
|
||||
</appendix>
|
||||
|
|
@ -0,0 +1,401 @@
|
|||
<!--
|
||||
;; $Id: errors.docbook,v 1.1 2012/08/25 07:19:01 gdr Exp $
|
||||
-->
|
||||
|
||||
<appendix id="gsh-app-errors">
|
||||
<title>Gsh Errors</title>
|
||||
|
||||
<para>
|
||||
<command>gsh</command> tries, when an error occurs, to
|
||||
output an informative error message that will lead you to the
|
||||
solution of your problem. This appendix documents all <command>gsh</command>
|
||||
error messages and what the probable cause of the problem might
|
||||
be. There are five classes of errors: generic gsh, command-entry,
|
||||
syntax, execution, and builtin. Each error is discussed
|
||||
separately.
|
||||
</para>
|
||||
|
||||
<sect1>
|
||||
<title>Generic gsh Errors</title>
|
||||
|
||||
<para>
|
||||
These errors can typically occur at any
|
||||
time and may not be directly related to something the user has
|
||||
done. Some of them are trivial, and some are very serious and
|
||||
should be reported immediately via the
|
||||
<ulink url="http://www.gno.org/~gno/bugs.html">GNOBugs</ulink>
|
||||
web page.
|
||||
</para>
|
||||
|
||||
<variablelist>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
gsh: There are stopped jobs.
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
All stopped jobs must be killed before exiting the
|
||||
shell. Use the <command>jobs</command> and <command>kill</command> commands.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1>
|
||||
<title>Command Editing Errors</title>
|
||||
|
||||
<para>
|
||||
Command editing errors occur when entering
|
||||
information on the command-line. If you try to move the cursor
|
||||
too far to the left or right of your command-line (i.e. before
|
||||
the first character or after the last character), an error will
|
||||
occur. At present, gsh indicates a command-entry error by generating
|
||||
the bell character (^G), which beeps the speaker.
|
||||
This is to notify you that the action you requested is not possible.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1>
|
||||
<title>Syntax Errors</title>
|
||||
|
||||
<para>
|
||||
Syntax errors occur while gsh is trying to
|
||||
understand the command you have entered on the command-line.
|
||||
Problems arise when you wish to quote an argument (") and
|
||||
only enter one quote.
|
||||
</para>
|
||||
|
||||
<variablelist>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
gsh: Missing ending ".
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A second " wasn't supplied when quoting text.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
gsh: Missing ending '.
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A second ' wasn't supplied when quoting text.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
gsh: Too many arguments, so no dessert tonight.
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The command-line contained too many arguments which exceeded the available
|
||||
memory allocated by <command>gsh</command>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
gsh: Not enough memory for arguments.
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
No memory was available for allocating command-line arguments.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
gsh: Extra '<' encountered.
|
||||
</term>
|
||||
<term>
|
||||
gsh: Extra '>' or '>>' encountered.
|
||||
</term>
|
||||
<term>
|
||||
gsh: Extra '>&' or '>>&' encountered
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Text may be redirected to only one file.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
gsh: No file specified for '<'.
|
||||
</term>
|
||||
<term>
|
||||
gsh: No file specified for '>' or '>>'.
|
||||
</term>
|
||||
<term>
|
||||
gsh: No file specified for '>&' or '>>&'.
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A file must be specified when redirecting I/O.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
gsh: '|' conflicts with '>' or '>>'.
|
||||
</term>
|
||||
<term>
|
||||
gsh: '|' conflicts with '<'.
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Piping is another form of redirection, thus
|
||||
pipes and redirections cannot be mixed.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
</sect1>
|
||||
|
||||
<sect1>
|
||||
<title>Execution Errors</title>
|
||||
|
||||
<para>
|
||||
After <command>gsh</command> parses the command-line,
|
||||
it will then execute the command and pass any arguments to the
|
||||
command. If, however, the command does not exist, <command>gsh</command> will
|
||||
report an error. The reason the command does not exist could be
|
||||
either the command name was typed wrong or the command does not
|
||||
exist.
|
||||
</para>
|
||||
|
||||
<variablelist>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
$0: Command not found.
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
$0 represents the command to be executed.
|
||||
Either the command name was entered incorrectly or the command
|
||||
does not exist. Recheck the spelling of the command and check
|
||||
$PATH to make sure the command exists in the pathname list.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
$0: Not executable.
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
$0 represents the command to be executed. Check to ensure that the
|
||||
filetype is correct.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
heh heh, next time you'll need to specify a command before redirecting.
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Redirection was specified but the command-line had no command.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
Cannot fork (too many processes?)
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
An error was encountered forking a process.
|
||||
The most likely culprit is there are too many processes running.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1>
|
||||
<title>Builtin Command Errors</title>
|
||||
|
||||
<para>
|
||||
These are errors which can be returned by
|
||||
many of the builtin commands. Every builtin also contains a
|
||||
usage message on the proper invocation method.
|
||||
</para>
|
||||
|
||||
<variablelist>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
cd: Not a directory
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Tried to change the cwd to a file that isn't a directory.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
prefix: could not set prefix, pathname may not exist.
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
GS/OS Prefix command failed, most likely
|
||||
the pathname did not exist or the disk is damaged.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
setdebug: Unknown flag
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
An unknown flag was sent to
|
||||
<command>setdebug</command>. Run
|
||||
<command>setdebug</command> with
|
||||
no arguments for a list of possible flags.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
ps: error in kvm_open()
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
<command>ps</command> was unable to access the process data
|
||||
structure. If the kernel data structures are damaged to the point that
|
||||
this error occurs, it is likely that you will not be able to see this
|
||||
error.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
set: Variable not specified
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A variable was not passed to set, for example,
|
||||
"<command>set =bar</command>".
|
||||
Make sure the variable name was specified
|
||||
without the preceding dollar sign. For example, if foo is not
|
||||
set, then
|
||||
"<command>set $foo=bar</command>"
|
||||
would be expanded to
|
||||
"<command>set =bar</command>",
|
||||
resulting in this error.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
kill: Invalid signal number
|
||||
</term>
|
||||
<term>
|
||||
kill: Invalid signal name
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
See the signal(2) manual page for a list of valid signal names and numbers.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
fg: No job to foreground.
|
||||
</term>
|
||||
<term>
|
||||
bg: No job to background.
|
||||
</term>
|
||||
<term>
|
||||
stop: No job to stop.
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
There aren't currently any jobs so the attempted command is useless.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
fg: No such job.
|
||||
</term>
|
||||
<term>
|
||||
bg: No such job.
|
||||
</term>
|
||||
<term>
|
||||
stop: No such job.
|
||||
</term>
|
||||
<term>
|
||||
kill: No such job.
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The specified job (or process) doesn't exist.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
fg: Gee, this job is already in the foreground.
|
||||
</term>
|
||||
<term>
|
||||
bg: Gee, this job is already in the background.
|
||||
</term>
|
||||
<term>
|
||||
stop: Gee, this job is already stopped.
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Well, this should be self-explanatory.
|
||||
Also, some of these should be impossible to get, unless you're
|
||||
bound and determined to crash gsh, but then, these errors will
|
||||
keep you from crashing it, so, what's the point?
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
</sect1>
|
||||
</appendix>
|
||||
|
|
@ -0,0 +1,472 @@
|
|||
<!--
|
||||
;; $Id: glossary.docbook,v 1.1 2012/08/25 07:19:02 gdr Exp $
|
||||
-->
|
||||
|
||||
<glossary id="gsh-glossary">
|
||||
<title>Glossary</title>
|
||||
|
||||
<!--
|
||||
;;
|
||||
;; Make sure you keep all these entries properly sorted. They will
|
||||
;; appear exactly in the order in which you see them here; no automated
|
||||
;; sorting is done.
|
||||
;;
|
||||
;; Here is a glossary entry template for you to cut and paste:
|
||||
;;
|
||||
<glossentry>
|
||||
<glossterm></glossterm>
|
||||
<glossdef>
|
||||
<para>
|
||||
</para>
|
||||
</glossdef>
|
||||
</glossentry>
|
||||
;;
|
||||
;;
|
||||
-->
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Alias</glossterm>
|
||||
<glossdef><para>
|
||||
A name used as an
|
||||
abbreviation for one or more commands. An alias allows
|
||||
you to replace any command string with a short sequence
|
||||
of characters.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Applesoft</glossterm>
|
||||
<glossdef><para>
|
||||
An implementation of BASIC for the Apple II.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>APW</glossterm>
|
||||
<glossdef><para>
|
||||
Apple Programmer's Workshop. Similar to ORCA.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>BASIC</glossterm>
|
||||
<glossdef><para>
|
||||
Beginners All-purpose Symbolic Instruction Code. A simple computer
|
||||
language.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Built-in Command</glossterm>
|
||||
<glossdef><para>
|
||||
A command processed by <command>gsh</command>. These commands are not
|
||||
external to the shell, but are included within the
|
||||
<command>gsh</command> program.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Command</glossterm>
|
||||
<glossdef><para>
|
||||
An action for <command>gsh</command> to perform. Commands can be
|
||||
either simple or compound. A simple command is an alias assignment,
|
||||
variable assignment, I/O redirection, or built-in
|
||||
command. A compound command is a pipeline.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Directory</glossterm>
|
||||
<glossdef><para>
|
||||
A special
|
||||
type of file that contains a list of other files; usually
|
||||
used to categorize files related in some way.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Environment</glossterm>
|
||||
<glossdef><para>
|
||||
The state of a process, which includes information such as
|
||||
its open files, current directory (working directory),
|
||||
and local and global variables. Three environments exist
|
||||
under <command>gsh</command>:
|
||||
<variablelist>
|
||||
|
||||
<varlistentry>
|
||||
<term>Child Environment</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The environment of the child process.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>Current Environment</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The environment of the current process.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>Parent Environment</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The environment of the parent process.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Environment file</glossterm>
|
||||
<glossdef><para>
|
||||
A file that is interpreted by an application to allow the
|
||||
user to customize its operation. For <command>gsh</command>, this
|
||||
file is <filename>gshrc</filename>.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Export</glossterm>
|
||||
<glossdef><para>
|
||||
A way to pass a variable from a parent process to child process.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>File</glossterm>
|
||||
<glossdef><para>
|
||||
An object used
|
||||
to store data and/or programs. On the IIgs, files
|
||||
are tagged with types such as EXE, SRC, TXT, and so forth.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Filter</glossterm>
|
||||
<glossdef><para>
|
||||
A command
|
||||
that reads from its standard input and writes to its
|
||||
standard output. For example, a filter program could be
|
||||
written to convert all characters to upper case. Filters
|
||||
are used mainly in pipelines.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Flag</glossterm>
|
||||
<glossdef><para>
|
||||
A character
|
||||
used to represent an option to a command. Flags are
|
||||
either short or long options whose character
|
||||
representations are "-" and "+".
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Glob</glossterm>
|
||||
<glossdef><para>
|
||||
Slang for Pathname Expansion.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>GNO/ME</glossterm>
|
||||
<glossdef><para>
|
||||
GNO Multitasking Environment. The complete package including
|
||||
the GNO kernel and the GNO Shell.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>GNO Kernel</glossterm>
|
||||
<glossdef><para>
|
||||
Heart of GNO/ME. Executes processes when asked by the GNO Shell.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>GNO Shell</glossterm>
|
||||
<glossdef><para>
|
||||
Provides
|
||||
an interface between the user and the GNO kernel.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>gsh</glossterm>
|
||||
<glossdef><para>
|
||||
GNO Implementation of a UNIX-like shell.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>GS/OS</glossterm>
|
||||
<glossdef><para>
|
||||
16 bit
|
||||
Operating System for the Apple IIgs.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>History</glossterm>
|
||||
<glossdef><para>
|
||||
A variable
|
||||
number of command-lines saved by <command>gsh</command> for future
|
||||
reference. The number of command-lines saved is dependent
|
||||
on the HISTORY environment variable.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>History file</glossterm>
|
||||
<glossdef><para>
|
||||
A file
|
||||
containing command-lines entered while in a <command>gsh</command>
|
||||
session. The number of command-lines saved is dependent
|
||||
on the SAVEHIST environment variable.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Interrupt</glossterm>
|
||||
<glossdef><para>
|
||||
A signal
|
||||
generated by a sequence of keyboard characters or by a
|
||||
command that terminates the current executing process,
|
||||
unless the process has set up a trap to handle the
|
||||
interrupt signal.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>I/O Redirection</glossterm>
|
||||
<glossdef><para>
|
||||
The
|
||||
process of changing the standard input, standard output,
|
||||
and standard error associated with a process so that it
|
||||
is redirected to a file instead of the console.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Job</glossterm>
|
||||
<glossdef><para>
|
||||
A set of related
|
||||
processes. A job can be either:
|
||||
|
||||
<variablelist>
|
||||
|
||||
<varlistentry>
|
||||
<term>Background Job</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A process
|
||||
that executes with the current process. Background jobs
|
||||
are not associated with the terminal.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>Foreground Job</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A process
|
||||
that is currently executing and which is associated with
|
||||
the terminal.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Multiprocessing</glossterm>
|
||||
<glossdef><para>
|
||||
Indicates a machine with more than one CPU.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Multitasking</glossterm>
|
||||
<glossdef><para>
|
||||
The ability to run more than one program at a time, or the
|
||||
illusion of more than one program running at a time;
|
||||
usually the latter.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>ORCA</glossterm>
|
||||
<glossdef><para>
|
||||
Shell programing
|
||||
environment for the Apple //gs. Also a type of whale.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Path Search</glossterm>
|
||||
<glossdef><para>
|
||||
The means of searching a pathname list for a command or
|
||||
script.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Pathname</glossterm>
|
||||
<glossdef><para>
|
||||
A string used to identify a file.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Pathname Completion</glossterm>
|
||||
<glossdef><para>
|
||||
The means of generating all pathnames matching a given pattern.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Pathname Expansion</glossterm>
|
||||
<glossdef><para>
|
||||
The means of replacing a pattern with a list of pathnames
|
||||
matching that pattern.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Pattern</glossterm>
|
||||
<glossdef><para>
|
||||
A string of
|
||||
characters used to match literal characters and/or
|
||||
multiple characters.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Permission</glossterm>
|
||||
<glossdef><para>
|
||||
Each file
|
||||
has certain permissions associated with it: destroy,
|
||||
rename, backup, invisible, write, and read.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Pipe</glossterm>
|
||||
<glossdef><para>
|
||||
A conduit
|
||||
through which a stream of characters can pass from one
|
||||
process to another. This is accomplished by linking the
|
||||
standard output of one process to the standard input of a
|
||||
second process.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Pipeline</glossterm>
|
||||
<glossdef><para>
|
||||
Two or more
|
||||
processes connected together by pipes.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Process</glossterm>
|
||||
<glossdef><para>
|
||||
A single
|
||||
thread of execution that consists of a program and an
|
||||
execution environment. If a process creates another process,
|
||||
the creator is known as the <emphasis>parent process</emphasis>;
|
||||
the created process is known as the <emphasis>child process</emphasis>.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Process ID</glossterm>
|
||||
<glossdef><para>
|
||||
Each active process is uniquely identified by a positive
|
||||
integer called the process id.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>ProDOS</glossterm>
|
||||
<glossdef><para>
|
||||
8-bit Disk
|
||||
Operating System for Apple II computers.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Prompt</glossterm>
|
||||
<glossdef><para>
|
||||
A message
|
||||
displayed by <command>gsh</command> when it is ready to receive a
|
||||
command.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Quoting</glossterm>
|
||||
<glossdef><para>
|
||||
A means of
|
||||
including special characters as arguments to a command or
|
||||
as the command name. Certain characters have certain
|
||||
meanings to <command>gsh</command> and quoting them makes
|
||||
<command>gsh</command> ignore them.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Reserved Word</glossterm>
|
||||
<glossdef><para>
|
||||
A word
|
||||
that is treated specially by <command>gsh</command>. This word is
|
||||
part of the <command>gsh</command> grammar.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Script</glossterm>
|
||||
<glossdef><para>
|
||||
A sequence of
|
||||
commands contained in a file.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Signal</glossterm>
|
||||
<glossdef><para>
|
||||
An asynchronous message that consists of a number or name
|
||||
that can be sent from one process to another.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Standard Error</glossterm>
|
||||
<glossdef><para>
|
||||
The file associated with error messages for a process. This
|
||||
file is usually the terminal.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Standard Input</glossterm>
|
||||
<glossdef><para>
|
||||
The file associated with a processes input. This file is
|
||||
usually the terminal.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Standard Output</glossterm>
|
||||
<glossdef><para>
|
||||
The file associated with a processes output. This file is
|
||||
usually the terminal.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Tilde Expansion</glossterm>
|
||||
<glossdef><para>
|
||||
Words beginning with "~" are treated
|
||||
specially by <command>gsh</command>. The "~" is
|
||||
expanded to the value of the HOME environment variable.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>UNIX</glossterm>
|
||||
<glossdef><para>
|
||||
Popular
|
||||
operating system which has growing use in education and
|
||||
business. One of the first operating systems to support
|
||||
multitasking.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Variable</glossterm>
|
||||
<glossdef><para>
|
||||
A named
|
||||
location in <command>gsh</command> that contains text. The text of a
|
||||
variable can be expanded in a command by preceding the
|
||||
variable name with a dollar sign ($).
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Wildcard</glossterm>
|
||||
<glossdef><para>
|
||||
See Pattern and Pathname Expansion.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>Working directory</glossterm>
|
||||
<glossdef><para>
|
||||
The current directory.
|
||||
</para></glossdef></glossentry>
|
||||
|
||||
</glossary>
|
||||
|
|
@ -0,0 +1,94 @@
|
|||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
|
||||
"/usr/share/sgml/docbook/xml-dtd-4.3-1.0-30.1/docbookx.dtd"
|
||||
[
|
||||
<!ENTITY gshStart SYSTEM "start.docbook">
|
||||
<!ENTITY gshInteract SYSTEM "interact.docbook">
|
||||
<!ENTITY gshProduct SYSTEM "product.docbook">
|
||||
<!ENTITY gshCommands SYSTEM "commands.docbook">
|
||||
<!ENTITY gshVars SYSTEM "vars.docbook">
|
||||
<!ENTITY gshPrefix SYSTEM "prefix.docbook">
|
||||
<!ENTITY gshErrors SYSTEM "errors.docbook">
|
||||
<!ENTITY gshComply SYSTEM "comply.docbook">
|
||||
<!ENTITY gshTermcap SYSTEM "termcap.docbook">
|
||||
<!ENTITY gshGlossary SYSTEM "glossary.docbook">
|
||||
]>
|
||||
|
||||
<!--
|
||||
In the above DTD block the canonical location for the DTD
|
||||
would be:
|
||||
|
||||
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
|
||||
|
||||
But instead on the official build machine we use the following
|
||||
local DTD because it makes the build MUCH faster:
|
||||
|
||||
"/usr/share/sgml/docbook/xml-dtd-4.3-1.0-30.1/docbookx.dtd"
|
||||
-->
|
||||
|
||||
<!--
|
||||
-->
|
||||
|
||||
|
||||
<book>
|
||||
|
||||
<bookinfo>
|
||||
<title>GNO Shell Users' Manual</title>
|
||||
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Tim</firstname>
|
||||
<surname>Meekins</surname>
|
||||
</author>
|
||||
|
||||
<author>
|
||||
<firstname>Albert</firstname>
|
||||
<surname>Chin</surname>
|
||||
</author>
|
||||
|
||||
<author>
|
||||
<firstname>Jawaid</firstname>
|
||||
<surname>Bazyar</surname>
|
||||
</author>
|
||||
|
||||
|
||||
<author>
|
||||
<firstname>Andrew</firstname>
|
||||
<surname>Roughan</surname>
|
||||
</author>
|
||||
|
||||
|
||||
<author>
|
||||
<firstname>Devin</firstname>
|
||||
<surname>Reade</surname>
|
||||
</author>
|
||||
</authorgroup>
|
||||
|
||||
<copyright>
|
||||
<year>1991-2012</year>
|
||||
<holder>Procyon Enterprises</holder>
|
||||
</copyright>
|
||||
|
||||
<pubdate>25 Aug 2012</pubdate>
|
||||
|
||||
</bookinfo>
|
||||
|
||||
<toc/>
|
||||
|
||||
<!--
|
||||
Now list the chapters in the order in which you want them to appear.
|
||||
-->
|
||||
|
||||
|
||||
&gshStart;
|
||||
&gshInteract;
|
||||
&gshProduct;
|
||||
&gshCommands;
|
||||
&gshVars;
|
||||
&gshPrefix;
|
||||
&gshErrors;
|
||||
&gshComply;
|
||||
&gshTermcap;
|
||||
&gshGlossary;
|
||||
|
||||
</book>
|
||||
|
|
@ -0,0 +1,557 @@
|
|||
<!--
|
||||
;; $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-<
|
||||
</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->
|
||||
</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>
|
||||
|
|
@ -0,0 +1,132 @@
|
|||
<!--
|
||||
;; $Id: prefix.docbook,v 1.1 2012/08/25 07:19:02 gdr Exp $
|
||||
-->
|
||||
|
||||
<appendix id="gsh-app-prefix">
|
||||
<title>Prefix Conventions</title>
|
||||
|
||||
<para>
|
||||
When <command>gsh</command> is started, GS/OS assigns
|
||||
certain values to individual prefixes, and usually the
|
||||
<filename>gshrc</filename>
|
||||
file also sets some prefixes. A total of 32 prefixes are
|
||||
available to the user. The following list documents each prefix
|
||||
and the purpose of each.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If version 2.x of the ORCA languages are being used, then prefixes 9 and 13
|
||||
through 18 should mirror prefixes 1 through 7. For a discussion on
|
||||
the differences in these two prefix sets, see your ORCA language reference
|
||||
manual.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<table colsep="1" frame="all" rowsep="1" tocentry="1" shortentry="0"
|
||||
orient="land" pgwide="0">
|
||||
<title>GS/OS Prefix Conventions</title>
|
||||
<tgroup cols="2">
|
||||
<!-- tribby: This table would, of course, look better if the prefix numbers
|
||||
were given a narrow column and the prefix descriptions a wide column.
|
||||
However, experimenting with the documented parameters does not seem to
|
||||
give good results. This should be revisited at a later time (ie: once
|
||||
I get around to asking some questions on the sgmltools mailing list) -->
|
||||
<colspec colnum="1" align="center"/>
|
||||
<colspec colnum="2" align="left"/>
|
||||
<thead>
|
||||
<row>
|
||||
<entry align="center">Number</entry>
|
||||
<entry align="center">Description</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>@</entry>
|
||||
<entry>
|
||||
AppleShare prefix. If GNO resides on an
|
||||
AppleShare volume, this prefix is set to the pathname of
|
||||
the user's directory on the file server; otherwise, this
|
||||
prefix is set to the same pathname as prefix number 9.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>*</entry>
|
||||
<entry>
|
||||
Boot volume prefix. It is not
|
||||
possible to modify the value of this prefix with the
|
||||
shell's <command>prefix</command> command. The only other way to
|
||||
access this prefix is the GS/OS <function>_GetBootVol</function> call.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>0</entry>
|
||||
<entry>
|
||||
Prefix 0 is the current working
|
||||
directory. It is the prefix that is changed by the <command>cd</command>
|
||||
command.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>1, 9</entry>
|
||||
<entry>
|
||||
This is the directory in which the currently executing program resides.
|
||||
In the shell, this is usually <filename>/bin</filename>.
|
||||
The kernel sets these prefixes appropriately for each
|
||||
program that is executed.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>2, 13</entry>
|
||||
<entry>
|
||||
These prefixes should be set to the pathname of the ORCA libraries
|
||||
directory.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>3, 14</entry>
|
||||
<entry>
|
||||
These prefixes should be set to the same directory as contains
|
||||
the ORCA/Shell program, <filename>ORCA.SYS16</filename>.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>4, 15</entry>
|
||||
<entry>
|
||||
These prefixes should be set to the pathname of the ORCA "shell"
|
||||
directory. This is the directory that contains the files,
|
||||
<filename>Editor</filename>,
|
||||
<filename>SysTabs</filename>,
|
||||
<filename>SysCmnd</filename>,
|
||||
and so forth.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>5, 16</entry>
|
||||
<entry>
|
||||
These prefixes should be set to the pathname of the ORCA languages
|
||||
directory.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>6, 17</entry>
|
||||
<entry>
|
||||
These prefixes should be set to the pathname of the ORCA utilities
|
||||
directory.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>7, 18</entry>
|
||||
<entry>
|
||||
This should be set to a temp directory; one that can be used by various
|
||||
programs for scratch files. Using a RAMDisk for this purpose can speed
|
||||
up many programs. See also the <command>renram5</command>(8) and
|
||||
<command>mktmp</command>(8) commands.
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
</para>
|
||||
|
||||
|
||||
</appendix>
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,215 @@
|
|||
<!--
|
||||
;; $Id: start.docbook,v 1.1 2012/08/25 07:19:03 gdr Exp $
|
||||
-->
|
||||
|
||||
<chapter id="gsh-start">
|
||||
<title>Getting Started with the GNO Shell</title>
|
||||
|
||||
<para><quote><emphasis>
|
||||
Computer operating systems are among the most complex objects created by
|
||||
mankind...
|
||||
</emphasis>
|
||||
</quote>
|
||||
-- Douglas Comer, Operating System Design, the XINU Approach
|
||||
</para>
|
||||
|
||||
<section>
|
||||
<title>Introduction</title>
|
||||
|
||||
<para>
|
||||
The GNO shell is an integral part of the
|
||||
GNO Multitasking Environment (GNO/ME). The GNO shell provides the
|
||||
interface between the user and the GNO Kernel. While both work
|
||||
together, the jobs they perform are quite different. This manual
|
||||
documents the functions of the shell.
|
||||
</para>
|
||||
|
||||
<para>The user interacts with the shell through a
|
||||
command-line interface. Command-line interfaces provide a unique
|
||||
way of interacting with the operating system. Unlike GUIs
|
||||
(Graphical User Interfaces), with which you are already familiar
|
||||
with by using programs such as the Finder and ShrinkIt! GS, all
|
||||
commands are typically entered using the keyboard. The shell
|
||||
interprets commands and passes them to the kernel for control and
|
||||
execution.</para>
|
||||
|
||||
<para>The command-line interface will be
|
||||
unfamiliar to some people However, once the command-line
|
||||
interface has been mastered, the user should have no difficulty
|
||||
using any current or future GNO applications. Those of you
|
||||
already familiar with Unix interfaces, such as the C shell,
|
||||
Bourne shell, and Korn shell, or the ORCA shell on the Apple
|
||||
IIGS, will begin to realize the advantages which GNO/ME is able
|
||||
to provide.</para>
|
||||
|
||||
<para>The way this manual is presented allows the
|
||||
complete beginner to simply work through the chapters in a
|
||||
chronological prder.
|
||||
<xref linkend="gsh-interact"/>
|
||||
familiarises the user with
|
||||
entering basic commands whereas the more powerful GNO/ME features
|
||||
are introduced in
|
||||
<xref linkend="gsh-productive"/>.
|
||||
<xref linkend="gsh-commands"/>
|
||||
documents the commands which are built into the GNO Shell and
|
||||
<xref linkend="gsh-shellvars"/>
|
||||
explains shell
|
||||
variables which give the user control over how their installation
|
||||
functions.</para>
|
||||
|
||||
</section>
|
||||
<section id="gsh-start-custom">
|
||||
<title>Customizing the Shell Environment</title>
|
||||
|
||||
<para>When <command>gsh</command>, the implementation of the
|
||||
GNO Shell, is executed, it reads in and processes the <filename>gshrc</filename>
|
||||
file. This file contains start-up instructions for the shell,
|
||||
which can be used to customize the operation of the shell and
|
||||
other aspects of the system. It is created by the GNO Installer
|
||||
during the installation process.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The following is a sample <filename>gshrc</filename> file
|
||||
(line numbers have been added for convenience):
|
||||
</para>
|
||||
|
||||
<informalexample>
|
||||
<screen>
|
||||
1 ###
|
||||
2 #
|
||||
3 # GNO 2.0 gshrc file
|
||||
4 #
|
||||
5 ###
|
||||
6 #
|
||||
7 # Initialize our environment
|
||||
8 #
|
||||
9 set path=":hard:gno:bin :hard:gno:usr:bin"
|
||||
10 set prompt="[%h] %S%t%s %C> "
|
||||
11 set home=":hard:gno:user:root"
|
||||
12 set term=gnocon
|
||||
13 export path prompt home term
|
||||
14 setenv history=100 savehist=25
|
||||
15 ###
|
||||
16 #
|
||||
17 #Set up standard prefixes for utilities.
|
||||
18 #
|
||||
19 ###
|
||||
20 prefix 2 :software:orca:libraries
|
||||
21 prefix 3 :software:orca
|
||||
22 prefix 4 :software:orca:shell
|
||||
23 prefix 5 :software:orca:languages
|
||||
24 prefix 6 :software:orca:utilities
|
||||
25 prefix 7 :tmp
|
||||
26 ###
|
||||
27 #
|
||||
28 # Set up prefixes for Orca2.0(tm)'s benefit
|
||||
29 #
|
||||
30 ###
|
||||
31 prefix 13 :software:orca:libraries
|
||||
32 prefix 14 :software:orca
|
||||
33 prefix 15 :software:orca:shell
|
||||
34 prefix 16 :software:orca:languages
|
||||
35 prefix 17 :software:orca:utilities
|
||||
36 alias ls 'ls -CF'
|
||||
37 alias dir 'ls -al'
|
||||
38 alias cp 'cp -i'
|
||||
39 alias rm 'cp -p rm'
|
||||
40 alias mv 'cp -p mv'
|
||||
41 setenv usrman='/usr/man'
|
||||
42 set fignore='.a .root .sym'
|
||||
43 alias zcat 'compress -cd'
|
||||
44 setenv pager=less
|
||||
45 setenv less=-e
|
||||
46 set nonewline=1
|
||||
47 #
|
||||
48 # Move to home directory
|
||||
49 #
|
||||
50 cd
|
||||
</screen>
|
||||
</informalexample>
|
||||
|
||||
<para>When you install GNO/ME, the GNO installer
|
||||
knows where to find the GNO utilities and any ORCA utilities you
|
||||
may have. Unfortunately it does not know where all the other
|
||||
utilities and applications that you may wish to use are located.
|
||||
It is therefore necessary to edit the setup file in order to tell
|
||||
the GNO shell where these programs are on your hard disk.</para>
|
||||
|
||||
<para>The setup file, <filename>gshrc</filename>, is located in
|
||||
the /usr directory of the path where you installed GNO/ME. You
|
||||
can use any text editor from the desktop to edit the <filename>gshrc</filename>
|
||||
file, or if you are already familiar with the editor vi
|
||||
you can use this utility after launching the GNO kernel.</para>
|
||||
|
||||
<para>Line 9 is the statement that we are
|
||||
concerned with. <userinput>Hard</userinput> represents the name of your
|
||||
particular hard drive volume where you have installed GNO/ME.</para>
|
||||
|
||||
<screen>
|
||||
9 set path=":hard:gno:bin :hard:gno:usr:bin"
|
||||
</screen>
|
||||
|
||||
<para>You will see that spaces have been inserted
|
||||
between pathnames. The space is the pathname separator and the
|
||||
colon has been used as the path delimiter for this specific
|
||||
variable, PATH. As an exercise, add your system directory to this
|
||||
statement. Line 9 should now look like this:</para>
|
||||
|
||||
<screen>
|
||||
9 set path=":hard:gno:bin:hard:gno:usr:bin :hard:system"
|
||||
</screen>
|
||||
|
||||
<para>What you have just done allows the GNO
|
||||
shell to find the Finder application. Now go ahead and add
|
||||
any pathnames that hold utilities or applications that you will
|
||||
use frequently from GNO/ME. It should also be noted that it is
|
||||
possible to have more than one pathname containing EXE, SYS16, or
|
||||
EXEC files; this is impossible under ORCA. The PATH variable is
|
||||
discussed thoroughly in
|
||||
<xref linkend="gsh-shellvars"/>.
|
||||
</para>
|
||||
|
||||
<para>For now, the remaining lines of the <filename>gshrc</filename>
|
||||
file do not need editing. As you gain an understanding of the
|
||||
system you may wish to make further changes to the <filename>gshrc</filename>
|
||||
file. Make sure you save the file before you exit the editor.</para>
|
||||
|
||||
<para>It is possible to modify these instructions
|
||||
while the GNO shell is active, but any changes will be lost upon
|
||||
exiting <command>gsh</command>. If you wish the changes to remain effective
|
||||
for the next session you must add them to the <filename>gshrc</filename> file.</para>
|
||||
|
||||
<para>By customizing the <filename>gshrc</filename> file it is
|
||||
possible to make the GNO environment more like UNIX, the ORCA
|
||||
environment, or something completly different. Customization of
|
||||
the GNO environment leads to greater user productivity.</para>
|
||||
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Invoking gsh</title>
|
||||
|
||||
<para>GNO/ME can be launched from a program
|
||||
launcher, such as the System 6.0 Finder. Launch the GNO Kernel
|
||||
program, <command>kern</command> by double clicking on it. The GNO kernel
|
||||
automatically executes the supplied GNO shell, <command>gsh</command>.
|
||||
</para>
|
||||
|
||||
<para>The prompt,
|
||||
<quote>gsh# </quote>
|
||||
indicates that <command>gsh</command> is ready to receive input from the
|
||||
keyboard.</para>
|
||||
|
||||
<para>To start a new <command>gsh</command> from the
|
||||
command-line simply type <command>gsh</command>.
|
||||
If multiple copies of the <command>gsh</command>
|
||||
process are undesirable, use the command <command>source gsh</command>
|
||||
instead. This is useful for testing changes made to the
|
||||
<filename>gshrc</filename> file.
|
||||
<command>source</command> is a built-in comand which is discussed in
|
||||
<xref linkend="gsh-commands"/>.
|
||||
</para>
|
||||
|
||||
</section>
|
||||
</chapter>
|
||||
|
|
@ -0,0 +1,99 @@
|
|||
<!--
|
||||
;; $Id: termcap.docbook,v 1.1 2012/08/25 07:19:03 gdr Exp $
|
||||
-->
|
||||
|
||||
<appendix id="gsh-app-termcap">
|
||||
<title>Termcaps</title>
|
||||
|
||||
<para>
|
||||
"Termcap" is short for "terminal capability",
|
||||
and is the name of a database which applications can
|
||||
use to do full-screen output on any kind of terminal. The termcap
|
||||
database contains records for the various supported terminals,
|
||||
each of which contains fields of the form
|
||||
<screen>
|
||||
<replaceable>cap</replaceable>=<replaceable>value</replaceable>
|
||||
</screen>
|
||||
<replaceable>Cap</replaceable> is a two-letter code that
|
||||
represents a cursor movement, screen mode change (such as inverse
|
||||
or underline mode), and various other things.
|
||||
<replaceable>Value</replaceable> is
|
||||
usually a sequence of control characters that is sent to a
|
||||
terminal to initiate the desired action.
|
||||
<replaceable>Value</replaceable> can also be
|
||||
'boolean', or yes/no, values, for such things as "Does this
|
||||
terminal support cursor movement?". The termcap file is
|
||||
documented in termcap(5) manual page.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The termcap library does not specifically require GNO/ME.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The following terminal types are supported in the GNO/ME termcap file:
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<informaltable colsep="1" frame="all" rowsep="1" tocentry="0" shortentry="0"
|
||||
orient="land" pgwide="0">
|
||||
<tgroup cols="2">
|
||||
<colspec align="left"/>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>gnocon</entry>
|
||||
<entry>GNO Console</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>CONSOLE</entry>
|
||||
<entry>GS/OS .console driver</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>ptse</entry>
|
||||
<entry>Proterm Special Emulation</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>vt100</entry>
|
||||
<entry>DEC VT-100 terminal</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>ansisys</entry>
|
||||
<entry>MS-DOS ANSI.SYS</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>xerox820</entry>
|
||||
<entry>Xerox 820-II CP/M terminal</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>iw1</entry>
|
||||
<entry>Apple ImageWriter I printer</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>iw-alt</entry>
|
||||
<entry>Alternate ImageWriter I printer</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>deskjet</entry>
|
||||
<entry>Hewlett Packard DeskJet 500 printer</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The printer entries allow a formatted
|
||||
electronic manual page to be sent to the printer. For example,
|
||||
the following script would bring up the manual page for <command>ls</command>,
|
||||
format it for the DeskJet 500, and print it with italics and
|
||||
boldface:
|
||||
</para>
|
||||
|
||||
<screen>
|
||||
set temp=$term
|
||||
set term=deskjet
|
||||
man $1 > .ttyb
|
||||
set term=$temp
|
||||
</screen>
|
||||
|
||||
</appendix>
|
||||
|
|
@ -0,0 +1,475 @@
|
|||
<!--
|
||||
;; $Id: vars.docbook,v 1.1 2012/08/25 07:19:03 gdr Exp $
|
||||
-->
|
||||
|
||||
<chapter id="gsh-shellvars">
|
||||
<title>Shell Variables</title>
|
||||
|
||||
<sect1>
|
||||
<title>Using Shell Variables</title>
|
||||
|
||||
<para>
|
||||
<command>gsh</command> supports variables in the
|
||||
shell environment. These variables can be used by any shell
|
||||
utility or script. Many EXE files and shell scripts predefine
|
||||
certain shell variables that contain formatting options or other
|
||||
options for a specific utility. As an example, the <command>ls</command>
|
||||
utility looks for the variable TERM that defines the
|
||||
terminal type currently being used. When <command>ls</command> is started, it
|
||||
reads the value of the TERM variable and avoids printing Apple II specific
|
||||
MouseText characters if the set terminal type does not support them.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<command>gsh</command> has set aside certain variables
|
||||
for its specific use. Shell utilities should be aware of these
|
||||
variables and use them appropriately. Use caution when changing
|
||||
shell variables, because the change could affect more than just
|
||||
the shell.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="gsh-shellvars-scope">
|
||||
<title>Scope of Shell Variables</title>
|
||||
|
||||
<para>
|
||||
There are two types of processes that are
|
||||
involved in any discussion of a multitasking system. The original
|
||||
process, <command>gsh</command> for example, is called a parent process.
|
||||
If <command>gsh</command>
|
||||
invokes a process, such as
|
||||
<command>ls</command>,
|
||||
<command>cp</command>, or
|
||||
<command>mv</command>,
|
||||
that process is called a child process. It is possible for any
|
||||
process to define a variable. These variables will not be made
|
||||
available to other processes unless the program that defined the
|
||||
variable specifically makes them available.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The <command>export</command> command makes variables
|
||||
defined by one process available to its children. See the example
|
||||
<filename>gshrc</filename> shell script shown in
|
||||
<xref linkend="gsh-start-custom"/>.
|
||||
In the case of the shell, most of its
|
||||
variables are exported and, therefore, all shell utilities can
|
||||
read the value of a shell variable. However, programs cannot
|
||||
change the value of a shell variable. In general, executables
|
||||
share their environment with that of the shell, so that a utility
|
||||
can change variables in its parent's environment. This allows
|
||||
communication between programs and the shell.
|
||||
<!-- tribby: that last paragraph seems to be self contradictory;
|
||||
can a child process affect the parent's environment variables or not? -->
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="gsh-shellvars-predef">
|
||||
<title>Description of Predefined Shell Variables</title>
|
||||
|
||||
<para>
|
||||
The following variables have special meaning to <command>gsh</command>.
|
||||
Shell variable names are not case sensitive.
|
||||
</para>
|
||||
|
||||
<variablelist>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
$0, $1, $2, ...
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
String values that contain the arguments to
|
||||
a shell script. Variable 0 contains the name of the
|
||||
script. The first argument begins with variable 1 and so
|
||||
on.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
$<
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
When encountered, the variable is expanded
|
||||
using a value obtained from standard input. This provides
|
||||
a means of obtaining user input in script files. Note
|
||||
that the shell variables are expanded before the
|
||||
command-line is executed
|
||||
(See <xref linkend="gsh-shellvars-access"/>.)
|
||||
When prompting the user for input,
|
||||
be sure that the prompt is in a separate command-line
|
||||
than the $<. Also, if the user wishes to enter a value
|
||||
with spaces, he must quote what he types with
|
||||
double-quotes.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
$ECHO
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A boolean value that, if defined, will
|
||||
cause commands in a shell script to be echoed to standard
|
||||
output.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
$FIGNORE
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
This variable, if set, contains a list of
|
||||
filename suffixes. When doing command or filename
|
||||
completion, <command>gsh</command> will ignore any filename with a
|
||||
suffix listed in FIGNORE. For example, you might want to
|
||||
<command>set fignore=".A .ROOT .SYM"</command>
|
||||
to ignore object files and other compiler droppings.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
$HISTORY
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A numeric value that contains the number of
|
||||
history commands (command-lines) remembered. If the value
|
||||
is 0 or HISTORY is undefined, all commands will be
|
||||
remembered. Previous command-lines can be called back
|
||||
with the UP-ARROW and DOWN-ARROW.
|
||||
(See <xref linkend="gsh-interact-hist"/>.)
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
$HOME
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The HOME directory is the main directory of the
|
||||
shell; it is the directory <command>gsh</command> defaults to when it
|
||||
starts. The tilde ("~") character can be used
|
||||
as a shorthand method of accessing the HOME directory
|
||||
(as discussed in <xref linkend="gsh-product-expand"/>).
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
$IGNOREEOF
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A boolean value that, if enabled, will
|
||||
prevent <command>^D</command> from exiting the shell.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
$NOBEEP
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A boolean value that, if set, will prevent <command>gsh</command>
|
||||
from sounding the speaker when errors occur while editing
|
||||
a command-line.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
$NODIREXEC
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A boolean value that, if set, will disable <command>gsh</command>'s
|
||||
feature of treating directory names as commands; i.e. if
|
||||
a directory is specified as a command, <command>gsh</command> will
|
||||
move to that directory as though the cd command was being
|
||||
used.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
$NOGLOB
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A boolean value that, if set, will
|
||||
disable filename globbing. Command arguments will be
|
||||
passed to their commands "as-is", without any
|
||||
wildcard expansion.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
$NONEWLINE
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A boolean value that, if set, will disable
|
||||
extraneous carriage returns being output before and after command
|
||||
execution. Examples given in this manual have
|
||||
this option set.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
$PATH
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A string value that defines the pathnames
|
||||
where shell scripts, EXE utilities, and SYS16 programs
|
||||
can be found
|
||||
(See <xref linkend="gsh-product-locate"/>).
|
||||
Because GS/OS uses colons as separators in pathnames, <command>gsh</command>
|
||||
cannot allow colons to be used as separators in the PATH
|
||||
variable, as UNIX does. If one of the path entries has a
|
||||
space within it (which is possible with the HFS FST),
|
||||
then the space should be quoted with a backslash, "\".
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
$PRECMD
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
This is actually a special <emphasis>alias</emphasis> and not an environment
|
||||
variable.
|
||||
If PRECMD is defined then its value is taken as a a command to be executed
|
||||
just before gsh prints the prompt for a command line. For example,
|
||||
<command>alias precmd qtime</command> will print the time in English
|
||||
text before every prompt.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
$PROMPT
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
When <command>gsh</command> prompts you to enter a
|
||||
command, the prompt that appears before the cursor can be
|
||||
customized for your <command>gsh</command> environment. If PROMPT
|
||||
is undefined, the default prompt of "% " is
|
||||
used. The prompt string recognizes certain character
|
||||
sequences in the PROMPT variable and interprets them accordingly.
|
||||
The following are the special characters:
|
||||
</para>
|
||||
<para>
|
||||
<table colsep="1" frame="all" rowsep="1" tocentry="1" shortentry="0"
|
||||
orient="land" pgwide="0">
|
||||
<title>Prompt Special Characters</title>
|
||||
<tgroup cols="2">
|
||||
<colspec align="left"/>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>%h, %!, !</entry>
|
||||
<entry>current history number</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%t, %@</entry>
|
||||
<entry>current time of day in 12 hour am/pm format</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%d, %/</entry>
|
||||
<entry>current working directory</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%~</entry>
|
||||
<entry>current working directory with tilde replacement</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%c, %C, %.</entry>
|
||||
<entry>trailing component of current working directory</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%S, %s</entry>
|
||||
<entry>inverse mode on (%s) and off (%S)</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%U, %u</entry>
|
||||
<entry>
|
||||
begin and end underline mode (only on terminals that support
|
||||
underline; gnocon will use inverse mode instead)
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%%</entry>
|
||||
<entry>the single "%" character</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%n</entry>
|
||||
<entry>user name (as defined by $USER)</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%W</entry>
|
||||
<entry>date in mm/dd/yy format</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%D</entry>
|
||||
<entry>date in yy-mm-dd format</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>\n</entry>
|
||||
<entry>newline</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>\r</entry>
|
||||
<entry>carriage return</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>\t</entry>
|
||||
<entry>horizontal tab</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>\b</entry>
|
||||
<entry>bell</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
$PUSHDSILENT
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
If this variable is defined, <command>gsh</command>
|
||||
will not print the directory stack after any of the
|
||||
directory stack commands.
|
||||
(See <command>pushd</command> and <command>popd</command> in
|
||||
<xref linkend="gsh-commands-builtin"/>.)
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
$SAVEHIST
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A numeric value that contains the number of
|
||||
commands to save to disk when exiting <command>gsh</command>. These
|
||||
commands are then read back in when <command>gsh</command> is
|
||||
restarted which allows old commands to be reused. If the
|
||||
value is 0 or SAVEHIST is undefined, no commands will be saved to disk.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
$TERM
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
This variable contains the name of the
|
||||
terminal emulation that the shell and other applications
|
||||
should use. By default, it is "gnocon". When
|
||||
the shell encounters a <command>set term</command> command,
|
||||
it automatically calls the the <command>tset</command> to reload the
|
||||
termcap information.
|
||||
See also <xref linkend="gsh-app-termcap"/>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
$TERMCAP
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
This variable specifies the location of the <filename>termcap</filename>
|
||||
file. The shell and other applications look for <filename>termcap</filename>
|
||||
in the <filename>/etc</filename> directory, but if TERMCAP is set,
|
||||
the fully specified termcap file is used instead. This
|
||||
allows users to install custom termcap entries.
|
||||
See also <xref linkend="gsh-app-termcap"/>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
$USER
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A string that represents the login name of the
|
||||
current user. This variable is usually set by <command>login</command>(8).
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="gsh-shellvars-access">
|
||||
<title>Accessing Shell Variables</title>
|
||||
|
||||
<para>
|
||||
Shell variables are defined or changed with the
|
||||
<command>set</command> command. The <command>unset</command> command
|
||||
is used to delete a variable.
|
||||
See <xref linkend="gsh-commands-environ"/>
|
||||
for more information on the <command>set</command> and
|
||||
<command>unset</command> commands.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To access shell variables from the command
|
||||
line or a shell script, use the character "$" followed
|
||||
by the variable name. The dollar sign character will expand the
|
||||
variable to its value. If you wish to use the dollar sign
|
||||
character in a string from the command line, remember to enclose
|
||||
it in single quotes or use the "\" escape character. If
|
||||
you use double quotes, the shell will try to expand the variable.
|
||||
To differentiate the variable name from characters that may
|
||||
immediately follow it, the variable name may be optionally
|
||||
surrounded with braces, "{" and "}".This
|
||||
provides a very powerful way of user interaction with shell
|
||||
scripts.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
</chapter>
|
||||
Loading…
Reference in New Issue