Added gsh reference manual.

This commit is contained in:
Devin Reade 2012-09-03 23:27:31 -06:00
commit 64ec87937e
20 changed files with 5028 additions and 0 deletions

1
.gitignore vendored Normal file
View File

@ -0,0 +1 @@
gen

29
README Normal file
View File

@ -0,0 +1,29 @@
This is the documentation for GNO/ME (the GNO Multitasking Environment),
a UNIX-like environment for the Apple IIgs. See <http://www.gno.org/gno>.
This documentation, which uses modern documentation frameworks, is not
built on an Apple IIgs due to the non-availability of those frameworks
on the IIgs, and the related computational power and memory requirements
for running those frameworks.
The canonical location for the sources you see here is the master git
repository at <https://github.com/GnoConsortium/gno-docs>.
If you are looking for man page sources, they are kept in the main
GNO/ME repository at <https://github.com/GnoConsortium/gno>.
Manifest:
README - This file.
README.build - Detailed build instructions.
Questions or concerns should be discussed on the gno-devel mailing
list at <https://lists.gno.org/mailman/listinfo/gno-devel>.
Devin Reade
gdr@gno.org

27
README.build Normal file
View File

@ -0,0 +1,27 @@
The following are instructions on how to build the documentation.
Platform:
The canonical build platform is CentOS 5.x. You are welcome
to submit patches to allow the docs to build on other platforms,
as long as you don't break the primary build.
Required Tools:
GNU make
docbook2html (CentOS package docbook-utils)
docbook2pdf (CentOS package docbook-utils-pdf)
latex2html
Preparation:
Create the file etc/constpriv.mk. See the comments in etc/const.mk
for details.
Procedure:
To build the documents, type:
make
This will create a 'gen' subdirectory with all the documentation
in it.
On the official build server only, to install the documents, type:
make install

1
etc/.gitignore vendored Normal file
View File

@ -0,0 +1 @@
constpriv.mk

64
etc/const.mk Normal file
View File

@ -0,0 +1,64 @@
#
# Before this file is included, it is assumed that you have defined
# the following constants:
#
# SRCROOT - The relative path to the base of the docs source
# (that is, the relative path of the directory above
# the etc directory in which this const.mk file resides).
#
# WEB_HOME_BASE - This is the directory, relative GNO_PUBLIC_HTML, where
# the files being built should reside upon installation.
#
# SUBPROJECTS - The child directories into which the make should recurse.
# If the value is empty, then recursion will stop.
#
# In addition, also before this file is included, it is assumed that
# the including makefile will also have included the constpriv.mk file,
# also in this directory. The constpriv.mk file is not checked into
# the repository, but is expected to be created locally and containing
# the following variables:
#
# GNO_PUBLIC_HTML
# The directory where the GNO web pages are anchored. This
# top level directory is not managed by these files, but
# the files there need to reference these files. If you are
# not building this for the official GNO web site, you can
# just point this at a scratch directory somewhere.
#
# After this file is included, the including makefile is expected to
# define
# This is the name and address that will be given as contact info
# at the bottom of each of the HTML pages. Do NOT use '<' or '>' in the
# address.
NAME = Devin Reade
ADDRESS = gdr@gno.org
# The directory hierarchy into which generated files get placed.
OUTPUT_DIR = $(SRCROOT)/gen
# The base document root (see DOCROOT_INSECURE and DOCROOT_SECURE).
DOCROOT = $(OUTPUT_DIR)
# DOCROOT_INSECURE contains files that are available via http (unencrypted)
# access.
DOCROOT_INSECURE = $(OUTPUT_DIR)/insecure/gno
# DOCROOT_SECURE contains files that are only available via https
# (encrypted) access.
DOCROOT_SECURE = $(OUTPUT_DIR)/secure/gno
HTTP_SERVER = www.gno.org
HTTP_PORT = # :81
HTTPS_PORT = # :8443
FTP_SERVER = ftp.gno.org
DATE = $(SRCROOT)/etc/getdate -date
BUILD_FILES = GNUmakefile $(HEAD_PAGE) $(TAIL_PAGE) \
$(SRCROOT)/etc/const.mk \
$(SRCROOT)/etc/rules.mk \
$(SRCROOT)/etc/tailcat.mk
# This is where the files will eventually wind up.
TARGET_DIR = $(GNO_PUBLIC_HTML)/$(WEB_HOME_BASE)

74
etc/getdate Executable file
View File

@ -0,0 +1,74 @@
#! /usr/bin/perl -s
#
# Extract the date from the RCS Id string in a file.
#
# $Id: getdate,v 1.1 2012/08/26 02:27:36 gdr Exp $
#
use strict;
my @month;
push(@month,
"Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep",
"Oct", "Nov", "Dec" );
# for ($i=0; $i<12; $i++) {
# printf("month %d is %s\n", $i, $month[$i]);
# }
my $printdate = 0;
my $printversion = 0;
if (defined($::date)) {
$printdate = 1;
}
if (defined($::version)) {
$printversion = 1;
}
my %sortedDates;
my %sortedVersions;
my $date = "(unspecified date)";
my $version = "(unspecified version)";
while(<>) {
if (/\$Id([^\$]*)\$/) {
$_ = $1;
if (/^:\s+(\S+)\s+(\S+)\s+(\S+)\s+(\S+)\s+/) {
my $file=$1;
my $v=$2;
my $rawdate=$3;
my $time=$4;
if ($rawdate =~ m,(\d+)[-/](\d+)[-/](\d+),) {
my $year = $1;
my $m = $2;
my $day = $3;
my $mon = @month[int($2) - 1];
my $d = "$day $mon $year";
my $fakedate = int($day) + 100 * int($m) + 10000 * int($year);
$sortedDates{"$fakedate"} = $d;
$sortedVersions{"$fakedate"} = $v;
}
}
}
}
my @fakes = sort(keys(%sortedDates));
my $lastFake = pop @fakes;
if (defined($lastFake)) {
$date = $sortedDates{$lastFake};
$version = $sortedVersions{$lastFake};
}
if ($printdate) {
printf("%s\n", $date);
} elsif ($printversion) {
printf("%s\n", $version);
} else {
printf("getdate: bad invocation\n");
exit(1);
}
exit(0);

79
etc/rules.mk Normal file
View File

@ -0,0 +1,79 @@
#
# $Id: rules.mk,v 1.1 2012/08/26 02:27:36 gdr Exp $
#
$(WEB_HOME)/%.gif: %.gif
install -m644 $< $@
$(WEB_HOME)/%.png: %.png
install -m644 $< $@
$(WEB_HOME)/%.pdf: %.pdf
install -m644 $< $@
$(WEB_HOME)/%.txt: %.txt
install -m644 $< $@
build: buildLocal webHome $(TARGETS) webHomePerms $(BUILD_FILES)
@for s in X $(SUBPROJECTS); do \
[ "$$s" = X ] && continue; \
[ -d "$$s" ] || continue; \
(cd $$s; $(MAKE) $(MFLAGS) $@); \
done
# You can define additional rules for buildLocal if the default build
# rule is insufficient.
buildLocal::
@true
webHome:
@if [ -z "$(WEB_HOME)" ]; then \
echo "WEB_HOME not set"; \
exit 1; \
fi; \
[ -d $(WEB_HOME) ] || mkdir -p $(WEB_HOME)
webHomePerms:
@if [ -z "$(WEB_HOME)" ]; then \
echo "WEB_HOME not set"; \
exit 1; \
fi; \
find $(WEB_HOME) -type d \! -perm 0755 -exec chmod 0755 {} \; ; \
find $(WEB_HOME) -type f \! -perm 0644 -exec chmod 644 {} \;
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 {} \;
clean::
rm -f *~
@for s in X $(SUBPROJECTS); do \
[ "$$s" = X ] && continue; \
[ -d "$$s" ] || continue; \
(cd $$s; $(MAKE) $(MFLAGS) $@); \
done
clobber:: clean
buildDocbookHtml:: clean
@if [ -z "$(DOCBOOK_TOP)" ]; then \
echo "DOCBOOK_TOP is not set"; \
exit 1; \
fi
@htmldir="$(WEB_HOME)/html"; \
[ -d $$htmldir ] || mkdir -p $$htmldir; \
echo docbook2html -o $$htmldir $(DOCBOOK_TOP); \
docbook2html -o $$htmldir $(DOCBOOK_TOP)
# -cp -p *.png $(HTML_DIR)
buildDocbookPdf::
@[ -d $(WEB_HOME) ] || mkdir -p $(WEB_HOME)
@date
docbook2pdf -o $(WEB_HOME) $(DOCBOOK_TOP)
@date

23
etc/tailcat.mk Normal file
View File

@ -0,0 +1,23 @@
#
# $Id: tailcat.mk,v 1.1 2012/08/26 02:27:36 gdr Exp $
#
$(WEB_HOME):
mkdir -p $(WEB_HOME)
$(WEB_HOME)/%.html: %.html $(HEAD_PAGE) $(HEAD_PAGE_1) $(TAIL_PAGE) Makefile
@echo "making $@"; \
date="`$(DATE) < $<`"; \
cat $(HEAD_PAGE) $(HEAD_PAGE_1) $*.html $(TAIL_PAGE) | perl -p \
-e "s,%%DATE%%,$$date,g;" \
-e 's,%%HTTP_SERVER%%,$(HTTP_SERVER),g;' \
-e 's,%%HTTP_PORT%%,$(HTTP_PORT),g;' \
-e 's,%%HTTPS_PORT%%,$(HTTPS_PORT),g;' \
-e 's,%%FTP_SERVER%%,$(FTP_SERVER),g;' \
-e 's,%%HTML_TITLE%%,$(HTML_TITLE),g;' \
$(TAILCAT_LOCAL_REPLACEMENTS) \
> $@
@if [ "$(FIX_PERMS)" != "no" ]; then \
chmod 644 $@; \
fi
@$(WEBLINT) $@

23
refs/gsh/GNUmakefile Normal file
View File

@ -0,0 +1,23 @@
#
# GNO Shell
#
SRCROOT = ../..
WEB_HOME_BASE = refs/gsh
SUBPROJECTS =
include $(SRCROOT)/etc/constpriv.mk
include $(SRCROOT)/etc/const.mk
WEB_HOME = $(DOCROOT_INSECURE)/$(WEB_HOME_BASE)
HEAD_PAGE =
TAIL_PAGE =
TARGETS = buildDocbookHtml buildDocbookPdf
DOCBOOK_TOP = gsh.docbook
default: build
clean::
/bin/rm -rf $(WEB_HOME)/html
include $(SRCROOT)/etc/rules.mk
include $(SRCROOT)/etc/tailcat.mk

1195
refs/gsh/commands.docbook Normal file

File diff suppressed because it is too large Load Diff

60
refs/gsh/comply.docbook Normal file
View File

@ -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>

401
refs/gsh/errors.docbook Normal file
View File

@ -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 '&lt;' encountered.
</term>
<term>
gsh: Extra '&gt;' or '&gt;&gt;' encountered.
</term>
<term>
gsh: Extra '&gt;&amp;' or '&gt;&gt;&amp;' encountered
</term>
<listitem>
<para>
Text may be redirected to only one file.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
gsh: No file specified for '&lt;'.
</term>
<term>
gsh: No file specified for '&gt;' or '&gt;&gt;'.
</term>
<term>
gsh: No file specified for '&gt;&amp;' or '&gt;&gt;&amp;'.
</term>
<listitem>
<para>
A file must be specified when redirecting I/O.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
gsh: '|' conflicts with '&gt;' or '&gt;&gt;'.
</term>
<term>
gsh: '|' conflicts with '&lt;'.
</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>

472
refs/gsh/glossary.docbook Normal file
View File

@ -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>

94
refs/gsh/gsh.docbook Normal file
View File

@ -0,0 +1,94 @@
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/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>

557
refs/gsh/interact.docbook Normal file
View File

@ -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-&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>