Ubuntu Manpage: vf1 — command line gopher client

NAME

       vf1 — command line gopher client

SYNOPSIS

       vf1 [-h] [--bookmarks] [--debug] [--tls] [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.

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

       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. Go forward to the next item in the history.

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

fo, 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 [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 pattern
Search the lookup (case insensitive).

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

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/*:            Ta 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 activatd by using the 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 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.

       timeout
               Time to wait, in seconds, when trying to connect to a gopher server before  giving  up.   Default
               value is 10.

FILES

       ~/.vf1-bookmarks.txt  This  file  stores gopher bookmarks, in a simple gophermap format (without hosts or
                             ports).  Use add to add the current URL to the bookmark list.
       ~/.config/vf1/vf1rc
       ~/.config/.vf1rc
       ~/.vf1rc              Upon startup, vf1 will search for a file with one of these names,  a  so-called  RC
                             file  (see  below).The  names  are listed above in order of preference and vf1 will
                             stop after the first one it finds, e.g. if both ~/.config/vf1/vf1rc and a  ~/.vf1rc
                             exist then then ~/.vf1rc will be ignored.

   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.

EXAMPLES

       See the vf1-turorial(7) for a comprehensive introduction to the work flow of vf1

       Start vf1:

             vf1

       Start vf1 and immediately open to bookmark list:

             vf1 --bookmarks

       Visit the zaibatsu:

             vf1 zaibatsu.circumlunar.space

STANDARDS

       vf1 is a gopher client conforming to RFC 1436 ⟨https://tools.ietf.org/html/rfc1436⟩.

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@sdf.org⟩
       Alex Schroeder ⟨alex@gnu.org⟩
       Joseph Lyman ⟨tfurrows@sdf.org⟩
       Adam Mayer ⟨https://github.com/phooky⟩
       Paco Esteban ⟨paco@onna.be⟩

All Operating                                    August 31, 2019                                          VF1(1)