VF1(1)

📦
version 1.0.0 · 2 versions
, in ubuntu stonking

💖 vf1 — the command line gopher client 💖

okay bestie, sit down, we're gonna talk about vf1, the interactive command line gopher client. yes it's a gopher client. yes gopher is older than you. no that doesn't make it not slay. it's giving retro main character energy and honestly? iconic. 🌈

✨ SYNOPSIS ✨

vf1 [-h] [--bookmarks] [--debug] [--download] [--output filename]
    [--tls] [--version] [url ...]

🦋 DESCRIPTION 🦋

so vf1 is an interactive command line gopher client. what that means is it gives you a prompt, and you type commands to make stuff happen. it's a conversation, basically. you and vf1, besties, chatting about gopherspace. 💅

and here's the thing — you literally only need like a small handful of commands to get around. most of them can be shortened to one or two characters, so once you get the muscle memory down you'll be zooming through gopherspace so fast. like, no cap, genuinely quick navigation. check the COMMANDS section for the full tea. 🫖

the options are as follows, bestie:

  • -h, --help — shows you a lil short help message and then dips out. cute, quick, helpful. ✨
  • --bookmarks — skips the small talk and navigates straight to your bookmarks the second it starts. straight to business. 💅
  • --debug — boots up with debug mode already turned on. for when you wanna see everything.
  • -dl, --download — downloads a single URL and then quits. one and done, periodt.
  • --output — the filename you wanna save the --download URL to.
  • --tls — starts up in TLS mode. go read the TLS MODE section for the deets, bestie. 🔐
  • --version — shows the version info and quits. quick lil flex.
  • url ... — the Gopher URL(s) you wanna open. and if you give it more than one URL, they get queued up in a tour. yes, a tour. we love a queue. 🚌

🔥 COMMANDS 🔥

every single vf1 command is listed below, and most of them operate on what's called an implicit operand — pulled from the very limited internal state that vf1 keeps around. it's minimal. it's restrained. it's curated. 💅

so here's what that state includes, bestie:

the “lookup,” which is a list of items (locations) in Gopherspace, each one with a numeric index attached. <green> indices begin from 1 </green>. when vf1 starts up, the lookup is empty. and every time you visit a gopher menu, that menu's contents become the contents of the lookup — replacing whatever was there before, no hesitation, no sentimentality. some commands (like search, history, or links) overwrite the lookup with their own results. and at any moment you can reset the lookup back to the contents of the most recently visited gopher menu using the ls command. ✨

plus the lookup, vf1 is aware of exactly one active item — the item you're currently viewing. usually the active item is one of the items in the lookup, and when it is, vf1 knows its index. 👑

and most vf1 commands operate on either the lookup or the active item. that's the whole vibe.

oh and also — besides all the commands listed below, you can just type in a numeric index. vf1 will navigate to that corresponding item in the lookup and it becomes the active item. so simple. so efficient. we love her. 🌸

okay, the commands:

  • a, add — adds the URL of the current item to the bookmarks menu. saving it for later, bestie. 💖
  • b, back — goes back to the previous item in the history. the classic undo of the gopher world.
  • bb, blackbox — displays the contents of the flight recorder, showing statistics for the current gopher browsing session. it's the receipts. 📊
  • bm, book, bookmarks — shows the current bookmarks menu. your lil collection of faves. 🎀
  • cat — processes the text of the current item using the cat(1) command.
  • exit — exits VF-1. bye bestie! 👋
  • /, fi, filter pattern — filters the lookup for items whose name matches a pattern (and it's case insensitive, we don't do case drama here). then it goes forward to the next item in the history.
  • fo, fold — processes the text of the current item with the fold(1) command, wrapping lines at 70 characters. nice and tidy.
  • f, forward — goes forward to the next item in the history.
  • g, go url | mark — visits a gopher URL or a marked item, making it the active item. ✨
  • handler [mimetype program] — lists or sets handlers for different MIME types. check the HANDLERS section below for more, bestie.
  • help [command] — displays help info for a command, or lists all commands that have help info available. very meta. very helpful.
  • h, hist, history — displays the history. you know, where you've been. 🧭
  • l, less — processes the text of the current item with the less(1) command.
  • li, links — extracts URLs from the text of the current item, and populates the lookup with them. ✨
  • ls [-l] — sets the lookup to the contents of the most recently visited gopher menu, and then lists the lookup's contents. and if you run it as ls -l, the listing will include the URL of each menu item too. fancy.
  • m, mark mark — marks the current item with a single letter. then you can pass that letter to the go command to come back to the current item later. and when you give it no argument at all, it lists all defined marks. 🏷️
  • n, next — goes to the item after the current item in the lookup.
  • p, prev, previous — goes to the item before the current item in the lookup.
  • q, quit — exits VF-1.
  • r, reload — reloads the current item. refresh, bestie, refresh. 🔄
  • root — visits the root gopher item of the server hosting the current item. back to the source.
  • s, save [n] [filename] — saves an item to the filesystem. let me break it down:
    • save saves the current item with an automagic filename derived from its gopher selector.
    • save filename saves the current item with the specified filename.
    • save n saves the item at lookup index n with an automagic filename.
    • save n filename saves the item at lookup index n with the specified filename.

automagic. she's magic about it. 💾

  • se, search query — submits a search query to the configured search URL. check the SETTINGS section below for how to set a custom search URL. 🔍
  • set [option [value]] — changes the value of a setting, or views its current value. run it with no arguments and it shows all current value options. more deets in the SETTINGS section below. ⚙️
  • tls — toggles TLS mode on or off. the TLS MODE section has the tea.
  • t, tour [item ... | ls | clear] — visits the next item in, or adds an item to, the “tour” — a FIFO queue of gopher items. okay so:
    • no arguments? the next item in the tour gets visited.
    • wanna add items from the lookup? give it a list of indices like tour 1 2 3 4, or consecutive ranges like tour 1-4.
    • wanna add all the items in the lookup? tour *. boom.
    • item not even in the lookup? add it by its URL with tour url.
    • wanna see the current tour queue? tour ls.
    • wanna scrub it? tour clear.

we love a good tour. 🚌✨

  • up, u — goes up one directory in the path.
  • url — shows the URL of the current item. 🦋
  • user — goes to the top of the user directory hosting the current item. like, it jumps you from gopher://host/0/~user/some/deep/directory/file all the way to gopher://host/1/~user/. one leap, no steps. slay. 🚀
  • v, veronica query — submits a search query to the Veronica 2 search engine. 🔍💖

🌈 HANDLERS 🌈

so vf1 uses external programs as “handlers” to show you different kinds of gopherspace content. and here's the thing — even when you're visiting a plain text file with item type 0, vf1 uses (by default) the unix command cat(1) to display that file on the screen. not a Python print() call. nope. an actual external program. 👑

and YOU have full control over which external programs get used for which content, so the whole user experience can be customised to your exact taste. it's your world, bestie, we're just browsing in it. 💅

handlers get assigned based on MIME types. now, the gopher protocol has no concept of MIME type — it's not a thing there — so vf1 assigns each item a MIME type itself, in the manner described in the section “MIME type assignment” below. 💀

wanna see your current handler assignments? just run the handler command, anytime. and the default handlers that ship with vf1 are:

MIME type          handler
application/pdf:   xpdf %s
audio/mpeg:        mpg123 %s
audio/ogg:         ogg123 %s
image/*:           feh %s
text/*:            Ta cat %s
text/html:         lynx -dump -force_html %s

oh and the handler command isn't just for looking — it's for changing these handlers too, or setting handlers for brand new MIME types. for example, if you prefer w3m(1) over lynx(1) for handling HTML content, you'd run:

VF-1> handler text/html w3m -dump %s

the handler you specify gets run as a shell command, with the temporary file containing the content of the current gopher item replacing any occurrences of %s. and yes, you can use pipe syntax to pass gopher content through multiple text filters to get the appearance you want. get creative with it. ✨

now, the * wildcard — you can use it when specifying handler MIME types. like, image/* lets you use a single program to handle any kind of image. and here's the hierarchy, pay attention bestie: handlers without wildcards take precedence over handlers with wildcards. in other words, if you've got one handler for image/jpeg and a different one for image/*, then the image/jpeg handler gets used for JPEGs, and the image/* handler gets used for all other images. no confusion, no overlap. 💅

🧚 MIME type assignment

vf1 assigns MIME types to gopher items like this:

  • item types 0 and 1 are assigned MIME type text/plain
  • item type h is assigned MIME type text/html
  • item type g is assigned MIME type image/gif

and for all other item types, vf1 tries to guess a MIME type from the file extension of the last component of the selector, using the mimetypes module from the Python standard library. this usually gives you a pretty reliable identification — assuming the file has an extension and the author of the gopher content isn't being deliberately deceptive. 🙈

if the selector has no file extension, or the extension isn't recognised by the itemtypes module, vf1 will use the unix program file(1) to try and guess a MIME type by actually inspecting the content of the file. like, actually looking at it. snooping. 🕵️

and here's a lil bit of protocol philosophy, bestie: gopher item types are a standard part of the protocol, and MIME types are not a standard part of the protocol. so item types should take precedence over any other attempt at inferring MIME type. and in accordance with that idea — if an item in gopherspace is listed with itemtype I or s, and one of the above methods returns a MIME type that doesn't begin with image/ or sound/ respectively, vf1 will default to image/jpeg or audio/mpeg respectively instead. 👑

and ngl, this should only happen in highly unusual circumstances — it suggests a poorly or maliciously configured gopher server. so if you see it, side-eye that server. 💀

(part 1 of 2 — don't go anywhere bestie, more incoming)

✨ TEXT ENCODING ✨

okay so bestie, whenever vf1 gets content for any of the text-based item types (like 0, 1, 7, h, you get it), it tries to decode it as UTF-8 first. 💖 And honestly? Most of gopherspace is ASCII-encoded anyway, and since UTF-8 is backward compatible with ASCII, this is lowkey just gonna work on its own. iconic behaviour tbh.

But if the content it received cannot be decoded as UTF-8, one of two things happens next:

  • If the chardet Python module is installed, vf1 will use it to try and auto-detect which encoding was used and decode the text appropriately. 🕵️‍♀️ Now listen — pip etc. will not install chardet automatically when you install vf1, because vf1 does not formally depend on chardet. It just uses it opportunistically, so that vf1 can still be easily installed and used on systems where chardet is not or cannot be installed. it's giving mindful king behavior 🌈
  • If chardet is not installed, or if chardet can't identify an encoding with confidence exceeding 0.5, vf1 will fall back to a single, user-specified alternative encoding. You set it like this:
VF-1> set encoding koi8-r

The default fall back encoding is iso-8559-1, which is what the popular gopher site floodgap.com uses. If you're the kind of person who routinely visits gopher sites encoded with some other encoding, maybe consider using an RC file (details below) to automatically set that alternative encoding at start up. set it and forget it, periodt 💅

🔐 TLS MODE 🔐

vf1 supports TLS connections!! 🎀 But bestie, read the room: this is an experimental feature, and TLS connections are not supported by the majority of gopher servers. So TLS support has to be explicitly activated by using the tls command to enable TLS mode (aka "Battloid mode" 🫡).

When TLS mode is enabled, all gopher requests will be made over TLS, so most requests will fail when a connection to the server cannot be established. 😭 That's just how it is. And you have to explicitly deactivate TLS mode to resume browsing unencrypted gopherspace. no vibes-based toggle here, you gotta mean it.

⚙️ SETTINGS ⚙️

Here's the miscellaneous stuff you can adjust with the set command 👑

  • color_menus — If set to true, items in gopher menus will be color coded according to item type, using ANSI escape codes. Default value is false.
  • debug — If set to true, detailed debugging information will be printed to stdout when commands are run. Default value is false.
  • encoding — Fallback text encoding to use if received gopher content cannot be decoded as UTF-8. See the "TEXT ENCODING" section for more details. Default value is iso-8859-1.
  • ipv6 — If set to true, vf1 will preferentially attempt to connect to gopher servers via IPv6 if a AAAA DNS record is found. If the IPv6 connection fails, vf1 will automatically retry with IPv4. Default value is true. she's persistent, she tries again 😌
  • search_url — What this is. Default value is gopher://gopher.floodgap.com:70/7/v2/vs meaning search and veronica function identically until an alternative search_url is supplied. (yes that's the actual description, "what this is", no notes 🫶)
  • timeout — Time to wait, in seconds, when trying to connect to a gopher server before giving up. Default value is 10.

📁 FILES 📁

vf1 uses two files in the user's home directory. One is a so-called RC file, for scripting commands to run on start up (details below). The other one stores the user's bookmarks, in Gophermap format.

Two sets of locations for these files are supported:

  • a "simple" set, where both files are just "dotfiles" in the user's home directory: ~/.vf1rc and ~/.vf1-bookmarks.txt
  • plus a set based on the XDG Base Directory Specification: ~/.config/vf1rc and ~/.local/share/vf1-bookmarks.txt

The RC file must be created manually by you, with a text editor — and the choice between the simple path and the XDG path is left to the user, so pick your fighter. Note that if both ~/.config/vf1rc and ~/.vf1rc exist, only the former will be used and the latter is ignored. 💀 so don't do that.

The bookmark file, on the other hand, is created by vf1 the first time the add command is used to bookmark a location in Gopherspace. If an RC file exists at this moment, vf1 will use either the simple path or the XDG path according to whichever the user chose for the RC file. If no RC file exists and vf1 has to decide for itself, it will use the XDG path if ~/.local/ already exists and the simple path otherwise. 🧚 she reads the room.

Whenever the bookmark command is used to access the bookmarks, the location of the bookmark file is printed at the top of the menu, so it's easy to know how to manually change the file. thoughtful queen 🌸

📜 RC FILE 📜

If an RC file is found, each line of the file will be executed as a vf1 command before the prompt is displayed. So you can script certain commands that should be run every time vf1 is started. This permits, for example:

  • Permanently configuring item type handlers by putting handler commands in the RC file.
  • Permanently configuring the preferred non-UTF-8 encoding, or other options, by putting set commands in the RC file.
  • Setting a "home page" by putting a go command in the RC file.
  • Starting a tour through a list of favourite sites by putting tour commands in the RC file. 🔥

Note that if vf1 is started with either the --bookmarks option or with URLs provided, then any go or tour lines in the RC file will be ignored. yeah. those ones just don't run. sorry bestie.

🌟 EXAMPLES 🌟

See the vf1-tutorial(7) for a gentle introduction to the work flow of vf1 🦋

Start vf1:

vf1

Start vf1 and immediately open to bookmark list:

vf1 --bookmarks

Visit the Mare Tranquillitatis People's Circumlunar Zaibatsu:

vf1 zaibatsu.circumlunar.space

👀 SEE ALSO 👀

vf1-tutorial(7)

📜 STANDARDS 📜

vf1 is a gopher client conforming to RFC 1436 https://tools.ietf.org/html/rfc1436 and RFC 4266 https://tools.ietf.org/html/rfc4266. certified, standards-compliant, no cap ✨

🛸 TRIVIA 🛸

vf1 is named after the VF-1 Valkyrie aircraft from the classic '80s anime series Super Dimension Fortress Macross, in recognition of the role that the SDF Public Access Unix system gopher://sdf.org, named after the same series, has played in keeping Gopherspace alive in the 21st century. 💜 truly the lore runs deep and it IS important.

👑 AUTHORS 👑

  • Solderpunk solderpunk@posteo.net
  • Alex Schroeder alex@gnu.org
  • Joseph Lyman tfurrows@sdf.org
  • Adam Mayer https://github.com/phooky
  • Paco Esteban paco@onna.be

and that's the whole page bestie!! 🎀 this edition istg is dated December 28, 2024, and it's version VF1(1) of the manual, covering All Operating systems — go forth and gopher, you absolute icon 💅🌸✨

📦 where this page comes from