So at long last, you've got your server set up and responding to requests. How do you actually get content on Gopher? It honestly looks a lot more complicated than it is. Gopher server packages will serve whatever files exist in the publish directory of the server. The man page for gopherd gives the example of /home/gopher-data as a publish directory. Getting files on Gopher is as easy as throwing files and folders in that one. This will always be up-to-date because there's no web page or anything to update. The server package will simply generate the menu any time a Gopher client requests it with what it has on hand.
Sometimes, though, you want to customize your menu a little more. Depending on your server package, you could be looking at one of two ways to do it; gopherd and its ilk support .cap and .link files for customizing menus and generating links to other servers, while more modern servers customize their menus using gophermaps.
Table of contents
The traditional way: .cap and .link
.link files: for going to other servers
To explain the syntax of .cap and .link files (since they're the same format), let's start with the latter first. I want to remind you of the five parts of a Gopher menu selector:
| Itemtype | Display string (name) | Path on host | Host | Port on host |
|---|---|---|---|---|
0 |
About Somnolescent | 0/somnolescent.info |
gopher.somnolescent.net |
70 |
To make a link to another server, we'll need to feed gopherd these five bits of information, plus where to slot it in on a menu if desired. (The server will sort alphabetically otherwise.) gopherd automatically assumes any files whose names start with a dot (.) are link files and will open them up and parse their contents when it goes to generate the menu. That file should contain five lines, plus a Numb= field if a custom place on the menu is desired:
Name= Numb= Type= Port= Path= Host=
Thus, when a client requests a directory, gopherd will open that file up, build a selector out of the name, itemtype, path, port, and host given, and deliver it on that menu as if it was a local file sitting on your server. If I wanted to link to Floodgap's "Welcome to Gopherspace!" directory, I could make a page named, say, .fg_welcome (the name doesn't matter, but that's a fairly obvious one) and have these lines in it:
Name=Getting started with gopher, software, more (from gopher.floodgap.com) Numb=1 Type=1 Port=70 Path=1/gopher/ Host=gopher.floodgap.com
If you're linking to files on your own machine, you can use a plus sign (+) for the Port= and Host= fields. gopherd will simply fill in your server's host and port for those fields when it generates the menu. If you're looking for more uses of these .link files, I highly suggest reading the man page linked in the intro. Several uses are described, including links to WAIS and FTP servers and running shell scripts on the server itself.
.cap files: for customizing your own selectors
gopherd will make several assumptions about the files in the publish directory when generating a menu from its contents:
- All files/directories that start with a dot, or are named
etc,usr,bin,dev,coreare ignored or processed specially.- The title of each object presented to the client is the filename of the file/directory.
- Directories in the tree are served as Gopher directory objects.
- Text files are represented as Gopher text objects.
- Ulaw sound files are are represented as sound objects.
- Compressed files are assumed to be text, and have their titles changed to remove the
.Zextension.- Mail spool files are represented as directories. When the client attempts to view the mail-spool file, the Subject lines are presented as the title of each mail message within the file.
- Executable shell scripts are assumed to be of text object type. When the client requests to view the shell-script, the script is run, and the results sent to the client.
- Files that end with
.htmlare assumed to be WWW hypertext files. They are served up with typeh.- Files that end with
.srcare assumed to be WAIS searches. If the server has WAIS indexing compiled in, then these will show up as a search engine.
For customizing this, say to rearrange the menu or rename certain selectors, gopherd gives one of two examples. The first involves a directory called .cap inside the relevant directory on the menu. Files in this directory with the same name as one in the directory itself will be used to override gopherd's assumptions about the file, such as its type, the order in which it's sorted, and its name.
If you had a file called recipes.txt which was sorted sixth on a menu, and you wanted to extend its name out to "Banana Bread Recipes" and put it second on that menu, you'd make a .cap directory in the same directory as the one with recipes.txt in it. You'd then make a recipes.txt in that .cap directory and fill in the following lines:
Name=Banana Bread Recipes Numb=2
(You don't need all the fields when it's a .cap file, as the server already assumes it's local.)
Now, when gopherd builds a menu from that directory, it will name the recipes.txt selector "Banana Bread Recipes" instead, and slot it in much higher on the menu. It'll still link to the same file, of course.
gopherd's other method for customizing menus eschews the .cap directory and just involves making files whose names start with a dot. (Remember, gopherd doesn't serve these out.) These have the same structure as the previous files. So in our banana bread example, .recipes.txt (again, note the dot) could look like this:
Path=./recipes.txt Name=Banana Bread Recipes Numb=2
And get the same result.
The Bucktooth way: Gophermaps
Feeling the .link and .cap files were a bit long-winded, Cameron Kaiser developed a new format for customizing Gopher menus for his Bucktooth server package. These are called gophermaps. Gophermaps are simplified representations of menus that let you leave off some selector information to reduce typing. The server package then fills in the missing information when it sends a menu off to a client. Gophermaps are exclusive rather than inclusive, unlike gopherd. If you leave a file off a gophermap, it simply won't be listed on that menu. (If it's on the server, it'll still be accessible with the right URL.) gopherd lists near everything in the requested directory no matter what.
Gophermaps aren't needed to have a functional server in any capacity, but they've become canonical anyway. More server packages arguably support gophermaps than .cap and .link files these days. To make use of gophermaps, make a file called gophermap (exactly that, no extension) in the directory whose menu you want to customize. You'll need one for every directory you intend to customize.
Here's the gophermap of Somnolescent's root menu:
| Gophermap | Generated menu |
|---|---|
Somnolescent "The glow of the bulb will guide us all" -------------------------------------------------------------- 0About Somnolescent somnolescent.info 0The Somnolescent Manifesto manifesto.txt 1Who are the Somnolians? somnolians/ 1Somnolescent Recaps recaps/ The cult at a glance, who's responsible, and what we're up to hSomnolescent on the Web URL:/web/somnol_v3/ Many handmade sites and blogs to peek at... 1aphrodisiac aphrodisiac/ Clunky, catchy machine rock from your bedroom 1AutoSite autosite/ Static sites, simplified 1mari's Essays maris-essays/ Many thoughts, many words (all in Markdown) 1Pennyverse pennyverse/ Something strange in the seafoam 1Pituophis and Gophew pituophis/ Our homebrew Gopher search and serve solution (client too!) 1w2krepo on Gopher w2krepo/ Software to bring your Windows 2000 PC to life 7Search Somnolescent search/ Looking for something in particular? |
 |
The structure should become fairly obvious, provided you know the structure of a Gopher menu. Though all links on our menu point towards files on our own server, if you wanted to link to someone else's Gopher server, you'd simply write out the full selector, host and port included:
0An Examination of Some Claims in the Light of Scripture (on silentmessengers.org) assets/docs/dwe.txt silentmessengers.org 70
One bit to note is that lines that don't contain tabs (remember that Gopher selectors are tab-delineated) are parsed in gophermaps as informational selectors. These are lines of plain text that don't link anywhere and are merely used for decoration or relevant information to the menu. Most good clients these support these, while some older ones don't and either will treat them as regular selectors (annoying) or simply not display them. Therefore, I'd advise you to write your gophermaps with as few informational selectors as possible, only using them if seeing the menu without them would still make sense. Put any really relevant information (like a bio) in a text file and deliver it as a proper selector instead.
Gophermap enhancement #1: globbing
One enhancement over the basic concept of a gophermap is the ability to match many files in a folder using a single selector. This is called globbing, and most servers that support gophermaps can also support globbing. A glob selector looks near-identical to a normal selector, but with wildcards where you intend to match multiple files. For example, if you wanted to match every text file in a directory, you'd use this selector:
0*.txt
That's the itemtype each matched file will return as, the wildcard and extension for the display string, and then a tab so the server knows this is a selector. (Yes, I promise there's a tab there. Highlight if you don't believe me.) Nothing more is needed.
Somnolescent uses globbing in our w2krepo menus. Rather than write out a selector for each file in the directory, we use globbing to match all of them and save on having to edit the gophermap every time a new file gets added to the collection.
| Gophermap | Generated menu |
|---|---|
1<< Back to gopher.somnolescent.net / gopher.somnolescent.net 70 1< Back to w2krepo ../ w2krepo on Gopher Astraware -------------------------------------------------------------- ?* |
 |
Globbing is naturally very powerful, so you'll need to be careful how you use it. For example, you might simply want to match every file in a directory as we did, to bring back the original inclusive behavior of gopherd. You can do this if you simply use * as your wildcard, with no extension. Problem being, if you used a specific itemtype, every file regardless of type would be returned as that type. Directories would return as text files, images would return as text files—it'd be a mess.
Instead, use the question mark (?) itemtype, and the server will figure out the itemtype for each file matched by the glob for you:
?*
Gophermap enhancement #2: gophertags
The second gophermap enhancement, the gophertag, is only really relevant when paired with globbing. One drawback to globbing is you lose out on the ability to write custom display strings—all files display as their filename, which could be rather unfriendly all things considered. For directories, this drawback can be ameliorated with a file called gophertag in each directory, in the same fashion as the gophermap. gophertag doesn't have any special syntax to speak of, merely the nicer, readable name of that directory. When the directory's matched with a glob, the gophertag will be used for the display string.
Originally, our root menu was to feature globbing before I decided to use informational selectors to explain each of the menu items. Since the maris-essays/ directory would have a space in it, I couldn't simply rename it to a more friendly title; on glob, it'd get listed as maris-essays. A gophertag in that directory containing this text:
mariteaux's Essays
Would solve the problem, as when the directory gets matched by the glob selector, it would display as "mariteaux's Essays" instead.