VF1-TUTORIAL(7)

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

INTRODUCTION
vf1(1) is built around an interactive command prompt. A comprehensive list of the available commands can be found in the vf1(1) man page. This tutorial will introduce some of the most important commands in an informal, step-by-step manner. The tutorial will not cover every detail of using VF-1, but it will cover the basics and get you exploring gopherspace relatively quickly, as well as provide a few tips for experienced users. Read the proper man page if you aspire to wizard status! Since vf1(1) is entirely command-driven, you can safely unplug your mouse the entire time you are using it. :)

BASIC NAVIGATION
Start up VF-1 by issuing the

    vf1

command to your shell. After a brief welcome message you should see the following 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.

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.

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.

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.

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.

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.

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.

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
Now let's look at two tools for quick and easy navigation through gopherspace, tours and marks.

Sometimes you're looking at a menu and it's very long but you know you want to look at few items, one after another. Assume you're looking at phlogosphere.org, for example. How about adding the first four items to a tour and then going on that tour?

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

Use the tour command without any arguments to go to the next stop. This is basically your stack of items to go to. And yes, you guessed it. Use t if you're feeling lazy.

Actually, if you're really lazy, you can use ranges, too:

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

But there's more. Let's say you're looking at something pretty interesting, like the list of all the phlogs on phlogosphere.org. How about marking this place with a letter, following some links, and then returning to this location not using a bunch of back and up commands but just that one letter?

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

And yes, m for the lazy.

HANDLER POWER MOVES
VF-1's default handler for all text content is cat(1). At first blush, the idea of replacing it with less(1) seems strange, because some content fits on one screen just fine and it would be a pain to need to quit out of an unecessary pager before being able to issue further commands to the VF-1 prompt. But less(1) comes with a whole host of options. If you put:

    handler text/* less -EFfR %s

into your VF-1 RC file (see vf1(1) for details), then less will automatically quit for content which fits on a single page ( -F ), and will automatically quit when you've scrolled to the bottom of longer content, too ( -E ), which provides quite a comfy user experience (in case you're wonering, the other arguments, -fR, allow for smooth handling of ANSII colour codes, widely used in Gopherspace).

If you use VF-1 on a remote system via ssh(1), the default image handler of feh(1) will not be of much use. You might think that no image handler will be of much use, but chafa(1) (see 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)