tutes-dump/site-tutorials/gopher.html

<style type="text/css">
.box { border: 1px black solid; padding: 10px; }
#toc span { font-size: 150%; }
.pseudo-link { color: blue; text-decoration: underline; }
</style>

<h1>Gopher</h1>

<div id="toc">

<span>Contents</span>

<ol>
	<li><a href="#what">What is Gopher</a></li>
	<li><a href="#create">Creating your gopherspace</a></li>
	<li><a href="#view">Viewing gopherspaces</a></li>
	<li><a href="#publish">Publishing content</a></li>
	<li><a href="#phlog">Gopher log</a></li>
	<li><a href="#moles">Dynamic content (moles)</a></li>
</ol>

</div>

<h2><a name="what"></a>What is Gopher?</h2>

<p>
<i>From: http://en.wikipedia.org/wiki/Gopher_(protocol)</i>
</p>

<blockquote>
	<p>
	The Gopher protocol is a TCP/IP Application layer protocol
	designed for distributing, searching, and retrieving documents over the
	Internet [...]. The protocol offers some features not natively supported
	by the Web and imposes a much stronger hierarchy on information stored
	on it.
	</p>
</blockquote>

<p>
You can find more info here:
</p>

<ul>
	<li><a href="http://freeshell.org/index.cgi?faq?GOPHER"
	rel="external">FAQ &gt; GOPHER</a>
	</li>
	<li><a href="http://www.scn.org/~bkarger/gopher-manifesto"
		rel="external">http://www.scn.org/~bkarger/gopher-manifesto</a>
	</li>
	<li><a href="http://gopher.floodgap.com/overbite/relevance.html"
		rel="external">http://gopher.floodgap.com/overbite/relevance.html</a>
	</li>
</ul>

<!--
<h2>Gopher and browser support</h2>
-->

<h2><a name="create"></a>Creating your Gopherspace</h2>

<p>
  The command <q>mkgopher</q> can be used to create and manage
  your gopherspace.
</p>
<p>
  When you run <q>mkgopher</q>, you will be given a command
  prompt. You can issue the <q>HELP</q> command here to get
  a list of the available commands:
  <pre>
    HOWTO                 - Tips on managing your GOPHERSPACE
    setup                 - First step, create your GOPHERSPACE
    chmod                 - Set/Restore file permissions
    title                 - Title your site
    describe              - Create a site description
    mkdir     {directory} - Create a directory
    rmdir     {directory} - Delete a directory
    edit       {filename} - Publish a document
    upload     {filename} - Transfer a file via ZMODEM to SDF
    ls                    - List the current directory
    cd        {directory} - Change directory
    pwd                   - Present working directory
    gopher                - Browse your site
    quit
  </pre>
</p>
<p>
  The <q>setup</q> command will create a directory in your $HOME
  called <q>gopher</q>  (This directory is a link to
  /ftp/pub/users/$USER/ ). On it, you can put all the files you want to
  be available in your Gopherspace.
</p>

<p>
  Once you create your Gopherspace, the files you publish will be available
  at
  <a href="gopher://sdf.org:70/1/users/">
    gopher://sdf.org:70/1/users/$USER/
  </a>
  <br/>
  (note: currently, the directory listing at gopher://sdf.org:70/1/users/
  doesn't appear to list all user directories. You may have to directly
  navigate to gopher://sdf.org:70/1/users/$USER/ in order to view your
  files.
</p>

<h2><a name="view"></a>Viewing Gopherspace</h2>
<p>
  There are many ways to view gopherspace. The easiest for new users is
  one of the following:
</p>
<h3>SDF Gopher Command</h3>
<p>
  You can issue the <q>gopher</q> command, either from the SDF shell or
  from within the <q>mkgopher</q> command prompt. This gives a very basic
  browser to explore gopherspace.
</p>
<h3>Use Lynx</h3>
<p>
  <a href="http://lynx.invisible-island.net/">Lynx</a> is the <i>text</i> web browser.
  <br/>
  In addition to web browsing, Lynx is also capable of browsing gopherspace.
  <br/>
  From the SDF shell, you can issue the command:
  <pre>
    $ lynx gopher://sdf.org/
  </pre>
  and Lynx will start up at sdf.org's gopher root menu.
  </p>
<h3>Floodgap Gopher Proxy</h3>
<p>
  Floodgap.com provides a public gopher proxy that you can view in your
  web browser at <a href="https://gopher.floodgap.com/gopher/gw">https://gopher.floodgap.com/gopher/gw</a>.
  <br/>
  For more information, see the proxy info page:
  <a href="https://gopher.floodgap.com/gopher/">https://gopher.floodgap.com/gopher/</a>
</p>

<h2><a name="publish"></a>Publishing Content</h2>
<p>
You can use mkgopher to publish documents, create directories, etc.  You can
also manage your Gopherspace manually. If you decide to do so, remember that
the server will not display your content if it is not already visible to
everyone. That is, files need to world-readable (chmod o+r
$HOME/gopher/yourfile), directories need also to be world executable (chmod
o+rx $HOME/gopher/yourdir), etc. <span style="font-weight:bold;">The gopher
server
(<a href="gopher://gophernicus.org/1/software/gophernicus/">Gophernicus</a>)
will serve executable files under /cgi-bin and also gophermaps which have
executable permission as gopher CGIs or "moles" (see below). In the case of
gophermaps, this is likely to result in errors, so make sure your gophermaps
do not have execute permission (chmod -x
$HOME/gopher/yourdir/gophermap).</span>
</p>

<p>
The usual 'mkgopher -p' command has not yet been updated to reflect
Gophernicus' permissions requirements. So you may need to reset your
permissions for all files and directories in your gopher directory as noted
above. The following two commands will revert all files to world-readable
but non-executable, and all directories to world-readable but executable.
</p>

<code>
<pre>
find ~/gopher/ -type f -print0 | xargs -0 chmod 644
find ~/gopher/ -type d -print0 | xargs -0 chmod 755
</pre>
</code>

<p>
You may need to manually add execute permissions to any dynamic gophermaps
or files under /cgi-bin after runnig these two commands.
</p>

<h3>Gophermap</h3>

<p>
<span style="font-weight:bold;">Note:</span> You can view the sample
gophermap that comes with Gophernicus here:

<a href="http://slugmax.tx0.org/README.Gophermap">README.Gophermap</a>
</p>

<p>
Say that you have <q>file1.txt</q>, <q>file2.pdf</q>, <q>file3.rtf</q>
and <q>dir</q> in your Gopherspace (<q>dir</q> is a directory). That is,
<p>

<pre>
$ ls -lF
drwxr-x---  2 $USER  nobody  512 Dec  2 10:15 dir/
-rw-r-----  1 $USER  nobody    6 Dec  2 10:14 file1.txt
-rw-r-----  1 $USER  nobody    6 Dec  2 10:14 file2.pdf
-rw-r-----  1 $USER  nobody    6 Dec  2 10:14 file3.rtf
</pre>

<p>
When you visit it, if there is no file named <q>gophermap</q> (yes, this
file has no extension) you'll see a list of the files and the directory,
like this:
</p>

<pre class="box">
,,,                                                                 Gopher Menu
                                  Gopher Menu

 (DIR) dir
(FILE) file1.txt
(FILE) file2.pdf
(FILE) file3.rtf
</pre>

<p>
If there is a gophermap file, the server will parse it and will present
the content as you specified in gophermap.
</p>

<p>
The gophermap syntax is:
</p>

<pre>
XSome text here&lt;TAB&gt;/path/to/content&lt;TAB&gt;example.org&lt;TAB&gt;N
</pre>

<p>
where the first character (<q>X</q> in the example) is an
<q>itemtype</q> (more below), <q>Some text here</q> is the text that
you want to be displayed, &lt;TAB&gt; is a tab character,
<q>/path/to/content</q> is the location of the content,
<q>example.org</q> is the server where the content is located and
the last character (<q>N</q> in the example) is the server port
(usually it's 70). Content after the second &lt;TAB&gt; is optional if
you are linking to content in your Gopherspace.
</p>

<p>
The <q>itemtype</q> is one of these characters:
</p>

<table>
	<tr><th>Itemtype</th><th>Content</th></tr>
	<tr><td>0</td><td>Text file</td></tr>
	<tr><td>1</td><td>Directory</td></tr>
	<tr><td>2</td><td>CSO name server</td></tr>
	<tr><td>3</td><td>Error</td></tr>
	<tr><td>4</td><td>Mac HQX filer</td></tr>
	<tr><td>5</td><td>PC binary</td></tr>
	<tr><td>6</td><td>UNIX uuencoded file</td></tr>
	<tr><td>7</td><td>Search server</td></tr>
	<tr><td>8</td><td>Telnet Session</td></tr>
	<tr><td>9</td><td>Binary File</td></tr>
	<tr><td>c</td><td>Calendar (not in 2.06)</td></tr>
	<tr><td>e</td><td>Event (not in 2.06)</td></tr>
	<tr><td>g</td><td>GIF image</td></tr>
	<tr><td>h</td><td>HTML, Hypertext Markup Language</td></tr>
	<tr><td>i</td><td>"inline" text type</td></tr>
	<tr><td>s</td><td>Sound</td></tr>
	<tr><td>I</td><td>Image (other than GIF)</td></tr>
	<tr><td>M</td><td>MIME multipart/mixed message</td></tr>
	<tr><td>T</td><td>TN3270 Session/</td></tr>
</table>

<h4>Gophermap example</h4>

<p>
OK, let's say that you want to display a welcome message, a description for
<q>file1.txt</q>, <q>file2.pdf</q>and <q>dir</q>, a link to an external server, a
link to an http URL. Your gophermap should be like
this:
</p>

<pre class="box">
Welcome to my Gopherspace!

0My text file	file1.txt
9My pdf file	file2.pdf
1My dir	dir

0Why is Gopher Still Relevant?	/gopher/relevance.txt	gopher.floodgap.com	70
hAn http link	URL:http://sdf.org/
</pre>

<p>
Remember the gophermap syntax? Then be careful about tab characters.
In the example above, there are some &lt;TAB&gt;s. For instance, the third line is
</p>

<pre>
0My text file&lt;TAB&gt;file1.txt
</pre>

<p>
while the seventh is
</p>

<pre>
0Why is Gopher Still Relevant?&lt;TAB&gt;/gopher/relevance.txt&lt;TAB&gt;gopher.floodgap.com&lt;TAB&gt;70
</pre>

<p>
How come the pdf file has an itemtype 9? Well, not every kind of file
has its own itemtype, so you can use one that makes more sense.
</p>

<p>
Even if you don't need a blank line as the second line of your
document, you can find this useful as there is a known Lynx bug that
makes it display the second line together with the first (you can find
a patch for this here:
<a href="gopher://sdf.org/0/users/bulibuta/openbsd/patches/lynx-gopher-newline.patch" rel="external">gopher://sdf.org/0/users/bulibuta/openbsd/patches/lynx-gopher-newline.patch</a>).
</p>

<p>
This is (more or less) the output you'll see if you use a gophermap
like the one in the example above:
</p>

<pre class="box">
,,,                                                                 Gopher Menu
                                  Gopher Menu

       Welcome to my Gopherspace!

(FILE) My text file
 (BIN) My pdf file
 (DIR) My dir

(FILE) Why is Gopher Still Relevant?
(HTML) An http link
</pre>


<h2><a name="phlog"></a>Gopher log</h2>

<p>
A gopher log (<q>glog</q> or <q>phlog</q>) is similar to a blog, but
on gopherspace. You can create your phlog and add it to the <a
href="http://phlogosphere.org/" rel="external">phlogosphere</a>.
</p>

<p>
Maintaining a glog consists basically (but not necessarily) in creating an
entry (in your log directory) and modifying your phlog gophermap so that the
new entry is displayed with its creation date. There's a script that you can
run on SDF called <q>mkgopherentry</q> (located in /sys/sdf/bin/mkgopherentry)
that will allow you to do exactly that. It will also extract the first
paragraph from the entry and will add it on the gophermap with a
<q>Continued...</q> link that will point to the full post.  Creating an entry
is as simple as:
</p>

<code>mkgopherentry title textfile</code>

<p>
where the 2 arguments are self-explaining.
</p>

<p>
Say that you have two entries in your diary. If you use <q>mkgopherentry</q>,
they will appear like:
</p>

<pre class="box">
--This is my second post!--
    Tuesday, December 01th, 2009
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Cras eros turpis, tristique semper aliquet sit amet,
hendrerit vel enim. Integer pulvinar leo in dolor posuere
blandit.
<span class="pseudo-link">Continued...</span>


--First post--
    Monday, November 30th, 2009
First entry in my gopher log at SDF.
<span class="pseudo-link">Continued...</span>
</pre>

<p><em>NOTE:</em> You can use the 'phlog' command to add your phlog/glog to the gopher.club phlog listing, and 
  you can then update the listing after you create a post by running the following command: <code>touch ~ftp/pub/users/$LOGNAME</code>
</p>

<h3>Other glog/phlog software</h3>

<p>
There are some software authored by SDF members that you could find useful
if you want to maintain a gopher log.
</p>

<dl>

	<dt>germ</dt>
		<dd>
		<a href="gopher://sdf.org/1/users/wt/soft/my/germ/"
		rel="external">gopher://sdf.org/1/users/wt/soft/my/germ/</a>
		</dd>

	<dt>slerm</dt>
		<dd>
		<a href="gopher://sdf.org/0/users/slugmax/about-slerm.txt"
		rel="external">gopher://sdf.org/0/users/slugmax/about-slerm.txt</a><br />
		<a href="gopher://sdf.org/9/users/slugmax/code/slerm-1.8.tgz"
		rel="external">gopher://sdf.org/9/users/slugmax/code/slerm-1.8.tgz</a><br />
                <a href="http://slugmax.tx0.org/slerm-1.8.tgz"
                rel="external">http://slugmax.tx0.org/slerm-1.8.tgz</a>
		</dd>

	<dt>glog<dt>
		<dd>
		<a
		href="gopher://sdf.org/0/users/yargo/scripts/glog.sh"
		rel="external">gopher://sdf.org/0/users/yargo/scripts/glog.sh</a>
		</dd>

	<dt>mkphlog</dt>
		<dd>
		<a href="gopher://sdf.org/1/users/octotep/scripts/mkphlog/"
		rel="external">gopher://sdf.org/1/users/octotep/scripts/mkphlog/</a>
		</dd>

	<dt>phlogit</dt>
		<dd>
		<a href="gopher://sdf.org/0/users/slugmax/code/phlogit.txt"
		rel="external">gopher://sdf.org/0/users/slugmax/code/phlogit.txt</a>
		</dd>

	<dt>tirph</dt>
		<dd>
		<a href="gopher://sdf.org/1/users/papa/tirph"
		rel="external">gopher://sdf.org/1/users/papa/tirph</a>
		</dd>

	<dt>ugo</dt>
		<dd>
		<a href="gopher://sdf.org/1/users/chr/scripts/ugo/"
		rel="external">gopher://sdf.org/1/users/chr/scripts/ugo/</a>
		</dd>

<!--
	<dt></dt>
		<dd><a href="" rel="external"></a></dd>
-->

</dl>

<p>
You can find more resources in the <q>Glogging/Phlogging</q> section at
<a href="gopher://sdf.org/1/users/wt/soft/gopher"
rel="external">gopher://sdf.org/1/users/wt/soft/gopher</a>.
<p>

<h2><a name="moles"></a>Dynamic content (gopher CGIs or moles)</h2>

<p>
The server used by SDF (Gophernicus) is able to serve <q>moles</q>. Moles
are executable files under /cgi-bin that are processed by the server as
CGIs. This means that you can write a script, that the server will execute
and it will present the data that your mole dumps to standard output. With
moles you don't have to declare a content type header. Moles get arguments
from the address used to access the document and can be accessed with
whatever itemtype makes sense for the kind of output the mole generates.
</p>

<p>
You can code moles with the language(s) you are comfortable and can
use on SDF. Below we will see some examples using shell scripts.
</p>

<h3>Mole examples</h3>

<p>
Remember that your moles need to be executable (and readable) by everyone,
and under /cgi-bin. So you will have to do: <code>chmod 755
YOURSCRIPT.cgi</code>
</p>

<h4>fortune.cgi</h4>

<p>
The following example will generate a random fortune:
</p>

<pre class"=box">
#!/bin/sh
/usr/pkg/games/fortune
</pre>

<p>
Easy enough, isn't it? As it is raw text, you can access it using am
itemtype&nbsp;=&nbsp;0, that is:
gopher://sdf.org/0/users/YOUR-USERNAME/cgi-bin/fortune.cgi
</p>

<p>
Did you notice that <q>fortune</q> was called with
a full path? OK, that's because the server's path is
<q>PATH=/sbin:/bin:/usr/sbin:/usr/bin</q>. That means that if you call
a program without a path, the server will search in <q>/sbin</q>,
<q>/bin</q>, <q>/usr/sbin</q> and <q>/usr/bin</q>. There's no
<q>/usr/pkg/games</q>, or other path in the server's $PATH
(eventually, you can add a path of your choice with, e.g., 
<code>PATH=$PATH:/usr/pkg/games</code>).
</p>

<h4>ls.cgi</h4>

<p>
The following example will generate a list of files on a specified
directory. It will be possible to sort the content alphabetically or
by modification time, based on how you access the script.
</p>

<pre class="box">
#!/bin/sh

directory=/ftp/pub/users/YOUR-USERNAME
rel_dir=/users/YOUR-USERNAME
server=sdf.org
port=70

# The internal field separator is set to be a newline
IFS='
'

if [ -n "$1" -a "$1" = 'date' ] ; then
    ls_arg=t
fi

for i in $(ls -l${ls_arg} $directory) ; do

    content=$(echo "$i" | awk '{ print $9}')
    date=$(echo "$i" | awk '{ print $6,$7,$8}')

    if [ -z "$content" ] ; then
        continue
    fi

    if [ -d $directory/$i ] ; then
        itemtype=1
    else
        itemtype=0
    fi

    echo "$itemtype$content ($date) $rel_dir    $server $port"
done

</pre>

<p>
Note that the <q>echo...</q> line is<br />
<code>
echo "$itemtype$content ($date)&lt;TAB&gt;$rel_dir&lt;TAB&gt;$server&lt;TAB&gt;$port"
</code>
</p>

<p>
If you go to gopher://sdf.org/1/users/YOUR-USERNAME/cgi-bin/ls.cgi ,
you will see a list of your files sorted alphabetically. If you access
your mole as
gopher://sdf.org/1/users/YOUR-USERNAME/cgi-bin/ls.cgi?date , then
you'll see your files/directories sorted by modification time.
</p>

<h4>figlet.cgi</h4>

<p>
You can add some interactivity by using the itemtype 7. This itemtype
is intended to make it possible to type some characters in a search
field in your browser. However, you can use it to make it possible to
pass arguments to your scripts. The following example will use some
text you digit in the search field and will pass it through the
program <q>figlet</q>.
</p>

<pre class="box">
#!/bin/sh

IFS='
'

for line in $(/usr/pkg/bin/figlet "$@") ; do
    echo "i$line"  # This is itemtype=i + text
done
</pre>

<p>
When you access the script via
gopher://sdf.org/7/users/YOUR-USERNAME/cgi-bin/figlet.cgi , your
browser will ask you to input some text (the way it ask depends on the
browser), then it will show your text as figlet transforms it.
</p>

<p>
The <q>i</q> in the <q>echo...</q> line is important here. Indeed, the
document is been accessed with an itemtype <q>7</q> (but the same applies
for itemtype <q>1</q>), so the document should be structured similarly
to gophermaps. It's not a gophermap, though. That's why you need to
explicitily state the line should be displayed as simple (or <q>inline</q>)
text.
</p>

<h3>Caveat</h3>

<p>
Besides what was said in the last paragraph of the <q>figlet.cgi</q>
example, there's also another thing to stress. In that example
(as with anything that will be served as a virtual directory or with an 
itemtype 1 or 7), content won't be displayed if you access your script
via floodgap proxy (and maybe others). In this case you will need to
<q>format</q> the output of your script.  Luckily this is very easy. For
instance, in the figlet.cgi example you will need to modify the <q>echo
	...</q> line this way:<br />
<code>
echo "i$i&lt;TAB&gt;&lt;TAB&gt;error.host&lt;TAB&gt;1"
</code>
<br />
where &lt;TAB&gt; is a tab character (you should already know this!)C
and <q>error.host</q> and <q>1</q> are, respectively, a fake server
and port number (you could also have written <q>fake</q> instead of
<q>error.host</q> and <q>300</q> instead of  <q>1</q>).
</p>

<div id="rcs_tag">$Id: gopher.html,v 1.24 2020/01/01 22:37:47 niro Exp $</div>