gno/doc/refs/intro.tex

%
% GNO Overview
%
% $Id: intro.tex,v 1.17 2012/08/25 21:53:25 gdr Exp $
% 

\documentclass{report}
\usepackage{html}
\usepackage{hthtml}
\usepackage{makeidx}
\makeindex
\bodytext{
	bgcolor=#ffffff 
	textcolor=#000000
	linkcolor=#0000FF
	vlinkcolor=#001177
	alinkcolor=#001177
	}

\begin{document}

\title{GNO Overview and Installation}
\author{Jawaid Bazyar, Tim Meekins, Devin Reade}
\date{November 1997}
\maketitle

\bibliographystyle{plain}
\nocite{*}

%
% These are various html links used throughout this document.
%
\newcommand{\faqhtml}[1]{\htlink{#1}
	{http://www.gno.org/~gno/FAQ.html}}
\newcommand{\faqtext}[1]{\htlink{#1}
	{ftp://ftp.gno.org/pub/apple2/gs.specific/gno/doc/faq/CURRENT}}
\newcommand{\gnodocs}[1]{\htlink{#1}
	{http://www.gno.org/~gno}}
\newcommand{\delphi}[1]{\htlink{#1}
	{http://delphi.com}}
\newcommand{\overview}[1]{\htlink{#1}
	{http://www.gno.org/~gno/intro.html}}
\newcommand{\kernel}[1]{\htlink{#1}
	{http://www.gno.org/~gno/kern.html}}
\newcommand{\gsh}[1]{\htlink{#1}
	{http://www.gno.org/~gno/gsh/index.html}}
\newcommand{\manpages}[1]{\htlink{#1}
	{http://www.gno.org/~gno/manindex.html}}
\parindent=0pt
\parskip=1pc

The GNO Multitasking Environment is Copyright 1991-1999 by
Procyon Enterprises Incorporated.

\begin{flushleft}
First Edition, 1991. \\
Second Edition, August 1996. \\
Third Edition, November 1997.
\end{flushleft}

The ORCA/C run-time libraries are Copyright 1987-1999 Byte Works, Inc.,
and distributed with permission.

This product includes software developed by the University of California,
Berkeley and its contributors.

GNO/ME versions 2.0 and later also include several utilities and
libraries produced by
outside authors and in the public domain. This software is included
solely as a convenience to users of GNO/ME, and is not considered part
of GNO/ME for copyright purposes.

GNO and GNO/ME are trademarks of Procyon Enterprises Incorporated.

Apple IIGS, APW, Finder, GS/OS, ProDOS, Macintosh, and HFS are registered
trademarks of Apple Computer, Inc.

AppleWorks GS is a trademark of Claris Corp.

UNIX is a registered trademark of The Open Group in the USA and other
countries.

\bf
Important Notice:
\rm
This is a fully 
copyrighted work and as such is protected under the copyright
laws of the United States of America.
While GNO is now freely available, GNO remains copyrighted and
is not to be considered in the public domain.

Procyon Enterprises Inc.
MAKES NO
WARRANTIES, EITHER EXPRESS OR IMPLIED, REGARDING THE ENCLOSED
COMPUTER SOFTWARE PACKAGE, ITS MERCHANTABILITY OR ITS FITNESS FOR
ANY PARTICULAR PURPOSE. THE EXCLUSION OF IMPLIED WARRANTIES IS
NOT PERMITTED IN SOME STATES. THE ABOVE EXCLUSION MAY NOT APPLY
TO YOU. THIS WARRANTY PROVIDES YOU WITH SPECIFIC LEGAL RIGHTS.
THERE MAY BE OTHER RIGHTS THAT YOU MAY HAVE WHICH VARY FROM STATE
TO STATE.

Procyon Enterprises, Inc. \\
P.O. Box 641 \\
Englewood, CO 80151-0641 USA \\
(303) 781-3273

\chapter{Credits}

\begin{quote}
\em
Always listen to experts. They'll tell you what can't be done, and why.
Then do it.  \bf --- Lazarus Long \rm
\end{quote}

The {\bf GNO} {\bf M}ultitasking {\bf E}nvironment for the Apple IIgs. \\
Copyright 1991-1999, Procyon Enterprises Inc. and Tim Meekins.

The following people and organizations have contributed to the GNO base
distribution; many other people have contributed stand-alone packages and
their efforts are also appreciated:

\begin{description}
% \setlength{\itemindent}{1.5cm}

\item[Kernel]
Jawaid Bazyar;
Derek Taubert.

\item[GNO Shell]
Tim Meekins;
Dave Tribby.

\item[Documentation]
Jawaid Bazyar;
Albert Chin;
Tim Meekins; 
Devin Reade;
Andrew Roughan.

\item[Utilities]
Matt Ackeret;
Leslie Barstow;
Soenke Behrens;
James Brookes;
Evan Day;
Tilghman Lesher;
Devin Reade;
Ian Schmidt;
Derek Taubert;
Greg Thompson;
Dave Tribby;
Philip Vandry.

\item[Libraries]
Jawaid Bazyar;
Soenke Behrens;
James Brookes;
Douglas Gwyn;
Tilghman Lesher;
Devin Reade;
Henry Spencer;
Derek Taubert;
Dave Tribby;
Phillip Vandry;
Mike Westerfield;
Procyon, Inc.;
The Byte Works, Inc.;
University of California, Berkeley.

% \setlength{\itemindent}{0cm}
\end{description}

The libraries contain other contributions that are necessarily anonymous,
as they are derived from code fragments for which no author information
was available.

With many thanks to:
\begin{itemize}
\item
Bill Gulstad, Rob Knauerhase,
and everyone on the gno-devel and GNOBETA Internet mailing lists.
\item 
Dave Lyons, for tolerating Jawaid's endless
questions since the beginning of time, for getting Jawaid
started in IIgs programming, and for calling GNO ``cool''.
\item
Mike Westerfield, for your
technical assistance and all your work in making great
development tools for the IIgs.
\end{itemize}

Special thanks to:
\begin{itemize}
\item
Matt Deatherage, for egging Jawaid on to
complete the project; also, for your most helpful
technical support through DEVSUPPORT --- you guys made this thing possible!
\item
Randy Hyde, for telling Jawaid it couldn't be done.
\end{itemize}

\chapter{Preface}

Computers are tools. The flexibility of a
tool determines how useful it is. Early computers were much like
the one this software was written for: the Apple IIgs. They could
only run one program at a time, and their usefulness was limited
to what the particular program the user was executing offered. In
the late 1960's, a team of researchers at AT\&T began
developing the UNIX operating system. The UNIX design was
partially based on the premise that most programs are I/O bound,
that is, most of the time the program executes is spent waiting
for user input or other I/O operations. While one program is
waiting for I/O, why not allow another program to execute? This
is what they did, and the result was one of the most successful
computer operating systems ever created.

The Apple IIgs, like the Macintosh it is
modelled after, provides very limited multitasking abilities in
the form of desk accessories (NDAs). The programs in the NDA menu
are available in whatever application you use as long as it
follows Apple's guidelines. However, there are many graphics
based programs that don't support NDAs, and in addition there is
a wealth of software that has been developed for the Byte Works'
ORCA environment. This environment is mainly text-based, and thus
makes access to NDAs impossible. As if that wasn't enough, it's
very difficult to write an NDA to allow the application to keep
running concurrently. So the benefits are lost, and we're back at
ground zero.

Enter the GNO Multitasking Environment.
What was once just dreamed about is now a reality. GNO/ME
provides an environment that is almost entirely compatible with
software developed for the ORCA environment. But GNO/ME also
provides a wealth of new abilities, lots of new ground for
developers and users alike.

Before we begin describing GNO, we'd like to
respond to those who say such a multitasking system isn't
possible on the Apple IIgs. Obviously it is: you hold it in your
hands. Some say the Apple IIgs isn't powerful enough to make
multitasking useful. We point out that the Apple IIgs is much
more powerful than the first computers UNIX was designed to run
on; they only had 64K of real memory, and were 16 bit machines.
Some ask why you'd ever need to run more than one program at
once. These are the same people who asked why we'd ever need more
than 64K of memory, or more than 140K of storage on disks (end
soapbox).

\chapter{Overview}

\section{Introduction}

The GNO Multitasking Environment provides
pre-emptive multitasking. Many programs can be executing at the
same time; each is called a ``process''. Each process is allowed to
run for a short period of time (1/20th of a second on average).
When its time runs out, the current process is set aside and
another one chosen to run next. This cycle continues until there
are no more processes left (i.e. when you exit GNO/ME). Starting
up processes to run 'in the background' is a simple matter of
adding a few characters to the shell commands.

GNO/ME provides a shell that takes full
advantage of the multitasking ability provided. The most
important feature of the shell is job control (starting,
terminating, and suspending processes). But the shell also
provides power never before seen on the Apple IIgs. The ability
to choose files by ``wildcard'' has been around for a while, but
the GNO Shell takes this to a new level with ``regular
expressions'', a very powerful yet simple programming language.
Other benefits of the GNO shell are too numerous to mention. (see
the \bf GNO Shell User's Manual \rm  for details).

In addition to being compatible with the
ORCA system, GNO/ME is a very powerful programming environment.
Available to the programmer are all the calls needed to control
processes, support Inter-Process Communication, and other tools
needed in a multitasking environment.
In fact, a large portion of the libraries in GNO v2.0.6 and later
are based upon code from FreeBSD UNIX (see \hturl{http://www.freebsd.org}).
The version of FreeBSD on which the GNO libraries are based is also
available at \hturl{ftp://ftp.gno.org/cdrom/usr/src}.

GNO/ME also boasts the first completely
consistent method for accessing serial and console I/O. The IIgs
TextTools have been incredibly enhanced to provide a truly
all-encompassing interface for serial, console, and IPC
applications. Imagine being able to attach terminals to your GS,
and have a useful shell in each one. Multiuser BBSs, remote
dial-ups, UUCP or SLIP that doesn't take over your computer- the
applications are endless!

With all this talk of shell utilities, have
desktop users (users of programs like AppleWorks GS) been left
behind? Absolutely not. GNO/ME doesn't allow more than one
desktop program to run concurrently, but it DOES let you run a
desktop program with as many text applications as you like. In
other words, no functionality is lost from the IIgs by using
GNO/ME.

Finally, the GNO Multitasking Environment
comes with a large number of free utilities that bring some of
the power of a UNIX system to the Apple IIgs. Also, a number of
programming libraries are included that make it easy to port
programs from UNIX or MS-DOS systems to the Apple IIgs.

%
% Dave Tribby thinks we should add in a ``what's new in 2.0.6'' list 
% here.
%


\section{Documentation Roadmap}

There are many pieces to the GNO documentation.  The primary ones are
listed below.  They are available
at the \gnodocs{GNO Documentation Page} and via anonymous ftp from
\tt ftp.gno.org\rm.

\begin{itemize}
\item	\overview{GNO Overview and Installation Manual}.
\item	\gsh{GNO Shell User's Manual}.
\item	\kernel{GNO Kernel Reference Manual}.
\item	Online Manual Pages.
\item	\faqhtml{GNO Frequently Asked Questions (and Answers) List}.
\end{itemize}

If you are new to GNO, you should start with the Overview and Installation
Manual (this document).

The \gsh{GNO Shell User's Manual} provides information on using \bf gsh\rm, 
which is an ORCA-compatible shell.  It is the primary user interface
to GNO.

The \kernel{Kernel Reference Manual} gives detailed information about
the kernel, which is the heart of GNO.  It is intended mainly for programmers.

The ``Manual Pages'' are the traditional form of UNIX documentation.
They are normally viewed on your GS by typing ``man \it subject\rm'',
where \it subject \rm  is the name of the command, library routine, file
(and so forth) for which you are trying to obtain information.
Man pages are provided for the \manpages{base distribution}, and are
usually provided by authors of third-party programs.  Type ``man man''
from within GNO for detailed instructions on how to use the man pages.

The \faqhtml{FAQ} is a list of questions and answers that have come 
up many times; you should read the FAQ before posting any GNO questions
to \delphi{Delphi} or \bf comp.sys.apple2.gno\rm.  Your question may
already be answered.

More information, including an online GNO bugs database, status charts
for ongoing development, and GNO-related links are available online
at \gnodocs{http://www.gno.org/~gno'}.  Because of the nature of this
information, much of it is available only via the WWW, and not 
anonymous ftp.

\section{Hardware Requirements}

GNO/ME will work on any Apple IIgs with at least 2 MegaBytes of
memory and a hard drive.

You should have at least 5 MegaBytes of hard disk space free for GNO
v2.0.4.

GNO version 2.0.6 is \em much \rm  larger than previous versions.
Even if you are only installing v2.0.4 at this time, it is recommended
that you reserve at least one 32-megabyte ProDOS partition for
GNO-specific files.

We recommend 4 MegaBytes of Memory and an 
accellerator card, especially if you will be using GNO with many
background processes. A modem and access to an on-line service
will greatly speed access to technical assistance and new
utilities as they are made available.

\section{Obtaining GNO}

GNO is a large and complex system.  There are many pieces to it;
too many to list in detail here.  There are, however, two major
catogories of pieces.  The first is the base distribution, the
second are all the third-party ``add-ons''.  
(Some of the second category sometimes get moved into the base distribution).
Normally, one would install the base distribution, then install 
whichever third-party applications are desired.

Currently, there are available two versions of the base GNO distribution.
The first is version 2.0.4, which is the one last version released by Jawaid.
It is relatively stable and easy to install,
but has no TCP/IP support, a few known bugs, and is not getting
any kernel updates.  (Recent library updates can, to some extent, be used
with this version.)

The second available version is 2.0.6.  It is undergoing active development
and therefore includes bug fixes to v2.0.4, as well as TCP/IP support
in the kernel (it does not currently take advantage of Marinetti).
On the other hand, it is still of alpha quality;  it is difficult to 
install, has some incompatibilities with 2.0.4, and new bugs have been
introduced.  Once it has stabalized more, it will completely supercede
version 2.0.4.

Both base distributions are available via anonymous ftp.
Version 2.0.6 is also available in source form, including via anonymous cvs.
See the respective Installation chapters on downloading these files.

Third party applications are available (among other places) from 
\hturl{ftp://ftp.gno.org/pub/apple2/gs.specific/gno}.  Because this
collection has grown so large, James Brookes developed the \bf describe\rm
database (later maintained by Soenke Behrens and Devin Reade), which
provides a description and other information on the various GNO utilities.
Online interfaces to the database may be found at
\hturl{http://www.gno.org/~gno/describe/}
or
\hturl{http://www.servtech.com/public/phoenix/computers/gno/index.html}.

\section{Obtaining Assistance}

Since GNO was reclassified as freeware in the fall of 1997, 
Procyon no longer provides direct support to users, other than those
that had paid the full price for GNO prior to the reclassification.

There is, however, a group of programmers and users of GNO who are
able to render assistance on a volunteer basis.  Some of these programmers
are also actively involved in upgrading the base GNO distribution.

If you require assistance, the following two methods of contact are
preferred:
\begin{itemize}
\item
Post a message to the USENET news group, \bf comp.sys.apple2.gno\rm.
Remember that messages usually take at least a few hours to propagate
around the world.  Answers also take time to propagate.

\item
Ask a question on the Delphi Apple II Programmers' Forum.  There
are subject areas set up for GNO under ``third party technical support''.
Delphi is accessible via \hturl{http://delphi.com}.  (Delphi is
recommended for discussion of programming topics in general and
has, for the most part, taken over from Genie as the center of 
online Apple II communication.  Some packages are available free of
charge.  Visit Delphi for more details.)

Unlike USENET, on Delphi you should try to continue existing threads.
The current ones for GNO are:

	\begin{itemize}
	\item	Message 1045: GNO: System Installation and Configuration
	\item	Message 1046: GNO: References and Users' Manuals
	\item	Message 1047: GNO: Manual Pages
	\item	Message 1048: GNO: The Kernel
	\item	Message 1049: GNO: Shells
	\item	Message 1050: GNO: Libraries and System Header Files
	\item	Message 1051: GNO: Interfacing with ORCA
	\item	Message 1052: GNO: Networking and Telecommunications
	\item	Message 1053: GNO: General Discussion
	\end{itemize}

\item
Also on Delphi, there is a regularly scheduled GNO Programmers' Conference
on Monday and Thursday evenings from 10pm to midnight EST/EDT.  Devin
is usually around those evenings, although he sometimes misses the 
conference.  If you don't catch him the first time, be sure to try again
another day.
\end{itemize}

As a last resort, you can contact Devin Reade (one of the GNO
development team) at \htmailto{gdr@trenco.gno.org}.  Please don't
use this method unless absolutely necessary, as Devin is not always
available.  More importantly, asking questions in an open forum 
provides for peer review; if an answer is wrong, it can be corrected
by other developers.

Finally, for those who paid for GNO before it was reclassified, 
Jawaid can still be contacted at
\htmailto{bazyar@hypermall.com}.
Written correspondence should be directed to Procyon at:

\tt \begin{verbatim}
        Procyon, Inc.
        PO Box 641
        Englewood, CO 80151-0641 USA
        (303) 781-3273
\end{verbatim} \rm 

\section{Reporting Bugs}
\index{bugs}

In any large piece of computer software
such as the GNO/ME system, bugs are sure to turn up, no matter
how much testing is performed on the software before it goes out
the door. If you discover a bug in GNO/ME, we'd like to hear
about it. There are several things we require, however, to make
bug reports useful to us.

First of all, we need a complete
description of your computer system; how much RAM, what cards, in
what slots, what type of disk storage, etc. This information is
very important in tracking down hardware-dependent bugs. Also, we
need to know the version numbers of the software involved; the
GNO Kernel, the GNO Shell, and any utilities.

Second, we need a step-by-step description
of how to duplicate the bug. If this requires writing down
individual keystrokes, then we need it. Only in this way can we
decide whether the bug is hardware dependent or global.

Once you have collected this information, the preferred method of
submitting it is to use the online GNOBugs database at
\hturl{http://www.gno.org/~gno/bugs.html}.
Alternately, you could contact the 
GNO developers in one of the ways mentioned in the section on
\bf Obtaining Assistance\rm.

\section{User Projects}

If you're working on a project which
utilizes GNO/ME in some way, we'd like to know about it. Just
Devin by email and tell him about your project. If possible, he'll
coordinate your efforts with those of other programmers. If we
really like your project and think it may be useful to others, it
may be included on the next GNO/ME distribution!

It is, of course, good to not start work on something that is already
being worked on or already finished.  Before starting a project, you may
first wish to check the Program Status List at
\hturl{http://www.gno.org/gno/status-bin.html}
or the Library Status List at
\hturl{http://www.gno.org/gno/status-lib.html}.

\section{Software Piracy}

If you have illegally copied computer software from someone
and are now reading this, take a moment to reflect on what you've done.
Many computer software applications are huge projects, consuming
many man-years of effort, huge amounts of money, and a lot of grief on the
part of the developers.
For example, the Byte Works' ORCA languages and development 
environment (as of November 1997) consists of over 220,000 lines
of source code, \em not \rm  including the libraries, tool 
interface files, test programs, samples, or the 5 800k disks
of source in the courses for each language.  This work represents
approximately 17 man-years of development, support, marketing,
and management.

Is it right that you're now benefiting from
developers' efforts without any just compensation to the authors?

Many programmers are born, bred, and raised in the spirit of
computing. They love to write software, and probably always
will. But if they cannot make enough money to make it
worthwhile to continue their work, then they won't; because by
worthwhile, we mean not only food on the table, but resources for
expansion and continued growth. In short,
support them and they'll support you.
 
Computer software is very inexpensive when you
consider what it allows you to do.
 
To all you who properly pay for the software you use:
Thank you.

\section{Suggested Readings}

The following are recommended readings for users:
\begin{itemize}
\item Learning UNIX \cite{gardner}
\item The UNIX Operating System \cite{christian}
\item Peter Norton's Guide to UNIX \cite{norton}
\item UNIX in a Nutshell \cite{gilly}
\item Life with UNIX --- A Guide for Everyone \cite{libes}
\item UNIX for the Impatient \cite{abrahams}
\item Learning the vi Editor \cite{lamb}
\end{itemize}

The following are recommended readings for programmers:
\begin{itemize}
\item The Design and Implementation of the 4.3 BSD UNIX Operating System \cite{leffler}
\item The UNIX Programming Environment \cite{kern_pike}
\item Advanced Programming in The UNIX Environment \cite{stevens}
\item Advanced UNIX Programming \cite{rochkind}
\item Using C on the UNIX System \cite{curry}
\item POSIX 1003.1 \cite{posix1}.  This would normally be considered
	required reading except that the POSIX standards (like most
	standards) are very expensive.  If you can obtain a copy, you
	should try to do so.
\end{itemize}

The following should be considered as required readings for programmers:
\begin{itemize}
\item The ANSI X3.159-1989 (ANSI/C) Standard \cite{ansic}.  This, however,
	is an expensive manual and beyond the financial reach of many
	hobby programmers.  A low-cost alternative is Schildt's
	Annotated ANSI/C Standard \cite{schildt}, provided that you 
	ignore Schildt's annotations.
\item The C Programming Language \cite{kern_ritchie}
\item Apple IIgs ToolBox Reference, Volume 1 \cite{tbr1}
\item Apple IIgs ToolBox Reference, Volume 2 \cite{tbr2}
\item Apple IIgs ToolBox Reference, Volume 3 \cite{tbr3}
\item GS/OS Reference \cite{gsos}
\item Apple IIgs Firmware Reference \cite{gsfirm}
\item Apple Numerics Manual \cite{numerics}
\item Programmers Reference for System 6.0 \cite{pr600}
\item Programmers Reference for System 6.0.1 \cite{pr601}
\end{itemize}

\section{Freeware Status}

The following message was distributed by Jawaid Bazyar by email and
by USENET news, in the fall of 1997:

\begin{quote}

As the man behind Procyon Enterpsises Inc., a long-time Apple IIGS
developer and one of the last commercial developers for the platform,
I regret to announce the end to sales of my first product, the GNO
Multitasking Environment (GNO/ME).

With my last distributor, EGO Systems, closing its doors, I cannot
justify the time and expense of continuing to produce the software. I
also didn't feel it was fair to the customers to continue to charge them
for the product, when I would be unable to support them in the manner
I would like, due to my intense involvement in my new ISP business.

However, instead of simply stopping sales of GNO and letting the software
wander into oblivion, I am placing GNO into ``freeware'' status, and I am
also making available all source code to the 2.0.4 version to the public
and the development community.

I will still sell printed manuals to anyone who wants one, for \$20 or
so, but this is just to cover printing and shipping costs. Purchasing
a manual will not entitle the buyer to support from me of GNO/ME.

Anyone who paid the normal \$89 price to EGO Systems (or to me directly)
for GNO will continue to receive support from me, and I will rely partly
on the help of the ``GNO-Devel'' list for assistance in this support.

Speaking of that, the GNO-Devel list is headed by Devin Reade,
and its members are programmers who have the time and devotion to
continuing to develop the GNO system. To their capable hands I leave
the software. The first task of this group is to put together a GNO
distribution based on the latest ORCA/C and ORCA/C libraries. Devin will
post followup info on csa2g and any inquiries should be directed to him
at <gdr@trenco.gno.org> for the moment.

Thank you all for your support in the past of my company and myself,
and best wishes to you all for the future!

\begin{flushleft}
Regards, \\

Jawaid Bazyar \\
President, Procyon Enterprises Inc. \\
President, Interlink Advertising Services Inc. \\
\end{flushleft}

\end{quote}

\chapter{Installation for GNO v2.0.4}

\em
\textbf{Important Note:}
GNO v2.0.4 is no longer supported.  New installations should be using
v2.0.6 or later.
\rm

\em 
\textbf{Important Note:}
This chapter is very out-of-date.  It was written for GNO v2.0.1, and
has had only minor updates since that time.  It very much needs to
be rewritten (concurrently, of course, with updates to the actual
installation process).  However, this is unlikely to occur since v2.0.4
has been superceded.  That notwithstanding, if you have suggestions
for updating this document (without making major changes
to the GNO v2.0.4 distribution itself), please email
your suggestions to Devin Reade.

Before attempting to install GNO v2.0.4, you are strongly encouraged to 
read this entire chapter, and then consult the 
\faqhtml{GNO FAQ} (Frequently Asked Questions list, which is also
available via \faqtext{ftp}) for those sections related to installation.
\rm

GNO/ME is a very large system. Most of the
system is stored on the three disks in a compressed format. For
this reason we recommend that you read this section carefully and
use the included automated installation program to save yourself
the major headache of arranging everything. You'll need a hard
drive partition with at least 5 Megabytes free to install GNO/ME.
The entire installation process should take no longer than 10
minutes. 

If you are upgrading from GNO 1.0 to GNO
2.0, we recommend that you install GNO 2.0 on a new area of your
hard drive. This is because GNO 2.0 provides new versions of
almost all the utilities and other software provided with GNO
1.0. You can then move the parts of your old system that aren't a
part of the standard GNO 2.0 distribution over to the new
installation. 

The installer program is able to the copy
the GNO libraries for use with the ORCA languages and tools. If
you want to use your ORCA languages and tools, you should answer
the appropriate questions during the install process. ORCA
installation is covered in more detail below.

\section{Obtaining GNO v2.0.4}

The base distribution for GNO v2.0.4 is not actually available as a 
self-contained package.  Instead, it is necessary to install GNO
v2.0.1, then incrementally upgrade it to v2.0.2, v2.0.3, and finally
v2.0.4.

These packages are available via anonymous ftp from 
\tt ftp://ftp.gno.org/pub/apple2/gs.specific/gno/base204\rm.
There is a three-disk set for GNO v2.0.1, and a 
single disk for each of the upgrades to versions 2.0.2, 2.0.3, and 2.0.4.
You should download all of these files.

There is also a custom version of ORCALib that should be installed if you
are using ORCA/C v2.0.x with GNO v2.0.4.

Remember to download these disk archives in binary mode.

\section{Installing GNO v2.0.1}

\begin{description}
\item[Step 1]

Copy the contents of \texttt{/GNO.Disk1} to the partition where you want
to install GNO/ME. The easiest way to do this is to run the IIGS
Finder, insert the \texttt{/GNO.Disk1} disk, and drag the 
\texttt{/GNO.Disk1} icon onto the icon of the drive you want to install on.
The Finder will tell you that the disks are of a different size, and
ask you if you wish to place the contents of \texttt{/GNO.Disk1}
in a folder on the hard drive partition.
Answer ``Yes'', and the Finder will copy the data.

\item[Step 2]

Open the newly created \texttt{GNO.Disk1} folder on the partition
and execute ``Kern'' by double-clicking on the \texttt{Kern} icon.
\texttt{GNO.Disk1} contains a minimal GNO system which you have
just started up. You'll see some copyright messages, and after a few
seconds the desktop will appear.

\item[Step 3]

Install will ask you questions before the installation process begins.
Questions asked by Install are boldfaced in this section.
If you're uncertain of how to answer, click on the ``Info'' button
to get more information on the question. This information is
reproduced here for ease of reference.

\begin{description}

\item[Do you have existing Byte Works (ORCA) language products?]

If you use Byteworks language products such as ORCA/C, ORCA/M,
ORCA/Pascal, and so forth and wish to use them from GNO/ME then
answer ``Yes'' to this question. Otherwise, answer ``No''.

Clicking on the ``Info'' button will display the following text:

	\begin{quote}

	If you currently use products such as ORCA/C, ORCA/Pascal,
	ORCA/M, etc., and wish to use them from GNO/ME then you should
	answer ``Yes'' to this dialog.
        

	Install will then ask you to locate the file ``ORCA.SYS16'' (the
	ORCA Shell). Usually, it will be in a directory called ``ORCA'' on
	one of your hard drive partitions. On our system, it is
	\texttt{:software:orca}.
	The location of this file determines where Install puts the
	GNO-specific ORCA/C header files and libraries (in the ORCA
	LIBRARIES directory).  If you have renamed ORCA.SYS16 to
	something else, select that instead. 

	Install uses this information to correctly set the ORCA prefixes
	and add the EXECUTABLES directory to the \$PATH variable in your
	gshrc file.  See the GNO Shell User's Manual, Appendix B, for
	more information on the ORCA prefixes.

	\end{quote}

\item[Do you want to install the modified ORCA/C 2.0 ORCALIB library?]

If you have ORCA/C 2.0 installed and you answered ``Yes'' to the
previous question, then you should answer 'Yes' now.
If you have ORCA/C 1.3 installed, or you do not have any ORCA languages or
tools, then you should answer ``No''.

Clicking ``Info'' will display the following text:

	\begin{quote}

	GNO/ME 2.0 comes with a modified version of the ORCA/C ORCALIB
	standard library. This library adds specific support for some of
        GNO's special files (pipes, terminals, etc) transparently
        and corrects other problems the standard ORCALIB has with
        GNO.
        
	This special ORCALIB is only for use with ORCA/C 2.0. It will
	NOT work with previous versions of ORCA/C.
        

	Note that all of GNO's other libraries (libgno, libbsd, libc)
	work fine with ORCA/C 1.3.

	\end{quote}

\item[Do you want to install the Multi-User package?]

If you wish to have the Multi-User package installed, answer ``Yes''.
It is recommended that new users do not install this package until they are
familiar with the system. This package is not fully discussed in the
GNO/ME manuals and may introduce many unfamiliar concepts.

Clicking ``Info'' will display the following text:

	\begin{quote}

	The ``Multi-User'' package consists of a number of
	cooperating programs, including \bf init\rm(8) and \bf login\rm(8).
	MU provides for password-protected access to the GNO Shell via the
        console or serial ports (modems and dedicated terminals).
        It also handles multiple user accounts, and a certain
        level of protection between users. 

	If you will be using a terminal with GNO, or want to be able to dial
        into GNO with a modem, you should install MU.
        
	You may wish to hold off setting up the Multi-User package until you
        learn your way around GNO a little better, as it's simple
        to set up MU later.

	\end{quote}

\end{description}

\item[Step 4]

The Installer will now proceed to arrange the GNO Multitasking
Environment on your hard drive. Initially, the contents of
\texttt{/GNO.Disk1} will be moved into the proper places on the
volume you have chosen. When asked by the Installer, you should place
\texttt{/GNO.Disk2} and \texttt{/GNO.Disk3} into the disk drive. The
contents of these disks will be extracted and decompressed into their
proper places.

\em
If the installer cannot finish it's tasks for some reason, it will
abort to the shell. At this point you should study the error messages
to determine the cause of the failure, 
\rm

\item[Step 5]

When the Installer finishes, you will be returned to the GNO prompt.
At this time you should type ``exit'' to return to Finder and delete
the \texttt{GNO.Disk1} directory, as it is no longer needed (GNO
is completely installed in a subdirectory ``\texttt{GNO}'' on the
same partition \texttt{GNO.Disk1} is on.

\end{description}

\section{Installing GNO v2.0.2 Through v2.0.4}

GNO versions 2.0.2 through 2.0.4 were distributed as sequential
updates to version 2.0.1, rather than as complete distributions.
Consequently, you should install each of the version 2.0.2,
2.0.3, and 2.0.4 distributions, \em in sequence, \rm  over top of your
version 2.0.1 distribution.

You should also obtain and install the Multi-User Update.

\section{What Has Been Installed?}

\em
\textbf{Note:}  This list of directories is somewhat out of date.
You should consult the \faqhtml{GNO FAQ} (also available via
\faqtext{ftp}) for more current information.
This section will be updated, but likely only after GNO v2.0.6 is 
released.
\rm

If you examine the directory that you chose
for GNO/ME, you will find that the Installer has created several
directories. Here is a brief rundown of thier contents:


\begin{rawhtml}
<!-- cleantable-start -->
\end{rawhtml}
\begin{tabular}{ll}

\bf :gno:bin: \rm	& 
\begin{minipage}[t]{8cm}
	This directory contains the executable shell utilities included
	with the GNO/ME package.
\end{minipage} \hfill \\


\bf :gno:dev: \rm	& 
\begin{minipage}[t]{8cm}
	This directory contains device drivers. The GNO/ME package
	includes serial drivers for the IIgs' built-in modem and
	printer ports.
\end{minipage} \hfill \\

\bf :gno:etc: \rm	& 
\begin{minipage}[t]{8cm}
	Various system configuration files
\end{minipage} \hfill \\

\bf :gno:initrc \rm	& 
\begin{minipage}[t]{8cm}
	This a startup file for kern and must remain in this directory.
\end{minipage} \hfill \\

\bf :gno:kern \rm	& 
\begin{minipage}[t]{8cm}
	This is the GNO kernel. Launch this to start GNO/ME.
\end{minipage} \hfill \\

\bf :gno:lib: \rm	& 
\begin{minipage}[t]{8cm}
	This directory is provided for programming libraries that are
	used only occasionally.  Various applications may also keep
	auxilliary files here.  It is currently empty.
\end{minipage} \hfill \\

\bf :gno:tmp: \rm	& 
\begin{minipage}[t]{8cm}
	This directory is used by various utilities as location for
	their temporary files.  It is currently empty, and should
	be cleaned on periodically.
\end{minipage} \hfill \\

\bf :gno:user: \rm	& 
\begin{minipage}[t]{8cm}
	This directory is created if you installed the Multi-User package.
	It contains a user directories for users of the system.
	Currently there is only one: ``root''. 
\end{minipage} \hfill \\

\bf :gno:usr: \rm	& 
\begin{minipage}[t]{8cm}
	This directory contains UNIX System Resources (USR).
\end{minipage} \hfill \\

\bf :gno:usr:bin: \rm	& 
\begin{minipage}[t]{8cm}
	Miscellaneous utilities.
\end{minipage} \hfill \\

\bf :gno:usr:man: \rm	& 
\begin{minipage}[t]{8cm}
	This directory contains the manual pages for the 'man' utility.
	There are eight categories of information as defined by UNIX
	standards. These eight categories are presented in either
	source (man) or preformatted (cat) form.
\end{minipage} \hfill \\

\bf :gno:usr:games: \rm	& 
\begin{minipage}[t]{8cm}
	The classic ``Hunt the Wumpus'' game, and perhaps others.
\end{minipage} \hfill \\

\bf :gno:usr:sbin: \rm	& 
\begin{minipage}[t]{8cm}
	System administration utilities.
\end{minipage} \hfill \\

\end{tabular}
\begin{rawhtml}
<!-- cleantable-end -->
\end{rawhtml}

\chapter{Installation for GNO v2.0.6}

\em 
\textbf{Important Note:}
Before attempting to install GNO v2.0.6, you are strongly encouraged to 
read this entire chapter, and then consult the 
\faqhtml{GNO FAQ} (Frequently Asked Questions list, which is also
available via \faqtext{ftp}) for those sections related to installation.
\rm

\em These instructions should be considered as draft quality.  If you
have suggestions on or corrections to these instructions, please forward
them to Devin Reade.\rm

This chapter contains information on how to install the newest version
of GNO, which is version 2.0.6 or later.  It explains how to install
the base \em binary \rm  distribution.  Installation of GNO sources such that
you are able to \em build \rm  the base distribution itself are at this
time beyond the scope of this document.

At this time, unfortunately, installing GNO is fairly cumbersome.
Gsh's scripting abilities are crude at best, and for various reasons
the Apple Installer program is not sufficient,
When sh (the Bourne Shell) is finished for GNO, installation should be easier.

Information in this chapter may change
significantly from release to release, so even if you have previously
installed a version newer than v2.0.4, you should review this chapter
prior to doing a new installation.

\section{Planning Your System}

The install scripts assumes that your \em new\rm  distribution will be 
installed on to the two volumes \bf /gno \rm  (ProDOS) and \bf /gno-hfs \rm 
(HFS or AppleShare).
It also assumes these volumes already exist and are \em empty\rm.
You may use other volume names,
but you will have to edit certain files before you run your distribution.

If you installing over an existing v2.0.6 or later distribution, ensure
that you read the section on \bf Planning for Future Upgrades\rm.

You will need \it at least \rm  the following amount of disk space.  
It is recommended that you dedicate an entire 32Meg ProDOS partition to
GNO.

\begin{tabular}{ll}
boot disk (used only for installation)	& 800k \\
binary distribution (shk files)		& 5.3 MB \\
binary distribution (extracted)		& 12.0 MB \\
complete GNO source (optional)		& 15.0 MB \\
\end{tabular}

Before you start, you should also ensure that your system meets the
minimum hardware requirements, as documented in \bf Overview\rm.

In order to install GNO, you will need some way to download the NuFX
archive files to your GS.  You will also need GS-ShrinkIt, which is available
from 
\hturl{ftp://ftp.gno.org/pub/apple2/gs.specific/archivers/gshk11.bsc}.

Part of the GNO installation still requires use of a text editor.  The
GNO boot disk ships with \bf vi\rm  installed;
if you do not know how to use \bf vi\rm  (or you need a refresher), see 
\hturl{http://www.jaws.umn.edu/~tobkin/vi}
for a good tutorial and quick reference guide.

\section{Upgrading from GNO v2.0.4 or Earlier}

If you already have an existing GNO installation running v2.0.4 or 
earlier, then there is no automated upgrade mechanism.  Instead, upgrades
must be done manually.

Before doing such an upgrade, ensure that you have a backup of your 
existing system.

Although it is more disk space intensive, you should upgrade from your
existing v2.0.4 system by first installing the current distribution into
an otherwise unused directory hierarchy (a ``from scratch'' install).
You should then review each component of your old distribution and move
any necessary files into the new hierarchy.  It is \em strongly \rm 
recommended that you make maximal use of the \bf /usr/local \rm hierarchy
so that future upgrades are easier.  See the section in this Guide on
\bf Planning for Future Upgrades \rm for details.

This method of upgrade is tedious, but in the end it makes for a cleaner
GNO distribution and easier future upgrades.

\section{Downloading and Extracting the Binary Distribution}

If you have not yet read the section on \it Planning Your System\rm,
please do so now.

Your first step is of course to download the distribution.
The distribution is available from 
\hturl{ftp://ftp.gno.org/pub/apple2/gs.specific/gno/base}.
You should have the following NuFX archives:

\begin{itemize}

\item{\bf gnoboot.shk\rm}
This is the GNO installation bootstrap disk.  It should be extracted to
a ProDOS-formatted 800k floppy disk named ``/gno.boot'' (the name is
critical).  It does not include a copy of GS/OS and is
therefore not bootable; you will have to boot your system in the normal
fashion.

\item{\bf gno.01.shk\rm, \bf gno.02.shk\rm, ... \bf gno.16.shk\rm}
These disk archives contain the main portion of the GNO distribution.
They must be placed in a single temporary subdirectory on a hard drive,
Zip disk, Appleshare volume, or other large capacity storage device.
They should not yet be extracted.

\item{\bf gnohfs.shk\rm}
This archive consists of files that do not conform to ProDOS naming 
conventions.
It should be placed into the same directory as were the files
{\bf gno.01.shk\rm, \bf gno.02.shk\rm, ... \bf gno.16.shk\rm}.
While it is possible to run GNO without any HFS partitions
at all, it is recommended that you have available to GNO a small amount
of space on an HFS partition.  If you use the \bf namespace\rm(5) facility,
it is unnecessary to dedicate an entire HFS partition to GNO.
Note that Appleshare volumes may be used in lieu of HFS volumes.

\end{itemize}

Using the Finder or a similar program, ensure that you have an empty ProDOS 
partition \bf /gno \rm, and an HFS or AppleShare partition online.  The
former \em may \rm  be named something else, but note the instructions
below for handling this situation.  The latter is assumed to be called
\bf /gno-hfs \rm  (modify the following instructions accordingly), and
need not be otherwise empty.  The two subdirectories \bf HFSinclude \rm
and \bf man \rm  will be created on \bf /gno-hfs  \rm during the installation
process.

Next, using GS-ShrinkIt or a similar program, extract the contents of the
file gnoboot.shk onto an 800k floppy named \bf gno.boot\rm.  
The name of the floppy is critical.  While you may use a hard drive 
partition for \bf gno.boot\rm, this is likely a waste of hard drive space
since \bf gno.boot\rm  will only be used while installing GNO, not while
running it.

People have also reported that they were able to use a RAM disk for
\bf gno.boot\rm  without problems (thanks to Kirk Mitchell for first
reporting this).

You should now do the following steps:

\begin{comment}

If your volumes are named something else, replace the names in the cd commands
below with the appropriate name.
 
\end{comment}


\begin{enumerate}

% We would like to be using bold face type for some parts of this, but
% it appears that the current version of tex2html can't handle boldface
% within an enumerated list.

\item
From your program launcher (typically the Finder), run the program
/gno.boot/kern.
This is the GNO kernel.  It will come up in 
single user mode and you will be logged in as root running a 
gsh
shell session.

Note that the boot disk currently uses the version 2.0.4 GNO kernel; this
is a temporary measure due to a bug with using newer kernels in single user
mode.  When GNO is installed on your hard drive, you will have a newer
kernel.

\item
As per the instructions shown on the boot screen, you should now read the
file /gno.boot/README.install.  The contents of that file, however, are
identical to the numerated instructions below; you need only read one or
the other set.

%% README.install-start
\item
Set your DOWNLOAD\_DIR environment variable to the directory
into which you placed the base distribution NuFX archive files
(gnoboot.shk, gnohfs.shk, gno.01.shk, and so forth).  For
example, if the NuFX files were in /download, you would type:

\begin{verbatim}
	setenv DOWNLOAD_DIR /download
\end{verbatim}

Ensure that you use slashes (``/'') rather than colons (``:'') as the
pathname delimiter.  Do not use a trailing slash.

\item
Install the majority of the GNO base distribution files by
changing directory into your destination directory and running
the installboot1 script. Assuming that you will be installing
to the partition /gno, the commands would be:

\begin{verbatim}
	cd /gno
	/gno.boot/installboot1
\end{verbatim}

This step takes quite a while, even with an accelerated IIgs.
Have patience.

\item
There are a small number of recommended files that do not follow
ProDOS naming conventions.  If you wish to install these files,
make sure that you have an HFS or Appleshare disk online. Change
directories to that disk (or subdirectory) and run installboot2.
Assuming that the HFS disk is /gno-hfs, the commands are:

\begin{verbatim}
	cd /gno-hfs
	/gno.boot/installboot2
\end{verbatim}

This step is optional.  It is possible to use the GNO binary
distribution without an HFS partition, but some information
will be missing.

\item
You should now edit the file /gno/etc/namespace.  If your
files were extracted onto a volume other than /gno, you will
have to replace all the ``:gno:'' strings with the appropriate
path.  Similarily, you will have to replace ``:gno-hfs:'' if
that is not the name of your HFS (or Appleshare) partition
where you ran the installboot2 script.  Note that you cannot
currently use pathnames in the namespace file that contain spaces.

The gno.boot disk includes the vi utility to do these edits.
You can also edit the namespace file with any other text editor
of your choosing, as long as it is done before you try to run
your new GNO distribution.

A vi tutorial and quick reference guide may be found at
\hturl{http://www.jaws.umn.edu/~tobkin/vi}.

\begin{comment}
You may want to put /usr onto a different partition; it will
get fairly large over time.

If you have a RAM disk, you should consider having it renamed
to /tmp using renram5(8) or mktmp(8), in which case its entry
should be removed from the namespace file.

\end{comment}
For a description of the namespace file, see the kernel
reference manual, or the namespace(5) manual page at
\hturl{http://www.gno.org/~gno/man/man5/namespace.5.html}

\item
During the extraction process, the following files were placed
into the /gno/System directory:

\begin{verbatim}
	/gno/System/Desk.Accs/GNOSnooperII
	/gno/System/Desk.Accs/SuspDA
	/gno/System/Desk.Accs/TMTerm
	/gno/System/Drivers/FilePort
	/gno/System/Drivers/FilePort.Data
	/gno/System/Drivers/NullPort
	/gno/System/System.Setup/GNOBug
	/gno/System/System.Setup/SIM
\end{verbatim}

It is recommended that these files be copied into the relevent
directories in the System folder of your boot partition.  The
GNOBug PIF is only required if you have GSBug installed.  If
you install GNOBug you should afterward sort the System.Setup
directory so that GNOBug appears before GSBug (the latter of
which is commonly called ``debug.init'').

\item
If you are not short of disk space, you should create .so links
for your manual pages.  (See the mkso(8) man page for an
explanation.)  You can do this by executing the following
commands:

\begin{verbatim}
	cd /gno/usr/man
	mkso -v -H /gno-hfs/man mkso.data
\end{verbatim}

If you installed GNO somewhere other than /gno and /gno-hfs, then
edit the above lines accordingly.  If you did not install files
onto an HFS (or Appleshare) partition at all, then execute the
following commands instead:

\begin{verbatim}
	cd /gno/usr/man
	mkso -v mkso.data
\end{verbatim}

\item
You can now return to your program launcher (the Finder,
ProSEL-16, or whatever you used to start /gno.boot/kern) by
typing ``exit'' at the prompt.  To startup up your new version
of GNO, you should then launch /gno/kern.  You will then see
a ``login:'' prompt.  Enter ``root'' as the user name; you will
not yet need a password.

%% README.install-end

\end{enumerate}

\section{Planning for Future Upgrades}

\it The information in this section is currently under review; please
forward any additions, deletions, or corrections to Devin Reade.\rm

One of the concerns for a system that is as large and as complex as GNO
is how to keep it updated without losing any custom configuration that
been added locally since the last installation.  This section attempts to
document how to minimize such conflicts and, where the conflicts can't
be avoided, where they are likely to occur.

In the context of updating GNO, there are three main sets of files.  The
first one is anything that is in the \bf /usr/local \rm hierarchy.  The
subdirectories and files under \bf /usr/local \rm are intended strictly
for site-specific customization.  The GNO base distribution does not,
and never will, add or modify files within \bf /usr/local\rm.  (It may,
however, ensure that certain subdirectories exist.)  For this reason,
it is recommended that any files (such as programs, configuration files,
or manual pages) that you wish to have on your system but are not part
of the GNO base distribution are placed within the \bf /usr/local \rm
hierarchy.  If you wish to have this customation available to another
GNO installation, it would then be sufficient to copy the \bf /usr/local \rm
hierarchy in its entirety.

\em
NOTE:  There is a single (temporary) exception to the comments above.  The
current GNO base distribution will copy in the file 
\textbf{/usr/local/lib/startup.mk}
which is used by the program dmake, and which is a duplicate of 
\textbf{/usr/lib/startup.mk}.
When dmake gets updated to properly use 
\textbf{/usr/lib/startup.mk}
as it's configuration file, then 
\textbf{/usr/local/lib/startup.mk}
will no longer be created by the GNO base install scripts.  If you have 
customized 
\textbf{/usr/local/lib/startup.mk}
for your site, you first save your startup.mk file elsewhere, then merge
those customizations into the new startup.mk.
\rm

The second set of files are those which have been written such that they
(or their configuration files) have pathnames which are hardcoded, and 
therefore must reside outside of the \bf /usr/local \rm hierarchy.  Some
of these programs can be forced into the first set described above by
setting appropriate environment variables; see the program's documentation
for details.  For the remainder, you should keep track of which programs
you have installed, and where they (or their configuration or data files) 
reside.  Unless there is a name conflict with files in the GNO base 
distribution, these files won't be overwritten or deleted during a GNO
update, but they obviously will not be copied in when doing a ``from scratch''
installation.

The third set of files are those are created while installing the GNO
base distribution, but which almost certainly have been modified in 
any existing GNO site.
These are all configuration files of one sort or another.
(If you are doing a fresh install, you can ignore
this set.)  If you are using the GNO ``from scratch'' installation scripts
rather than the update scripts
(\em not yet available\rm)
then you \em must \rm ensure that you have backups of these files so
that you can restore them after the install scripts have completed.  You
should not merely copy your old versions over the new ones; instead
compare the old files to the new to verify if there have been features
added which should be propagated to your old customized files.

The files which are known to be in the third set are listed here:

\begin{verbatim}
	/etc/glogin
	/etc/group
	/etc/hosts
	/etc/inittab
	/etc/motd
	/etc/networks
	/etc/namespace
	/etc/passwd
	/etc/rchost
	/etc/syslog.conf
	/etc/whereis.conf
	/home/root/gshrc
	/lib/orcacdefs/defaults.h
	/var/adm/newuser/newid
	/var/adm/newuser/skel/glogin
	/var/adm/newuser/skel/gshrc
\end{verbatim}

If you find that you have to modify any files outside of the \bf /usr/local \rm
(or \bf /home\rm ) hierarchy, you should record which files have been so
modified, together with a brief description of the necessary changes.

\section{Custom Configuration}

\it The information in this section is currently under review; please
forward any additions, deletions, or corrections to Devin Reade.\rm

This section describes the configuration changes that are commonly done
on newly installed systems.

If you have not already read the section on \bf Planning for Future 
Upgrades \rm, you should do so now.

\subsection{Passwords}

If you ever expect to connect your IIgs to a network (including the internet)
it is recommended that you password protect all of your GNO user IDs.
This is done with the
\htlink{passwd}{http://www.gno.org/~gno/man/man1/passwd.1}(1)
command; see the manual page for details.

Because there is no inherent security features in the Apple IIgs in general
(or GNO in particular), password protecting accounts on a stand-alone
machine does not gain any real level of security; if someone has physical
access to your IIgs, then they can get anything off of it that they want
to.  On the other hand, password protecting your accounts can't hurt, and
it is an excellent habit to get into.  (Rather, \em not \rm password 
protecting accounts is a very poor habit to get into.)

\subsection{Configuring the Namespace Facility}

\em This section is yet to be written. \rm

\subsection{Configuring Host and Network}

\em This section is yet to be written. \rm

\subsection{Configuring the System Logger}

\em This section is yet to be written. \rm

\subsection{Configuring the Shell}

\em This section is yet to be written. 
Talk briefly on /etc/glogin, \$HOME/glogin, and \$HOME/gshrc.
Leave real docs for the gsh manual.
\rm

\subsection{Message of the Day}

\em This section is yet to be written. \rm

\subsection{Adding Groups}

\em This section is yet to be written. \rm

\subsection{Adding Users}

\em This section is yet to be written. \rm

\subsection{Configuring Documentation Programs}

\em This section is yet to be written. 
Discuss /etc/whereis.conf, MANPATH, etc.
\rm

\subsection{Configuring Outbound SLIP}

\em This section is yet to be written. \rm

\subsection{Configuring Inbound Serial Connections}

\em This section is yet to be written. \rm

\section{Obtaining Source}

Source for the base distribution is available in one of two ways:
Anonymous FTP and anonymous CVS.

You can obtain the GNO source via anonymous FTP from 
\hturl{ftp://ftp.gno.org/pub/apple2/gs.specific/gno/base/src}.
The files in that directory hierarchy are updated daily from the
master repository.  Files that have been recently added or modified
will be listed in one or more of the 
\tt NEW.today\rm ,
\tt NEW.this.week\rm , or
\tt NEW.this.month \rm
files.

\em Please download only what you need.  Sites that attempt to download
all or large portions of the sources on a regular and frequent basis
without first requesting mirror status will be disabled. This is done
to keep a reasonable load level on Trenco.\rm

For those sites which are able to make use of CVS (Concurrent Versions
System), the GNO sources can also be obtained by anonymous CVS in 
pserver mode.  As there is as yet no CVS port to the GS, this implies
that you have another (probably UNIX) machine to which you are downloading
the sources.  Because of the size of the archive, you should also have
a reasonable speed of interconnect between your machine and \tt ftp.gno.org\rm.

The first time you obtain GNO sources via CVS, you must log in to the
repository, then check it out:

\begin{verbatim}
	cvs -d :pserver:cvs@ftp.gno.org:/usr/local/repository login
	Password: cvs
	cd /your/source/tree
	cvs -d :pserver:cvs@ftp.gno.org:/usr/local/repository checkout gno
\end{verbatim}

After this is done, you can update your sources to match the most recent
version by doing the following:

\begin{verbatim}
	cd /your/source/tree/gno
	cvs update -PAd
\end{verbatim}

Because doing updates by CVS does not use up as much bandwidth as 
does downloading the entire source tree, feel free to do cvs updates
on a regular basis.  It usually doesn't make sense to do them more
than once per day, though.

\chapter{Desk Accessories}

The following is a description of the desk
accessories that are shipped with GNO/ME.

\section{GSI NDA}

The \textit{Graphical Shell Interface New Desk Accessory}
allows you to access the shell from a window inside a
desktop application. Selecting ``GSI'' from the Apple menu opens a
window and brings up a shell in it. You can use the shell in this
window just as you would in text mode.

At this time, GSI doesn't support any
terminal emulations --- it's a ``dumb'' interface. As a result,
full screen programs like \bf less\rm(1) and \bf vi\rm(1) will not
work properly in GSI.

\section{Suspend NDA}

The Suspend New Desk Accessory allows you
to temporarily stop a desktop program and return to the text
shell. To return to the desktop program, simply type the foreground
command, ``\texttt{fg}''.

You may put desktop programs in the background
(through the ``\texttt{bg}'' command) 
at your own risk. This is not guaranteed to work for all programs,
and putting a desktop program in the background will not put the
Apple IIgs in text mode.

Also, do not run another desktop program
when one is currently suspended. The GNO kernel tries to cleanly
terminate the second program, but may not always be able to
accomplish this.

\section{GNO Snooper CDA}

The GNO Snooper CDA is a utility that is
very helpful in debugging software, and reporting system crashes.
Snooper has access to information inside the kernel that is not
generally available to processes.

When you enter the control panel and choose
``GNO Snooper'' a process list is displayed, which is
very similar to the \bf ps\rm(1) shell command, and a menu is presented
with the following options, each of which is invoked by typing it's
first letter:

\begin{description}
\item[D)etails]

Get detailed information on a process.
Snooper asks you for the process ID number of the process you
want to investigate. Snooper then dumps the state of the 65816
registers and shows various other information about the process.

\item[K)ill]

This option sends a SIGKILL to a process. Just type in the process ID
of the process you want to kill.

\item[P)rocess Group Dump]

Dumps the system process group tables,
which is very useful for debugging code which manipulates process
groups. The first table, ``pgrp'', is the process group reference
count table. This table lists how many processes (and TTYs)
belong to that process group. 
Process group ids start at 2, so the first pgrp listed is 2.

The second listing is the ttyStruct table.
This table shows to which process group each TTY belongs. The TTYs start
with .null (0), then move on to .ttyb, .ttya, .ttyco, etc.

\item[F)ile Table Dump]

Lists all open files known to GNO.
The information is presented in tuples. The first element is the
real GS/OS refNum or device driver ID. The second is the type of
file (GSOS, ttyXX, or PIPE). The third is how many references to
that file are open. This information is global, so if two
processes have .NULL opened, the refcount for .tty00 will be 2.

\end{description}

\bibliography{gno}

\parindent=20pt


\end{document}