One of the main advantages of Gopher over FTP is the ability to place a link to other Gopher servers (or other places on the same server) seamlessly so as to appear to be a part of the normal directory structure. This is accomplished through a special "link" file. I will be referring to the file used by the Windows NT Gopher Server "GopherS", but other Gopher Servers will use a similar scheme. In "GopherS", the server reads the actual file structure of your hard drive. Directories and files will appear to a Client exactly as they do on the portion of the hard drive you have made visible to GopherS. Within any of these directories you can insert a file named "link.gfr". "link.gfr" (other Servers will use different names for this file) will remain invisible to Gopher Clients, but the content of the file will be read as if it was a part of the directory. You can have only one link.gfr file per directory, but you can place a link.gfr file in any directory desired (no limit). The content of the file MUST be as follows: Numb= Name= Host= Port= Type= Path= Please note that the order of these names (Numb, Name, Host, etc.) must appear in the EXACT order as shown above (i.e., Numb is first, Host is third, Type is fifth, etc.). Note also that there is -no- "URL=" name as sometimes will appear in other documentation; as "URL=" is both NOT supported by many Server software programs (such as GopherS), and NOT supported by the majority of Gopher Clients or Browers acting as Gopher Clients (such as Microsoft Internet Explorer). An actual working link.gfr file might therefore look like this: Numb=1 Name=--> Welcome to my Gopher Server <-- Host=+ Port=+ Type=i Path=\About.txt # Numb=2 Name= Host=+ Port=+ Type=i Path=\About.txt # Numb=3 Name=All the Worlds Gophers Host=gopher.floodgap.com Port=70 Type=1 Path=/world # Numb=4 Name=Example.txt Host=gopher.nowhere.net Port=70 Type=0 Path=/foo/bar/example.txt And this is what the Client will see: --> Welcome to my Gopher Server <-- All the Worlds Gophers Example.txt =============== Interperetation =============== Each link pointer is defined by Numb, Name, Host, Port, Type, and Path. The "#" symbol is used to separate each of these links in link.gfr. It is good practice to out-of-habit always use the "#" symbol after "Path" at the end of EVERY link pointer, but it is not required to be added after the last link pointer (see number 4 in the above example). ---------- "Numb=" indicates the order in which a link pointer will appear to a Client. Please note that ALL links in link.gfr will appear BEFORE any physical files in the hard drives directory. This means that although you can list links in a non-alphabetical order, the actual files and sub-directories (if any) in the same directory can ONLY appear alphabetically, and only AFTER all of the pointers listed in link.gfr. Although you can change the order of a link pointers appearance just by changing its number (you can skip numbers without causing errors), it is recommended (for human readability) that the number order of the entries in link.gfr be in the order of their placement in link.gfr, and also be consecutive starting with number "1" (see the example above). ---------- "Name=" is the name you wish a file to appear to the Gopher Client as (essentially it is a alias for the file). Note how in number 4 in the above example, although the actual name of the file is all lower case (example.txt), the name that appears to the Client begins with an upper case "E" (Example.txt). If you do not include any text after "Name=", the Client will see what appears to be a blank line (see number 2 above). Be careful if you use this trick, as the symbol for the file type (IF the gopher client uses such a graphic) will appear to the left of the blank line. As this blank line could still be selectable in the Client, it is recommended that only "information" file types (Type "i") appear as blank lines. NOTE: It is good practice to ALWAYS name a file placed on a Gopher Server with a "file extension" (i.e.; .txt, .exe, .zip, etceteras). This is especially important for TEXT files, as many operating systems will use the extension to designate (beyond the Type 0), what kind of viewer to use to display the contents of the file. It is also EXTREMELY helpful to a HUMAN surfer to visually determine what kind of file it may be (such as a Macintosh *.hqx, Unix *.tar, etceteras) before they waste time downloading an un-useable file type. ---------- "Host=" is the name of the server that contains the item you are linking to. Use the fully qualified server name (as in number 3 and 4 in the above example). IF the link points to an item on the current server, then instead of typing the fully qualified name to the server you are already on, you may use the shorthand symbol of "+" (see above example number 1 and 2). ---------- "Port=" is the port the Gopher Server you are linking to is operating on. By convention, Gopher uses port 70 (but like any server software, it -could- be setup to use a different port). IF the link points to an item on the current server, then instead of typing the Port number you are already on, you may use the shorthand symbol of "+" (see above example number 1 and 2). WARNING: Some Client software (such as Mozilla and Internet Explorer) is poorly written, and will NOT recognize a Gopher server that is operating on a port -other- than Port 70! It is highly recommended therefore that you ALWAYS operate you Gopher Server through port 70. ---------- "Type=" is the file Type. All Gopher URLs include the file Type as a component of the path. You MUST define for the server what each of the Type symbols represent. By convention, the Gopher file Types are: 0 Plain text file 1 Directory 2 Search CSO server (i.e. a qi/ph index) 3 ERROR 4 BinHex-format file (i.e. a *.HQX file) 5 Binary archive file (i.e. a *.ZIP file) 6 UUencoded-format file 7 Search server (i.e. a WAIS index) 8 Telnet as any kind of terminal other than TN3270 9 Binary file (i.e. a *.EXE file) g GIF-format image file h HTML file I Any kind of image file other than GIF (i.e. a *.JPG file) i Informational text that is displayed (as if it was a normal file name), but does not NECESSARILY link to any actual file. s Any kind of sound file (i.e. a *.WAV file) T Telnet as a TN3270 terminal Note that the Type letters are CASE SENSITIVE (a legacy of Gophers UNIX origins). An unfortunate and very stupid result is the use of "I" and "i" to mean two different things! Many Clients use these Type indicators when choosing a proper symbol to place beside the file name. Three different examples of file Types appear in the above link.gfr example. Note that NOT all Clients (especially very old Clients) will recognize all these Types (ONLY Type 0 and Type 1 are guaranteed to be universally recognized). Although you can use any "Type=" label (including a rarely used, or even made-up label), the Client software will either use the Type you labeled the item as (the Client will use an internal or configurable external handler to manipulate the file based on Type), or try to translate the Type label into one it can understand (not much of an issue if for example you designated a *.ZIP file as a Type 9, but troublesome if for example a Binary file was handled as a Type 0). By default, "GopherS" maps all un-designated (or none) file extensions to Type 0. It is therefore very important that you map EVERY file extension you are storing on the Gopher Server to an appropriate Type number in the servers configuration control panel (not all that big a task, as it is good practice to keep all but a very few of the common file extensions Zipped-up inside Type 5 archive files). Note that even though the Type letters will give a broad indication of the kind of file it is, individual "reader" software may still not be able to handle the file (for example, ZIP, RAR and ARC would all be considered Type 5, but each require different software to de-archive). This is a legacy of Gopher originating as a "campus-wide" (rather than "international") protocol, where only a small selection of file formats were offered, which could be identified by Type letters alone. As such, it is now ALWAYS good proceedure to indicate the exact format of the file by including a standard 3 letter identifying extenstion. ---------- "Path=" is the full path to the item. The path always begins with the root of file structure opened to the Gopher Server. For example, if the root of the Gopher server was the directory "C:\Gopher\Root", and the item linked was on the directory path "C:\Gopher\Root\foo\bar.txt", then the path you would use would be "\foo\bar.txt". Note how I used the backslash (\) rather than the forward slash (/). This is because "GopherS" reads the file path in Windows/DOS format rather than Unix format. It is important to use the path structure used on the linked server (for example in the above example numbers 1 and 2 are items on the local Windows machine, while example numbers 3 and 4 are items on a remote Unix machine). Be careful also when referencing SOME Gopher servers, as they also include a Type number as a part of the path (you will see in their URL what appears to be a doubled Type number such as "00" or "11"). In such an instance, this number would appear dirctly after "Type=" ahead of the root slash (for example: 0/foo.txt, 1/, or 1/directoryname). Note also that a path may contain any URL legal character (including a SPACE and ? character). When writing out the full path in the link.gfr file, it is good practice to use the actual ASCII characters for the backslash (\), space ( ), and questionmark (?), rather than their HEX number equivalents (%5C, %20, and %3F respectively). Tip: Some Windows/DOS based Clients may have difficulty accessing a file item that has MORE than one period (.) in the file name. It is therefore recommended that a period only be used to separate the first part of the files' name from its "file extension". Also, if the item is a file that is intended for use on a machine that only supports the "8.3" file format (such as Pure DOS), then the file name (and in the case of a ZIP archive, ALL the files inside the archive) should also be limited to using ONLY the "8.3" file format (don't confuse the actual file name with the link pointers "Name=" field, as the "Name=" field is just an alias and can be any ASCII text, as in example number 4 above). Warning: Many Clients and Browsers (including Internet Explorer) are limited to a URL address length of no more than 2048 characters. It is also recommended that a Servers directory depth never exceed 8 levels. Some Gopher Servers require that the maximum PATH length for a file name not exceed 106 characters (the PATH in this case includes everything in the Gopher URL that comes after the root "slash" character, including the directory names, separating slash characters, and the actual file name). Be aware also that your Server OS and your backup system may have path limitations of their own (for example, windows limits paths to 256 characters, while DOS limits paths to only 64 characters). ================= Directory Headers ================= A "link.gfr" file can be used to add a "heading" to a directory. This is a distinct advantage over, say FTP, where all you get is a confusing list of files/directories. When making a heading, use the Information Type ("i"). Note that some Clients do NOT use a graphic next to the text (and worse, they make the text "clickable"), so special consideration must be given. A good way to clearly indicate that the text is indeed just text (and not a directory or other link), is to use "arrows" to bracket the text. Two dashes and a greaterthan/lesserthan symbol make for a good "arrow" (see number 1 in the above example). To further indicate that this text is a directory title, you can separate the line of text from the actual files/sub-directories by using a "blank" line of text (see number 2 in the above example). Notice how I actually use a real path in the "Path=" portion of the link pointer (see numbers 1 and 2 in the above example). Many Gopher server operators omit the path (or worse, they include a bogus path such as "\fake"). This is a bad practice, because some Clients (Microsoft Internet Explorer especially) consider this text "selectable/clickable", and if you do indeed click on this text, then you get an error message. A better solution (and a solution that has interesting creative possibilities) is to point the text to an "About.txt" file in the directory (an ASCII TEXT file is always a safe bet, as ALL Clients can handle it). This way, if they click on the text (assuming their Client supports "clicking" this text), then the content of the About.txt file is displayed (persons who are not able to "click" on an Information Type text line can still get the same information if they just open the "About.txt" file as normal). If you wanted to get fancy, you could even point to an item in another directory (or even an item residing on another Gopher server). Keep in mind that although you do not have to make a valid path on a "blank" text line, it is good practice (and a potential safeguard) to use the SAME path as you would for the line that contains the heading (see numbers 1 and 2 in the above example). ========== CAUTION: Do NOT use spaces in file names for files that are intended to be downloaded. Many non-unix computers cannot download files that contain spaces in the file name. For example DOS computers will truncate the file name as soon as it encounters a "space". Also some Gopher Clients have trouble handling files with spaces, mis-identify the file as intended to be read rather than downloaded. One way to still have descriptive names for files is to type the file name using the underscore character (i.e., "Write_the_name_like_this.txt"). WARNING: Gopher does not perform handshaking like some other Internet protocols. Once transfer is initiated, the server simply "serves" the file until it is done. Many Routers have a "time-out" feature, and they assume that because there is no longer any negotiation taking place, that the connection is "stale". After the time-out period, the Router will break the connection, causing any downloads still in progress to fail. To prevent this from occuring, deactivate the "time-out" feature on any Routers between your Server and the Internet.