VF1(1)

NAME
vf1 - command line gopher client

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

DESCRIPTION
vf1 is an interactive command line gopher client. It presents a prompt to the user, who can then enter commands to perform actions.

Only a small number of commands are needed to get around, and most of them can be abbreviated to one or two chars, so with practice very quick navigation of gopherspace is possible. See the COMMANDS section for more details.

The options are as follows:

-h, --help
    Display a short help message and exit.

--bookmarks
    Immediately navigate to bookmarks upon starting.

--debug
    Start with debug mode enabled.

-dl, --download
    Download a single URL and quit.

--output
    Filename to save --download URL to.

--tls
    Start in TLS mode. See the TLS MODE section for more details.

--version
    Display version information and quit.

url ...
    The Gopher URL(s) to open. If more than one URL is provided, these are queued in a tour.

COMMANDS

All vf1 commands are listed below. Most commands operate on an implicit operand from the very limited internal state which vf1 maintains.

This state includes the “lookup,” which is a list of items (locations) in Gopherspace with numeric indices attached. Indices begin from 1. Upon startup, the lookup is empty. Whenever a gopher menu is visited, the contents of that menu become the contents of the lookup, replacing any previous contents. Some commands, such as search, history, or links overwrite the lookup with their results. At any time, the lookup can be reset to the contents of the most recently visited gopher menu with the ls command.

In addition to the lookup, vf1 is aware of exactly one active item (the item the user is currently viewing). Usually, the active item is one of the items in the lookup, and if so vf1 knows its index.

Most vf1 commands operate on either the lookup, or the active item.

In addition to the commands listed below, users can enter a numeric index. vf1 will then navigate to the corresponding item in the lookup, and that item will become the active item.

a, add
    Add the URL of the current item to the bookmarks menu.

b, back
    Go back to the previous item in the history.

bb, blackbox
    Display contents of flight recorder, showing statistics for the current gopher browsing session.

bm, book, bookmarks
    Show the current bookmarks menu.

cat Process the text of the current item with the cat(1) command.

exit
    Exit VF-1.

/, fi, filter pattern
    Filter lookup for items whose name matches a pattern (case insensitive). Go forward to the next item in the history.

fo, fold
    Process the text of the current item with the fold(1) command, wrapping lines at 70 characters.

f, forward
    Go forward to the next item in the history.

g, go url | mark
    Visit a gopher URL or marked item, making it the active item.

handler [mimetype program]
    List or set handlers for different MIME types. See HANDLERS section below for more details.

help [command]
    Display help information for a command, or list all commands with help information available.

h, hist, history
    Display the history.

l, less
    Process the text of the current item with the less(1) command.

li, links
    Extract URLs from the text of the current item, and populate the lookup with them.

ls [-l]
    Set the lookup to the contents of the most recently visited gopher menu and then list the lookup's contents. If invoked as ls -l the listing will include the URL of each menu item.

m, mark mark
    Mark the current item with a single letter. This letter can then be passed to the go command to return to the current item later. Lists all defined marks when no argument is given.

n, next
    Go to the item which is after the current item in the lookup.

p, prev, previous
    Go to the item which is before the current item in the lookup.

q, quit
    Exit VF-1.

r, reload
    Reload the current item.

root
    Visit the root gopher item of the server hosting the current item.

s, save [n] [filename]
    Save an item to the filesystem. 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.

se, search query
    Submit a search query to the configured search URL. See the SETTINGS section below for details on setting a custom search URL.

set [option [value]]
    Change the value of a setting, or view its current value. Shows all current value options if no arguments are given. See the SETTINGS section below for more details.

tls Toggle TLS mode on or off. See the TLS MODE section for more details.

t, tour [item ... | ls | clear]
    Visit the next item in, or add an item to, the “tour” - a FIFO queue of gopher items. If no arguments are provided, the next item in the tour is visited. Items from the lookup can be added with a list of indices like tour 1 2 3 4, or consecutive ranges like tour 1-4. All items in the lookup can be added with tour *. Items not in the lookup can be added by their URL with tour url. The current tour queue can be listed with tour ls and scrubbed with tour clear.

up, u
    Go up one directory in the path.

url Show the URL of the current item.

user
    Go to the top of the user directory hosting the current item, i.e. jump from gopher://host/0/~user/some/deep/directory/file to gopher://host/1/~user/.

v, veronica query
    Submit a search query to the Veronica 2 search engine.

HANDLERS

vf1 uses external programs as “handlers” to present different gopherspace content to the user. Even when 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, rather than using a Python print() call. Users have full control over which external programs are used for different content, so the user experience can be customised to taste.

Handlers are assigned on the basis of MIME types. The gopher protocol has no concept of MIME type, so vf1 assigns each item a MIME type itself in the manner described in the section MIME type assignment below.

A list of the current handler assignments can be viewed at any time by running the handler command. 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/*: | cat %s
text/html: | lynx -dump -force_html %s

The handler command can be used to change these handlers, or set handlers for new MIME types. For example, users who prefer w3m(1) over lynx(1) for handling HTML content could run:

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

The specified handler will be run as a shell command, with the temporary file containing the content of the current gopher item replacing any occurrences of %s. Pipe syntax can be used to pass gopher content through multiple text filters to achieve the desired appearance.

The ‘*’ wildcard can be used when specifying handler MIME types, e.g. ‘image/*’ allows using a single program to handle any kind of image. Handlers without wildcards take precedence over handlers with wildcards. In other words, if one handler is specified for ‘image/jpeg’ and a different handler for ‘image/*’, the ‘image/jpeg’ handler will be used for JPEGs and the ‘image/*’ handler will be used for all other images.

  MIME type assignment

vf1 assigns MIME types to gopher items as follows:

•   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’

For all other item types, vf1 attempts 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 results in a reliable identification assuming the file has an extension and the author of the gopher content is not being deliberately deceptive.

If the selector has no file extension, or the extension is not recognised by the ‘itemtypes’ module, vf1 will use the unix program file(1) to attempt to guess a MIME type by actually inspecting the content of the file.

In accordance with the idea that gopher item types, which are a standard part of the protocol, should take precedence over any other attempt at inferring MIME type, which is not a standard part of the protocol, if an item in gopherspace is listed with itemtype ‘I’ or ‘s’ and one of the above methods returns a MIME type which does not begin with ‘image/’ or ‘sound/’ respectively, vf1 will default to ‘image/jpeg’ or ‘audio/mpeg’ respectively. This should only happen in highly unusual circumstances and suggests a poorly or maliciously configured gopher server.

TEXT ENCODING

vf1 attempts to decode the content received for any text-based item types (e.g. 0, 1, 7, h) as UTF-8. Most content in gopherspace is ASCII-encoded, and since UTF-8 is backward compatible with ASCII, this will generally “just work”. If the received content cannot be decoded as UTF-8, one of two possible things will happen:

If the ‘chardet’ Python module is installed, vf1 will use it to attempt to automatically detect the encoding used and decode the text appropriately. Note that pip etc. will not install ‘chardet’ automatically when installing vf1, as vf1 does not formally depend on ‘chardet’. It uses it opportunistically, so that it can still be easily installed and used on systems where ‘chardet’ is not or cannot be installed.

If ‘chardet’ is not installed, or if ‘chardet’ cannot identify an encoding with confidence exceeding 0.5, vf1 will attempt to fall back to a single, user-specified alternative encoding. This encoding can be set as follows:

    VF-1> set encoding koi8-r

The default fall back encoding is iso-8559-1, which is used by the popular gopher site floodgap.com. Users who routinely visit gopher sites encoded with some other encoding may consider using an RC file (see below) to automatically set the alternative encoding at start up.

TLS MODE
vf1 supports TLS connections. This is an experimental feature, and TLS connections are not supported by the majority of gopher servers. As such, TLS support must 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. TLS mode must be explicitly deactivated to resume browsing unencrypted gopherspace.

SETTINGS
The following miscellaneous settings can be adjusted 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.

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.

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 (see below). The other 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 the user with a text editor, and the choice between the simple path and the XDG path is left to the user. Note that if both ~/.config/vf1rc and ~/.vf1rc exist, only the former will be used and the latter is ignored.

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. 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.

  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.This allows users to 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.

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)

•   mimetypes: https://docs.python.org/3.5/library/mimetypes.html

•   chardet: https://pypi.python.org/pypi/chardet

•   https://specifications.freedesktop.org/basedir-spec/latest/

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>.

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.

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>