Apple-2gs-SW/gno-docs
1
0
Fork 0
mirror of https://github.com/GnoConsortium/gno-docs.git synced 2024-11-08 16:07:21 +00:00
Code Issues Projects Releases Wiki Activity

Added gsh reference manual.

Browse Source
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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

132
refs/gsh/prefix.docbook Normal file
View File

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

1007
refs/gsh/product.docbook Normal file
View File

File diff suppressed because it is too large Load Diff

215
refs/gsh/start.docbook Normal file
View File

@ -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=&quot;:hard:gno:bin :hard:gno:usr:bin&quot;
10 set prompt=&quot;[%h] %S%t%s %C&gt; &quot;
11 set home=&quot;:hard:gno:user:root&quot;
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>

99
refs/gsh/termcap.docbook Normal file
View File

@ -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 &gt; .ttyb
set term=$temp
</screen>
</appendix>

475
refs/gsh/vars.docbook Normal file
View File

@ -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>
$&lt;
</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 $&lt;. 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>