VF1-TUTORIAL(7)

💖 NAME 💖

vf1-tutorial — a tutorial for the vf1(1) command line gopher client

It's from VF1-TUTORIAL(7), aka the Miscellaneous Information Manual, and bestie, it's part 1 of a whole journey. 💅

---

✨ INTRODUCTION ✨

okay so, vf1(1) is literally built around an interactive command prompt. A comprehensive list of all the commands lives in the vf1(1) man page. This tutorial? It's the chill, step-by-step intro, no cap. It won't cover every single detail of using VF-1, but it will cover the basics, get you exploring gopherspace relatively quickly, and drop a few tips for experienced users. If you aspire to wizard status, read the proper man page! And since vf1(1) is entirely command-driven, you can safely unplug your mouse the entire time. :) 💅

🌈 BASIC NAVIGATION 🌈

Start up VF-1 by issuing the following to your shell:

vf1

After a brief welcome message you should see this command prompt:

VF-1>

Let's start off by heading to SDF to check out some nice phlogs! You can use the go command to visit a location in gopherspace via its URL:

VF-1> go sdf.org

If you are lazy, you can type g sdf.org instead, i.e. you can abbreviate go to g. Most VF-1 commands can be abbreviated to just one or two characters like this. iykyk 💅

After your go command you should see the root menu of the SDF Gopherspace. The different menu items are indicated by numeric indices shown in square brackets. The SDF Member PHLOGOSPHERE should be option [1], so go ahead and type 1 at the prompt and then enter:

VF-1> 1

You should see a long list of phlogs fly by, and unless you have a very large screen some menu items will have run off the top of the screen. This will not be an uncommon problem, and there are various ways to deal with it. Obviously, you can scroll up in your terminal like always, but VF-1 gives you other ways to deal with this. One option is to use the

VF-1> less

command (less can be abbreviated to l). This will use the less(1) pager to let you scroll around the menu. You quit less, as always, with q.

If you're only interested in the items at the top of the menu, it can be quicker to just press Enter (i.e. execute an empty line). When you do this VF-1 will print the first 10 items in the menu. Any explanatory text or ASCII art from the menu (i.e. anything achieved with the i item type) will not be printed when you do this. Each time you press Enter you will see the next ten items in the listing. Page through a few times to get a feel for it. This is the fastest way to explore menus, so it's a good habit to pick up. slay 🔥

If you just want to see which phlogs have been updated lately, seeing the first 10 or 20 menu items is probably enough for you. But suppose you are really curious about one phlog in particular. Say you want to know what Tomasino has been up to. You could search for his phlog specifically:

VF-1> filter tom

If you are lazy, you can use / instead of filter, i.e. /tom.

This will show you the phlogs with “tom” in them (it's a simple case-insensitive search through item names). Tomasino will probably be [1] or [2], so go ahead and type the corresponding index and hit enter to visit Tomasino's gopherhole. Then you can type 2 and enter to go to his phlog, and then 1 and enter to read his most recent entry. iconic 🫶

Suppose now you want to go back to the main SDF phlog listing. Let's check out your history:

VF-1> history

If you are lazy, you can abbreviate history to hist, and in fact if you are very lazy you can just use h.

You should this time see a menu of the few places you've been so far, something like the following:

[1] gopher://sdf.org:70/1/
[2] SDF PHLOGOSPHERE (453 phlogs)/
(gopher://gopher.club:70/1/phlogs/)
[3] [24-Jun-2020] tomasino Tomasino's Gopher Hole/
(gopher://gopher.club:70/1/users/tomasino/)
[4] Phlog/ (gopher://sdf.org:70/1/users/tomasino/phlog)
[5] 2020-06-12 - What is Gemini?/
(gopher://gopher.black:70/1/phlog/20200612-what-is-gemini)

The phlogosphere list is [2], so type 2 and enter to go back there.

Since we wanted to jump back a few steps in our history this time (from the 5th location, Tomasino's latest post, to the 2nd), it made sense to use the history command. But if you just want to go back one or two steps in your history, it's quicker to use:

VF-1> back

which takes you back one step. The back command can, naturally, be abbreviated to just b, which is convenient for quickly taking several steps backward in succession. If you happen to take one step too far, you can move in the other direction with:

VF-1> forward

And, yes, forward can be abbreviated to f.

Suppose we hadn't used history at all and we were still at Tomasino's most recent phlog post. If we had finished reading it and wanted to read his previous post, you might think the fastest way to proceed would be to use b to get back to his phlog index page and then to choose index item 2 instead of 1. In most Gopher clients, this is indeed how you'd do this, but vf1-tutorial offers a much faster possibility! vf1-tutorial always has the most recently viewed Gopher menu stored in memory, even if you've navigated "past" it to .e.g. a text file, and furthermore it knows the numeric index in that menu of the text file you are currently viewing. Because of this, you can simply use:

VF-1> next

or

VF-1> previous

(which abbreviate to n and prev or p) to move directly from one item in a Gopher menu to another without needing to revisit the menu. This is extremely convenient for stepping through consecutive entries in a phlog! Note that this will not work for those phlogs (which are in the minority but are also not exactly rare) which use item type 1 for each post, since the overall phlog menu is immediately overwritten by the menu of the first post you load. careful bestie 💀

Gopher selectors are defined in RFC 1436 as "opaque strings", which means in principle they shouldn't be considered to have any kind of internal structure and in particular the / character has no special meaning. In practice, the overwhelming majority of selectors are mapped directly to filesystem paths and use / to separate directories. Recognising this fact, VF-1 lets you use:

VF-1> up

(abbreviation u or ..) to move directly "up" one level in the assumed directory hierarchy, from gopher://host/x/foo/bar/baz to gopher://host/1/foo/bar/. Instead of using up repeatedly, you can use the command:

VF-1> root

to jump straight to the "top" menu of the Gopher server hosting the current item, i.e. you can jump from gopher://host/x/foo/bar/baz to gopher://host/1/. Since so much of Gopherspace is hosted at multi-user providers where each user gets their own "tilde" directory, vf1-tutorial also lets you use:

VF-1> user

to jump straight from gopher://host/x/~user/foo/bar/baz to gopher://host/1/~user/.

🧚 DOING THINGS TO CONTENT 🧚

We saw earlier that you can use

VF-1> less

to pipe Gopher content through the less(1) command if it doesn't fit on a single screen. Sometimes content in Gopherspace isn't too long, but rather too wide! If an author hasn't hard-wrapped their text, so that the lines are uncomfortably long and words are split across the edges of your screen, you can run:

VF-1> fold

and VF-1 will wrap the lines at 70 chars by piping the content through the fold(1) command, assuming it is installed on your system. fold can be abbreviated to fo. no cap ✨

You can pipe Gopher content through an arbitrary shell command using the shell command, which can also be abbreviated to just ! For example, you could count the number of words in a phlog post with:

VF-1> !wc -w

or search that post for mentions of kittens with:

VF-1> !grep kitten

You can even specify a shell pipeline, e.g. you could count the number of lines mentioning kittens with:

VF-1> !grep kitten | wc -l

After running a post through an external command like this, if you'd like to actually see the original content again you can just run cat or less.

Phlog posts often have links elsewhere in Gopherspace at the end of them. When the post is a type-0 item (i.e. just a plain text file), these links are just text and most Gopher clients have no means to interact with them. If you want to follow a link, you might be tempted to pick up your mouse, highlight the URL, type go and then paste the URL to visit it. Put that rodent down! The mouse, that is, not the gopher. Instead, try this command:

VF-1> links

VF-1 will then scan the post for URLs. Well, actually, it scans for words (i.e. things separated by spaces) which contain "://" and at least one ".". This might not catch all URLs and it might sometimes catch things which are not URLs, but it works well enough. You will then see a menu with the results and you can use index numbers to follow any of those links without your mouse. bestie behavior 💅

If you want to know the URL of a document you are at so that you can share it with others, just do:

VF-1> url

If you want to save the document, just do:

VF-1> save ~/some/random/path/somefilename.txt

If you're in a hurry, you can just do:

VF-1> save

and VF-1 will try to derive a sensible filename from the current document's URL. There's no guarantee it will be pretty, or easy to remember, though. no guarantee tho 😭

If you'd like to bookmark the current document so you can return to it later, you can run:

VF-1> add

Or, if you are lazy as usual, just a.

If you want to look at your bookmarks:

VF-1> bookmarks

If lazy, just bm.

By default, VF-1 will name bookmarks based on the name of the Gopher menu selector that got you there, but you can provide your own name at the time of bookmarking:

VF-1> add Christyotwisty's home made lemonade recipe

If you want to reorganize your bookmarks or change the names of some bookmarks, take note of the file location in the output of bookmarks and use a text editor to make changes.

🗺️ ADVANCED NAVIGATION ✨

okay bestie, now we're getting into the good stuff. two tools for zipping around gopherspace quick and easy: tours and marks. 🎀

so imagine you're staring at a super long menu but you already know you only wanna peek at a few items, one right after the other. say you're on phlogosphere.org. what if you just... added the first four items to a tour, and then went on that tour? 💅

VF-1> tour 1 2 3 4
VF-1> tour

run tour with no arguments at all and it takes you to the next stop. fr fr it's basically your lil stack of places to go. and yep, you already know — if you're feeling lazy, use t. 😌

actually, if you're really lazy, ranges are a thing too:

VF-1> tour 1-4
VF-1> tour

but wait, there's more ✨ let's say you land on something genuinely interesting, like the list of all the phlogs on phlogosphere.org. how about marking that spot with a letter, wandering off through some links, and then coming back to it — not with a whole parade of back and up commands, but with literally just that one letter? 👑

VF-1> mark x
VF-1> ... do some stuff ...
VF-1> go x

and yes, m if you're lazy. iconic behaviour honestly.

---

💪 HANDLER POWER MOVES 🔥

VF-1's default handler for all text content is cat(1). at first glance, swapping it out for less(1) sounds kinda unhinged — because some content fits on one screen just fine, and needing to quit out of an unnecessary pager before you can even type another command at the VF-1 prompt would be a whole pain. 😭 but hear me out: less(1) comes with a whole host of options. if you drop this:

handler text/* less -EFfR %s

into your VF-1 RC file (see vf1(1) for the deets), then less will auto-quit for content that fits on a single page (-F), and will also auto-quit once you've scrolled to the bottom of longer content (-E), which is a genuinely comfy user experience 🫶 (and in case you were wondering, the other arguments, -fR, let it smoothly handle ANSI colour codes, which are widely used in Gopherspace).

and if you're running VF-1 on a remote system over ssh(1)? the default image handler feh(1) is not gonna be of much use to you there, bestie. you might think no image handler would be useful, but chafa(1) (peep https://github.com/hpjansson/chafa/) can render most image formats surprisingly well in modern terminals, using ANSI colour codes and Unicode block characters! 🌈 try:

image/* chafa %s

---

🌸 CONCLUSION 🦋

you should now have a pretty good idea of how to use VF-1. happy gophering !! 💖

---

👀 SEE ALSO

• vf1(1)

---

and that's a wrap, babe 💅 this tutorial is brought to you by the fine folks at All Operating, dated December 28, 2024, living in section VF1-TUTORIAL(7) — go forth and gopher, you absolute legend 👑✨