.Dd December 28, 2024
.Dt VF1-TUTORIAL 7
.Os All Operating Systems
.Sh NAME
.Nm vf1-tutorial
.Nd a tutorial for the
.Xr vf1 1
command line gopher client
.Sh INTRODUCTION
.Xr vf1 1
is built around an interactive command prompt.
A comprehensive list of the available commands can be found in the
.Xr vf1 1
man page.
This tutorial will introduce some of the most important commands in an informal,
step-by-step manner.  The tutorial will
.Em 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
.Xr vf1 1
is entirely command-driven, you can safely unplug your mouse the entire time
you are using it. :)
.Pp
.Sh BASIC NAVIGATION
Start up VF-1 by issuing the
.Pp
.Dl vf1
.Pp
command to your shell.
After a brief welcome message you should see the following command prompt:
.Pp
.Dl VF-1>
.Pp
Let's start off by heading to SDF to check out some nice phlogs!
You can use the
.Ic go
command to visit a location in gopherspace via its URL:
.Pp
.Dl VF-1> go sdf.org
.Pp
If you are lazy, you can type
.Ql g sdf.org
instead, i.e. you can abbreviate
.Ic go
to
.Ic g .
Most VF-1 commands can be abbreviated to just one or two characters like this.
.Pp
After your
.Ic 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
.Ic 1
at the prompt and then enter:
.Pp
.Dl VF-1> 1
.Pp
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
.Pp
.Dl VF-1> less
.Pp
command (
.Ic less
can be abbreviated to
.Ic l
).
This will use the
.Xr less 1
pager to let you scroll around the menu.  You quit less, as always, with q.
.Pp
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.
.Pp
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:
.Pp
.Dl VF-1> filter tom
.Pp
If you are lazy, you can use
.Ic /
instead of
.Ic filter ,
i.e.\&
.Ic /tom .
.Pp
This will show you the phlogs with
.Dq 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
.Ic 2
and enter to go to his phlog, and then
.Ic 1
and enter to read his most recent entry.
.Pp
Suppose now you want to go back to the main SDF phlog listing.
Let's check out your history:
.Pp
.Dl VF-1> history
.Pp
If you are lazy, you can abbreviate
.Ic history
to
.Ic hist ,
and in fact if you are very lazy you can just use
.Ic h .
.Pp
You should this time see a menu of the few places you've been so far,
something like the following:
.Pp
.Dl [1] gopher://sdf.org:70/1/
.Dl [2] SDF PHLOGOSPHERE (453 phlogs)/ (gopher://gopher.club:70/1/phlogs/)
.Dl [3] [24-Jun-2020]        tomasino  Tomasino's Gopher Hole/ (gopher://gopher.club:70/1/users/tomasino/)
.Dl [4] Phlog/ (gopher://sdf.org:70/1/users/tomasino/phlog)
.Dl [5] 2020-06-12 - What is Gemini?/ (gopher://gopher.black:70/1/phlog/20200612-what-is-gemini)
.Pp
The phlogosphere list is [2], so type
.Ic 2
and enter to go back there.
.Pp
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
.Ic history
command.  But if you just want to go back one or two steps in your
history, it's quicker to use:
.Pp
.Dl VF-1> back
.Pp
which takes you back one step.  The
.Ic back
command can, naturally, be abbreviated to just
.Ic 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:
.Pp
.Dl VF-1> forward
.Pp
And, yes,
.Ic forward
can be abbreviated to
.Ic f .
.Pp
Suppose we hadn't used
.Ic 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
.Ic b
to get back to his phlog index page and then to choose index item
.Ic 2
instead of
.Ic 1 .
In most Gopher clients, this is indeed how you'd do this, but
.Nm
offers a much faster possibility!
.Nm
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:
.Pp
.Dl VF-1> next
.Pp
or
.Pp
.Dl VF-1> previous
.Pp
(which abbreviate to
.Ic n
and
.Ic prev
or
.Ic 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.
.Pp
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:
.Pp
.Dl VF-1> up
.Pp
(abbreviation
.Ic u
or
.Ic .. )
to move directly "up" one level in the assumed directory hierarchy,
from
.Lk gopher://host/x/foo/bar/baz
to
.Lk gopher://host/1/foo/bar/ .
Instead of using
.Ic up
repeatedly, you can use the command:
.Pp
.Dl VF-1> root
.Pp
to jump straight to the "top" menu of the Gopher server hosting
the current item, i.e. you can jump from
.Lk gopher://host/x/foo/bar/baz
to
.Lk gopher://host/1/ .
Since so much of Gopherspace is hosted at multi-user providers where
each user gets their own "tilde" directory,
.Nm
also lets you use:
.Pp
.Dl VF-1> user
.Pp
to jump straight from
.Lk gopher://host/x/~user/foo/bar/baz
to
.Lk gopher://host/1/~user/ .
.Sh DOING THINGS TO CONTENT
.Pp
We saw earlier that you can use
.Pp
.Dl VF-1> less
.Pp
to pipe Gopher content through the
.Xr 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:
.Pp
.Dl VF-1> fold
.Pp
and VF-1 will wrap the lines at 70 chars by piping the content through
the
.Xr fold 1
command, assuming it is installed on your system.
.Ic fold
can be abbreviated to
.Ic fo .
.Pp
You can pipe Gopher content through an arbitrary shell command using the
.Ic shell
command, which can also be abbreviated to just
.Ic !
For example, you could count the number of words in a phlog post with:
.Pp
.Dl VF-1> !wc -w
.Pp
or search that post for mentions of kittens with:
.Pp
.Dl VF-1> !grep kitten
.Pp
You can even specify a shell pipeline, e.g. you could count the
number of lines mentioning kittens with:
.Pp
.Dl VF-1> !grep kitten | wc -l
.Pp
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
.Ic cat
or
.Ic less.
.Pp
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
.Ic go
and then paste the URL to visit it.
Put that rodent down!  The mouse, that is, not the gopher.  Instead,
try this command:
.Pp
.Dl VF-1> links
.Pp
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.
.Pp
If you want to know the URL of a document you are at so that you can
share it with others, just do:
.Pp
.Dl VF-1> url
.Pp
If you want to save the document, just do:
.Pp
.Dl VF-1> save ~/some/random/path/somefilename.txt
.Pp
If you're in a hurry, you can just do:
.Pp
.Dl VF-1> save
.Pp
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.
.Pp
If you'd like to bookmark the current document so you can return to it
later, you can run:
.Pp
.Dl VF-1> add
.Pp
Or, if you are lazy as usual, just
.Ic a .
.Pp
If you want to look at your bookmarks:
.Pp
.Dl VF-1> bookmarks
.Pp
If lazy, just
.Ic bm .
.Pp
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:
.Pp
.Dl VF-1> add Christyotwisty's home made lemonade recipe
.Pp
If you want to reorganize your bookmarks or change the names of some
bookmarks, take note of the file location in the output of
.Ic bookmarks
and use a text editor to make changes.
.Pp
.Sh ADVANCED NAVIGATION
Now let's look at two tools for quick and easy navigation through gopherspace,
tours and marks.
.Pp
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
.Lk phlogosphere.org ,
for example.
How about adding the first four items to a
.Ic tour
and then going
on that tour?
.Pp
.Bd -literal -offset indent
VF-1> tour 1 2 3 4
VF-1> tour
.Ed
.Pp
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
.Ic t
if you're feeling lazy.
.Pp
Actually, if you're really lazy, you can use ranges, too:
.Pp
.Bd -literal -offset indent
VF-1> tour 1-4
VF-1> tour
.Ed
.Pp
But there's more.
Let's say you're looking at something pretty interesting, like the list of all
the phlogs on
.Lk phlogosphere.org .
How about marking this place with a letter, following some links, and
then returning to this location not using a bunch of
.Ic back
and
.Ic up
commands but just that one letter?
.Pp
.Bd -literal -offset indent
VF-1> mark x
VF-1> ... do some stuff ...
VF-1> go x
.Ed
.Pp
And yes,
.Ic m
for the lazy.
.Pp
.Sh HANDLER POWER MOVES
VF-1's default handler for all text content is
.Xr cat 1 .
At first blush, the idea of replacing it with
.Xr 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
.Xr less 1
comes with a whole host of options.  If you put:
.Pp
.Dl handler text/* less -EFfR %s
.Pp
into your VF-1 RC file (see
.Xr vf1 1
for details), then less will automatically quit for content which fits
on a single page (
.Fl F
), and will automatically quit when you've scrolled to the bottom of
longer content, too (
.Fl E
), which provides quite a comfy user experience (in case you're
wonering, the other arguments,
.Fl fR ,
allow for smooth handling of ANSII colour codes, widely used in
Gopherspace).
.Pp
If you use VF-1 on a remote system via
.Xr ssh 1 ,
the default image handler of
.Xr feh 1
will not be of much use.  You might think that no image handler will
be of much use, but
.Xr chafa 1
(see
.Lk https://github.com/hpjansson/chafa/ )
can render most image formats surprisingly well in modern terminals
using ANSI colour codes and Unicode block characters!  Try:
.Pp
.Dl image/*   chafa %s
.Pp
.Sh CONCLUSION
You should now have a pretty good idea of how to use VF-1.
Happy gophering !!
.Sh SEE ALSO
.Xr vf1 1