gopher://gopher.studiolab45.net/0/info/tutorial.text
GOPHER TUTORIAL
This tutorial shows you how to do things like make the long filenames
and add links to your Gopherspace. I originally wrote this tutorial for
my fellow staff of the now-defunct pretentiousgamer.com, but anyone is
free to use it.
You can find most of this stuff in the (py)gopherd man page, but I think
the
explanation given in there is somewhat confusing, plus there are some
pitfalls
that I've found that aren't explained in the man page. Therefore, I see
fit
to write my own tutorial.
The first thing to understand about Gopher is that browsing Gopher is like
browsing your local filesystem, or an FTP site. Hence, the conventions
that
apply to the World Wide Web don't apply here in Gopherspace. Rather than
having set pages that link to other pages, Gopher is very hierarchial.
This
has its advantages and disadvantages, but that's the way things work.
Keeping this key concept in mind will help you understand why Gopher is
the
way it is.
(Some trivia: Gopher was originally created to give users the ability to
browse files on other computers throughout the Internet without having to
log into them a la FTP.)
That said, you can make a basic Gopher site simply by putting files and
directories into your Gopher directory, but you probably don't want those
file names appearing to visitors, and you may also want to link to other
sites.
CREATING LONG NAMES
In addition to your regular files, there are some special files that your
Gopher server will read and perform certain actions after reading those
files. One of these files is .names. .names is the file where you put in
the actual file name and what you want the name to be as it appears when a
visitor is browsing your Gopher site. The dot in front of the name
indicates that this is a hidden file (all files with a dot in front of
them
are hidden files on Unix and Unix-like systems, and since Gopher, like a
lot
of Internet protocols, was designed using Unix, it sticks to this
convention). The basic format for this file is as follows:
Path=[path to file]
Name=[nifty long file name]
where Path is the actual path to the file and Name is the name as you want
it to appear. That's it. Simple, right?
Well, there's one pitfall: if you just put in the name of a file in the
current directory, your Gopher server will put out *two* links to that
file:
one with the real file name, the other with the longer file name that you
want the visitors to see. Here's an example of what will do that:
Path=somefile.txt
Name=Some Random File With a Cool Name
To prevent this from happening, you add a ./ to the Path entry, like so:
Path=./somefile.txt
Name=Some Random File With a Cool Name
What you're doing is asking the Gopher server to read the path that the
actual file is in again (in this case, the same as the current directory).
For some reason, it needs to do this to associate the name with the file
correctly.
If you want to make a file that's further down the hierarchy available
near
the top, say you have something stored in mystuff/rants/somerant.txt and
you want it to appear on the top level, just link to it with that exact
path
name and it will appear on the directory that the .names file is in:
Path=./mystuff/rants/somerant.txt
Type=0
Name=My Intelligent Rant
The caveat here is that you *must* provide the Gopher item type for the
link
to work.
This works for directories as well.
One more thing (and this goes for every entry you create in any special
file, not just .names): if you delete a file, make sure you delete the
entry
pointing to the file, othewise the Gopher server will provide a link to a
file that doesn't exist!
LINKING TO OTHER SITES
One way that Gopher differs from FTP (and which makes it more similar to
the
World Wide Web) is its ability to link to different sites as well as files
on different sites.
To link to a Web site, just put this in your .names file:
Path=/URL:http://www.somecoolsite.com
Type=h
Name=Some Cool Site Name
The syntax is the same for FTP sites as well:
Path=/URL:ftp://ftp.somegoodfiles.org
Type=h
Name=Some Good FTP Site
You can also do the same for other Gopher sites, but there's a way to link
to other Gopher sites more seamlessly:
Path=
Host=gopher.somesite.com
Type=1
Port=70
Name=Cool Gopher Site
Note that in this case the "Name" attribute is mandatory, since there is
no
path. The "Host" entry is simply the URL to point to. The standard
Gopher
port is 70. This is optional, but may help speed things along. The Type
is
1 because you're linking to a Gopher directory, even if it's on another
site. The Type is mandatory.
You can also link to other files on other sites by using the corresponding
Gopher item type number. The full list is later in this document in
addition to a separate one in this directory.
ABSTRACTS
An abstract in Gopher terms is a line of text that describes a directory,
file, or link.
Unfortunately this is the one major feature of Gopher that some Web
browsers do not implement (and hurrah to the Mozilla folks for including
it in the latest versions of Firefox, the Mozilla Suite, Camino, and
SeaMonkey; previous versions did not support abstracts). It is still
useful for real Gopher browsers as well as when a user is browsing a
Gopher site through a Web interface as provided by servers such as
pygopherd (which this site uses) or GoFish.
For directories, simply put whatever text you want to show up in a file
called .abstracts in the directory you want the abstract to show for. If
the directory is a subdirectory, then when a visitor is looking at the
directory above the one with the abstract, the abstract will appear below
the link to the directory. The text will show above everything else once
the visitor goes into the directory.
There are two ways to create an abstract for a file: the method above,
using
[filename].abstract as the filename of the abstract (replacing [filename]
with the name of the file to create the abstract for, of course), and
putting an entry into .names, a method that is not documented in the
(py)gopherd manual:
Path=./goodfile.txt
Type=0
Name=Good File
Abstract=This file has some good information in it.
The second method has one caveat that you need to know about, though: if
you want to put in text that is more than one line long, you must end each
line with a "/" like so:
Abstract=This is a really long abstract. This file is so important that
it/
needs more than one line to describe it.
GOPHER ITEM TYPES
These are mainly taken from the pygopherd man page, with my own
annotations
where I think they're warrented. The item types consist of exactly one
number or letter and always make up the second part of a Gopher URL, right
after the domain name. An example:
gopher://somecoolgopher.com/1/
The 1 is the gopher item type, in this case a directory (the root
directory
in this URL). Another example:
gopher://somecoolgopher.com/0/files/info.txt
The 0 is the item type, saying that the file being accessed is a standard
ASCII text file. This applies even though the file is in a subdirectory,
which is type 1.
Here are the Gopher item types. Note that since this server uses
pygopherd,
I've left the pygopherd-specific information in. My comments are in
brackets ([]).
0 Plain text file
1 Directory
2 CSO phone book server (not implemented by PyGopherd)
3 Error condition; text that follows is plain text
4 Macintosh file, BinHex format
5 DOS binary archive (not implemented by PyGopherd; use
type 9
instead)
6 uuencoded file; not directly generated by PyGopherd
automatically, but can be linked to manually. Most gopher
clients will handle this better as type 1.
7 Search
8 Telnet link
9 Binary file [Use this for any file that doesn't already have
an item type elsewhere.]
+ Redundant server (not implemented by PyGopherd)
c Calendar (not implemented by PyGopherd)
e Event (not implemented by PyGopherd)
g GIF-format graphic [When Gopher was implemented, the only
file
formats that were widely used were GIF and JPEG, and GIF was
more heavily used.]
h HTML file [Also works for links in general to other
protocols
that display files in Web browsers, such as HTTP and FTP.]
I Any kind of graphic file other than GIF
i Informational text included in a directory that is displayed
but does not link to any actual file.
M MIME multipart/mixed file
s Any kind of sound file
T tn3270 link
X [Hidden file - use this to keep a file from being shown in
the
directory listing.]
- UMN-specific -- signifies that this entry should not be
dis-
played in a directory entry, but may be accessed via a
direct
link. This value is never transmitted in any Gopher
protocol.