Last modified: 2021-08-30 20:10

gc Explained

gc implements a lot of functions, which are outlined here. Most of them are non-standard, sometimes because I made modifications to the original Gopher specification and sometimes because things are not specified in the Gopher+ proposal.

UTF-8 charset

The original Gopher protocol assumes ASCII character set, 7bit and 8bit may work. (Were charsets like ISO-8859-1 and later utf for Internet text files already invented?) Of course, things have changed and I think utf-8 is a good choice.

Supported item types and MIME-types

gc understands most of the standard Gopher types.

Indicator Content
0 text document (text/plain)
1, 7 directories (application/gopher-menu)
4, 5, 6, 9 binary data (application/octet-stream)
I, g image (image/jpeg, image/gif)
h HTML document (text/html)
Z Gemini document (text/gemini)
i information item

However, for displaying items, gc converts Gopher type into MIME-types. This allows unifying processing of the supported server types and makes a difference when gc receives binary data. For such files gc consults the system's MIME-type database /etc/mime.types to get the file's content-type and /etc/mailcap to get a viewer to display the it. If no handler is configured gc asks for a filename to save the file.

The Z item type is not specified in the standards and I don't know if there is a proposol in the Gopher community for it.

Supported protocols

gc supports Gopher, Gopher+, HTTP/S and Gemini. Gopher and Gopher+ are set (usually) in an item's directory entry, e.g.:

0Title<tab>/path/to/item<tab>some.server<tab>port<tab>+

A trailing <tab>+ marks the server as Gopher+ capable.

HTTP/S and Gemini URLs are identified by a URL in the path field of the directory item:

0Title<tab>http://some.server/path/to/item

The URL may be preceded by URL:, which is simply stripped. gc triggers on the :// in the path element. When fetching files from HTTP or Gemini servers gc favours the MIME-type over the Gopher item type from the directory.

Gopher and Gopher+ addresses might also be specified as URL, e.g. on gc's command line or even in the path element. In this case the specifications from RFC 4266 apply, which are somewhat different from HTTP.

Gopher by HTTP

For gc a protocol is just a means to bring information (a file) from A to B and it implements as much HTTP as is required to fetch files from HTTP servers. This can be binary downloads, HTML files or Gopher(+) directories. To make things easy for Gopher administrators having only an HTTP server gc implements the following functions.

  1. The file extension is .ca and the server announces the file as text/plain (which is or should be the default if the extension isn't known by the server) gc reads that file as directory.

  2. Directories can be either Gopher0 or Gopher+ and gc detects the type from the first character (+ or not).

  3. To ease the task of moving content from a private gopher to a public HTTP server, gc accepts directory entries where the server and port fields are empty. In such cases gc inserts the directory's server and port.

  4. If gc finds item paths that do not start with a slash / it insert the Gopher directory's URL directory part.

  5. Paths of alternative views can be appended to the Gopher+-formatted entry in the +VIEWS block, e.g. text/html: <7k> gc-implementation-notes.html.

Notice that gc does not implement any magic to fetch the Gopher directory if the URL ends with a slash /. HTTP servers return HTML in that case and gc will read and display it. gc does not add a certain filename like gopher.ca to get the directory because it doesn't know if that's the right thing to do. That is, your Gopher root is not http://www.example.org/ but http://www.example.org/gopher.ca. You may choose whatever filename you like for Gopher directories as long as

  1. the extension is .ca, and
  2. the content-type is text/plain.

All this does not turn HTTP servers into good Gopher servers but is enough to fetch static Gopher files from them.

Documents containing links

Along with support for other protocols than Gopher comes the ability to extract links from documents. gc uses helpers for that, which need to be installed. (gmi2text and md2text are distributed with gc.) The supported content-types and helpers are

File Type Helper
text/gemini gmi2text
text/html lynx
text/markdown md2text

The links are numbered if the reformatted version of the documents. Use the ref command to follow one of the links:

ref [num]

opens the numbered link num from the document. If num is missing gc lists all references it has found in the file.

Navigational links

For Gopher+ directories gc reads the Relation from the +ADMIN-block to see if there are any files with a special relation to the directory.

+ADMIN:
 Admin: ...
 Mod-Date: ...
 Relation: contents

gc takes that information and make the files available with the shortcut command :relation. E.g., :content would display the document with the contents relations. Relation names may be given shortened as other commands too. Only as much letters must be present to identify the relation. In the example above :c might be enough to display the contents page.

The available relations are listed below the directory and in any item's Gopher+ information with the plus command.

In addition to named relations, gc computes a list of all files that

and creates a prev-next list of files in the order as they appear in the directory. The prev-next documents have the relations first, prev, next and last. They are not identical to the corresponding entries in the +RELATED: block (if any). These are server provided and currently ignored by gc. The respective files can be opened by choosing the link number from the plus command.

Most of the navigational links described are also offered in the context navigation, see below.

(You find a third set of navigation links in the HTML files. These links are created by the Markdown translator.)

Server provided links

Gopher+ servers might add links to files that can't carry them on their own in the +LINKS block. Such links are listed as part of an item's Gopher+ information with plus and can be followed by entering the respective link number.

The links command lists only the available links of an item, if available.

Autoloading documents

gc supports something that could be described as "homepage of a Gopher directory". It is a file that is automatically loaded when gc retrieves a directory from a server. The document is loaded "on top" of the directory as if the user would have opened it and the back command .. displays the directory. The idea is that this document provides information, which would have otherwise displayed as info items (type i) in the directory.

If the option is enabled gc scans the directory Gopher+ information if it contains an item that has a Relation header in an +ADMIN block set to autoload (multiple comma-separated values are accepted).

+ADMIN:
 Administrator: gophermeister@example.org
 Mod-Date: Thu, 12 Aug 2021 18:04:01 +0200 <20210812180401>
 Relation: home, autoload

If no Gopher+ information is available (when talking to Gopher servers) gc scans the item pathnames.

(^|-)(readme|home|about|welcome)([-.]|$)

it is automatically loaded.

The autoload function is optional and must be enabled with either the -e al command line option (al is the option's key) or from within gc by the enable al command. disable al turns autoloading off.

Context navigator

The context navigator is another optional feature. gc tries to support the user's navigation by

Not all items have the same amount of context navigation and for the user it's not obvious what is available and what not. Whenever a document is displayed the context navigator looks what is there and displays it in a single line. Each option is indicated by one of the following characters:

Char Displays
F first document
P prev document
N next document
L last document
H directory's home page
I directory's index page
C directory's contents page
: current directory listing
# the current document
+ document's Gopher+ information
> document's +LINKS section
R document's references (hyperlinks)

Entering on of the available characters (letters in lowercase) converts it to the corresponding command. Other commands can be entered as well.

The context navigation option has the key pnx and can be enabled with the -e pnx option or enable pnx command.

File uploads

gc supports uploading file and editing text files. I added this because I have the need not only to read file by Gopher but also to add or correct information while I'm in Gopher. Of course, this needs a compatible server and the server has to care about authorisation (in short: restrict on client IP basis). gc uses Gopher+ requests with +PUT in the plus field to indicate that the data in the request should go to the addressed file.

edit num

gets the item num from the server and loads it into vi. When you have finished editing it and the editor's exit code is 0 gc uploads the file to the server and asks if you want to continue editing.

Opening new sessions

Some of gc's commands accept a + in the item parameter. This opens a new shell running gc displaying that item. When running in an X-session then a new shell window is opened and can be used in parallel. Commands that can open a new window are

Command Opens
dup the current item
n+ link n from the current context
:n+ directory item n
:name+ related item name
edit [n]+ item n in the editor

If no X-Session is detected (by checking environment variable DISPLAY) gc opens a sub shell and suspends the current session.