vf1.1

.Dd June 25, 2019 
.Dt VF1 1
.Os All Operating Systems
.Sh NAME
.Nm vf1
.Nd command line gopher client
.Sh SYNOPSIS
.Nm
.Op Fl h
.Op Fl \-bookmarks
.Op Fl \-debug
.Op Fl \-tls
.Op Ar url ...
.Sh DESCRIPTION
.Nm
is an interactive command line gopher client.
It presents a prompt to the user, who can then enter commands to perform
actions.
.Pp
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
.Sx COMMANDS
section for more details.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl h , \-help
Display a short help message and exit.
.It Fl \-bookmarks
Immediately navigate to bookmarks upon starting.
.It Fl \-debug
Start with debug mode enabled.
.It Fl \-tls
Start in TLS mode.
See the
.Sx TLS MODE
section for more details.
.It Ar url ...
The Gopher URL(s) to open.
If more than one URL is provided, these are queued in a
.Ic tour .
.El
.Pp
.Sh COMMANDS
.Pp
All
.Nm
commands are listed below.
Most commands operate on an implicit operand from the very limited internal
state which
.Nm
maintains.
.Pp
This state includes the
.Dq 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
.Ic search ,
.Ic history ,
or
.Ic 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
.Ic ls
command.
.Pp
In addition to the lookup,
.Nm
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
.Nm
knows its index.
.Pp
Most
.Nm
commands operate on either the lookup, or the active item.
.Pp
In addition to the commands listed below, users can enter a numeric index.
.Nm
will then navigate to the corresponding item in the lookup, and that item will
become the active item.
.Pp
.Bl -tag -width Ds
.It Ic a , add
Add the URL of the current item to the bookmarks menu.
.It Ic b , back
Go back to the previous item in the history.
.It Ic bb , blackbox
Display contents of flight recorder, showing statistics for the current gopher
browsing session.
.It Ic bm , book , bookmarks
Show the current bookmarks menu.
.It Ic cat
Process the text of the current item with the
.Xr cat 1
command.
.It Ic exit
Exit VF-1.
Go forward to the next item in the history.
.It Ic f , fold
Process the text of the current item with the
.Xr fold 1
command, wrapping lines at 70 characters.
.It Ic fo , forward
Go forward to the next item in the history.
.It Ic g , go Ar url | mark
Visit a gopher URL or marked item, making it the active item.
.It Ic handler Op Ar mimetype Ar program
List or set handlers for different MIME types.
See
.Sx HANDLERS
section below for more details.
.It Ic help Op Ar command
Display help information for a command, or list all commands with help
information available.
.It Ic h , hist , history
Display the history.
.It Ic l , less
Process the text of the current item with the
.Xr less 1
command.
.It Ic li , links
Extract URLs from the text of the current item, and populate the lookup with
them.
.It Ic ls Op -l
Set the lookup to the contents of the most recently visited gopher menu and
then list the lookup's contents.
If invoked as
.Ic ls -l
the listing will include the URL of each menu item.
.It Ic m , mark Op Ar mark
Mark the current item with a single letter.
This letter can then be passed to the
.Ic go
command to return to the current item later.
Lists all defined marks when no argument is given.
.It Ic n , next
Go to the item which is after the current item in the lookup.
.It Ic p , prev, previous
Go to the item which is before the current item in the lookup.
.It Ic q , quit
Exit VF-1.
.It Ic r , reload
Reload the current item.
.It Ic root
Visit the root gopher item of the server hosting the current item.
.It Ic s , save Op Ar filename
Save an item to the filesystem.
.Ic save
saves the current item with an automagic filename derived from its gopher
selector.
.Ic save Cm filename
saves the current item with the specified filename.
.Ic save Cm n
saves the item at lookup index n with an automagic filename.
.Ic save Cm n Cm filename
saves the item at lookup index n with the specified filename.
.It Ic / , se , search Ar pattern
Search the lookup (case insensitive).
.It Ic set Op Ar option Ar value
Change the value of a setting, or view its current value.
Shows all current value options if no arguments are given.
See the
.Sx SETTINGS
section below for more details.
.It Ic tls
Toggle TLS mode on or off.
See the
.Sx TLS MODE
section for more details.
.It Ic t , tour Op Ar item ...
Visit the next item in, or add an item to, the
.Dq 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
.Ic tour Cm "1 2 3 4",
or consecutive ranges like
.Ic tour Cm 1-4 .
All items in the lookup can be added with
.Ic tour Cm * .
Items not in the lookup can be added by their URL with
.Ic tour Ar url .
The current tour queue can be listed with
.Ic tour Cm ls
and scrubbed with
.Ic tour Cm clear .
.It Ic up , Ic u
Go up one directory in the path.
.It Ic url
Show the URL of the current item.
.It Ic v , veronica Op Ar query
Submit a search query to the Veronica 2 search engine.
.El
.Sh HANDLERS
.Pp
.Nm
uses external programs as
.Dq handlers
to present different gopherspace content to the user.
Even when visiting a plain text file with item type 0,
.Nm
uses (by
default) the unix command
.Xr cat 1
to display that file on the screen, rather than using a Python
.Fn print
call.
Users have full control over which external programs are used for different
content, so the user experience can be customised to taste.
.Pp
Handlers are assigned on the basis of MIME types.
The gopher protocol has no concept of MIME type, so
.Nm
assigns each item a MIME
type itself in the manner described in the section
.Sx MIME type assignment
below.
.Pp
A list of the current handler assignments can be viewed at any time by running
the
.Ic handler
command.
The default handlers that ship with
.Nm
are:
.Bl -column -offset indent "application/pdf" "lynx -dump -force_html %s"
.It Sy MIME type          Ta Sy handler
.It application/pdf:    Ta xpdf %s
.It audio/mpeg:         Ta mpg123 %s
.It audio/ogg:          Ta ogg123 %s
.It image/*:            Ta feh %s
.It text/*:         	Ta cat %s
.It text/html:          Ta lynx -dump -force_html %s
.El
.Pp
The
.Ic handler
command can be used to change these handlers, or set handlers for new MIME
types.
For example, users who prefer
.Xr w3m 1
over
.Xr lynx 1
for handling HTML content could run:
.Pp
.Dl VF-1> handler text/html w3m -dump %s
.Pp
The specified handler will be run as a shell command, with the temporary file
containing the content of the current gopher item replacing any occurences of
%s.
Pipe syntax can be used to pass gopher content through multiple text
filters to achieve the desired appearance.
.Pp
The
.Ql *
wildcard can be used when specifying handler MIME types, e.g.
.Ql 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
.Ql image/jpeg
and a different handler for
.Ql image/* ,
the
.Ql image/jpeg
handler will be used for JPEGs and the
.Ql image/*
handler will be used for all other images.
.Pp
.Ss MIME type assignment
.Pp
.Nm
assigns MIME types to gopher items as follows:
.Bl -bullet
.It
Item types 0 and 1 are assigned MIME type
.Ql text/plain
.It
Item type h is assigned MIME type
.Ql text/html
.It
Item type g is assigned MIME type
.Ql image/gif
.El
.Pp
For all other item types,
.Nm
attempts to guess a MIME type from the file
extension of the last component of the selector, using the
.Ql 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.
.Pp
If the selector has no file extension, or the extension is not
recognised by the
.Ql itemtypes
module,
.Nm
will use the unix program
.Xr file 1
to attempt to guess a MIME type by actually inspecting the content of
the file.
.Pp
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
.Ql I
or
.Ql s
and one of the above methods returns a MIME type which does not begin
with
.Ql image/
or
.Ql sound/
respectively,
.Nm
will default to
.Ql image/jpeg
or
.Ql audio/mpeg
respectively.
This should only happen in highly unusual circumstances and suggests a poorly
or maliciously configured gopher server.
.Sh TEXT ENCODING
.Pp
.Nm
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
.Dq just work .
If the received content
.Em cannot
be decoded as UTF-8, one of two possible things will happen:
.Pp
If the
.Ql chardet
Python module is installed,
.Nm
will use it to attempt to
automatically detect the encoding used and decode the text appropriately.
Note that pip etc. will not install
.Ql chardet
automatically when installing
.Nm ,
as
.Nm
does not formally depend on
.Ql chardet .
It uses it opportunistically, so that it can still be easily installed
and used on systems where
.Ql chardet
is not or cannot be installed.
.Pp
If
.Ql chardet
is not installed, or if
.Ql chardet
cannot identify an encoding with confidence exceeding 0.5,
.Nm
will attempt to
fall back to a single, user-specified alternative encoding.
This encoding can be set as follows:
.Pp
.Dl VF-1> set encoding koi8-r
.Pp
The default fall back encoding is iso-8559-1, which is used by the
popular gopher site
.Lk 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.
.Sh TLS MODE
.Nm
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
.lc tls
command to enable TLS mode (aka "Battloid mode").
When TLS mode is enabled,
.Em 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.
.Sh SETTINGS
The following miscellaneous settings can be adjusted with the
.lc set
command.
.Bl -tag -width Ds
.It Ic 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.
.It Ic debug
If set to true, detailed debugging information will be printed to stdout when
commands are run.
Default value is false.
.It Ic encoding
Fallback text encoding to use if received gopher content cannot be decoded as
UTF-8.
See the
.Sx TEXT ENCODING
section for more details.
Default value is iso-8859-1.
.It Ic ipv6
If set to true,
.Nm
will preferentially attempt to connect to gopher servers via IPv6 if a AAAA DNS
record is found.
If the IPv6 connection fails,
.Nm
will automatically retry with IPv4.
Default value is true.
.It Ic timeout
Time to wait, in seconds, when trying to connect to a gopher server before
giving up.
Default value is 10.
.El
.Sh FILES
.\" the longest path name appearing in the list
.Bl -tag -width ~/.vf1-bookmarks.txt -compact
.It Pa ~/.vf1-bookmarks.txt
This file stores gopher bookmarks, in a simple gophermap format (without hosts
or ports).
Use
.Ic add
to add the current URL to the bookmark list.
.It Pa ~/.config/vf1/vf1rc
.It Pa ~/.config/.vf1rc
.It Pa ~/.vf1rc
Upon startup,
.Nm
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
.Nm
will stop after the first one it finds, e.g. if both
.Pa ~/.config/vf1/vf1rc
and a
.Pa ~/.vf1rc
exist then then
.Pa ~/.vf1rc
will be ignored.
.El
.Ss RC FILE
If an RC file is found, each line of the file will be executed as a
.Nm
command before the prompt is displayed.This allows users to script
certain commands that should be run every time
.Nm
is started.
This permits, for example:
.Bl -bullet
.It
Permanently configuring item type handlers by putting
.Ic handler
commands in the RC file.
.It
Permanently configuring the preferred non-UTF-8 encoding, or other
options, by putting
.Ic set
commands in the RC file.
.It
Setting a
.Dq home page
by putting a
.Ic go
command in the RC file.
.It
Starting a tour through a list of favourite sites by putting
.Ic tour
commands in the RC file.
.El
.Sh EXAMPLES
See the
.Xr vf1-turorial 7
for a comprehensive introduction to the work flow of
.Nm
.Pp
Start
.Nm :
.Pp
.Dl vf1
.Pp
Start
.Nm
and immediately open to bookmark list:
.Pp
.Dl vf1 --bookmarks
.Pp
Visit the zaibatsu:
.Pp
.Dl vf1 zaibatsu.circumlunar.space
.Sh SEE ALSO
.Xr vf1-tutorial 7
.Bl -bullet
.It
.Lk https://docs.python.org/3.5/library/mimetypes.html mimetypes
.It
.Lk https://pypi.python.org/pypi/chardet chardet
.El
.Sh STANDARDS
.Nm
is a gopher client conforming to RFC 1436
.Aq Lk https://tools.ietf.org/html/rfc1436 .
.Sh TRIVIA
.Nm
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
.Aq Lk gopher://sdf.org ,
named after the same series, has played in keeping Gopherspace alive in the
21st century.
.Sh AUTHORS
.An Solderpunk
.Aq Mt solderpunk@sdf.org
.An Alex Schroeder
.Aq Mt alex@gnu.org
.An Joseph Lyman
.Aq Mt tfurrows@sdf.org
.An Adam Mayer
.Aq Lk https://github.com/phooky
.An Paco Esteban
.Aq Mt paco@onna.be