phetch/doc/phetch.1

.\" Generated by scdoc 1.11.2
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "PHETCH" "1" "2022-11-14"
.P
.SH NAME
.P
phetch - quick lil gopher client
.P
.SH SYNOPSIS
.P
\fBphetch\fR [\fIOPTIONS\fR] [\fIURL\fR]
.P
.SH DESCRIPTION
.P
\fBphetch\fR is a terminal client designed to help you quickly navigate
the gophersphere.\& It features non-nonsense keyboard navigation,
support for most Gopher features, easy-to-use TLS and Tor support, as
well as bookmarking and history features.\&
.P
Usually \fBphetch\fR is started with a Gopher URL:
.P
.RS 4
phetch gopher://some-gopher-url.\&com
.P
.RE
If no URL is given, however, \fBphetch\fR will launch and open its default
"start page".\& This can be configured to be any URL.\& (See \fBCONFIG\fR.\&)
.P
.SH OPTIONS
.P
\fB-l\fR, \fB--local\fR
.RS 4
Connect to the local Gopher server at URL \fI127.\&0.\&0.\&1:7070\fR.\&
.P
.RE
\fB-p\fR \fIURL\fR, \fB--print\fR \fIURL\fR
.RS 4
Print a rendered Gopher server response of \fIURL\fR and exit.\&
.P
.RE
\fB-r\fR \fIURL\fR, \fB--raw\fR \fIURL\fR
.RS 4
Print the raw Gopher server response of \fIURL\fR and exit.\&
.P
.RE
\fB-s\fR, \fB--tls\fR
.RS 4
Attempt to fetch all pages securely over TLS.\&
.P
.RE
\fB-S\fR, \fB--no-tls\fR
.RS 4
Do not use TLS for connections.\& This can be used to cancel out an
option set in the config file, for instance.\&
.P
.RE
\fB-o\fR, \fB--tor\fR
.RS 4
Make all connections using a local Tor proxy.\&
Tor is The Onion Router.\&
Set the TOR_PROXY env variable to use an address other than the
Tor default of 127.\&0.\&0.\&1:9050.\&
.P
.RE
\fB-O\fR, \fB--no-tor\fR
.RS 4
Disable Tor.\&
.P
.RE
\fB-w\fR, \fB--wrap\fR \fICOLUMN\fR
.RS 4
Wrap long lines in Gopher "text" views at \fICOLUMN\fR.\&
Default: 0 (off)
.P
.RE
\fB-m\fR, \fB--media\fR \fIPATH\fR
.RS 4
Use program at \fIPATH\fR to open media files (movies and sounds).\&
Default: mpv
.P
.RE
\fB-M\fR, \fB--no-media\fR
.RS 4
Don'\&t try to open media files.\& Download them like regular binary
Gopher items.\&
.P
.RE
\fB-a\fR, \fB--autoplay\fR
.RS 4
Autoplay media files instead of prompting.\&
.P
.RE
\fB-A\fR, \fB--no-autoplay\fR
.RS 4
Don'\&t autoplay media files.\& Prompt instead.\&
.P
.RE
\fB-c\fR, \fB--config\fR \fIFILE\fR
.RS 4
Use \fIFILE\fR instead of \fI~/.\&config/phetch/phetch.\&conf\fR
.P
.RE
\fB-C\fR, \fB--no-config\fR
.RS 4
Do not use any config file.\&
.P
.RE
\fB-t\fR, \fB--theme\fR \fIFILE\fR
.RS 4
Use \fIFILE\fR for color theme.\&
.P
.RE
\fB--print-theme\fR
.RS 4
Print current theme.\&
.P
.RE
\fB-e\fR, \fB--encoding\fR \fIENCODING\fR
.RS 4
Render text views in CP437 or UTF8 (default) encoding.\&
.P
.RE
\fB-h\fR, \fB--help\fR
.RS 4
Print a help summary and exit.\&
.P
.RE
\fB-v\fR, \fB--version\fR
.RS 4
Print version information and exit.\&
.P
.RE
.SH NOTES
.P
When given a \fIURL\fR, \fBphetch\fR will show the requested Gopher page and
enter interactive mode.\&
.P
Without a \fIURL\fR, \fBphetch\fR will show a builtin dashboard with easy
access to online help, bookmarks and history, and enter interactive
mode.\&
.P
Command line options always override options set in phetch.\&conf.\&
.P
.SH NAVIGATION
.P
.SS KEYBOARD SHORTCUTS
.P
All single letter commands also work with the \fBCtrl\fR key: e.\&g.\&, \fBh\fR
and \fBCtrl-h\fR are synonyms.\&
.P
\fBh\fR
.RS 4
Go to builtin help page.\&
.RE
\fBq\fR
.RS 4
Quit \fBphetch\fR.\&
.P
.RE
\fBleft arrow\fR
.RS 4
Go back in history.\&
.RE
\fBright arrow\fR
.RS 4
Go forward in history.\&
.RE
\fBup arrow\fR, \fBp\fR, \fBk\fR
.RS 4
Select previous link.\&
.RE
\fBdown arrow\fR, \fBn\fR, \fBj\fR
.RS 4
Select next link.\&
.RE
\fBPgUp\fR, \fB-\fR
.RS 4
Scroll up by many lines.\&
.RE
\fBPgDn\fR, \fBSPACE\fR
.RS 4
Scroll down by many lines.\&
.P
.RE
\fBNumber key\fR
.RS 4
Open/select link.\&
.RE
\fBEnter\fR
.RS 4
Open current link.\&
.RE
\fBEsc\fR, \fBCtrl-c\fR
.RS 4
Cancel
.P
.RE
\fBf\fR, \fB/\fR
.RS 4
Find link in page.\&
.P
.RE
\fBg\fR
.RS 4
Go to Gopher URL.\&
.RE
\fBR\fR
.RS 4
Reload current URL.\&
.RE
\fBu\fR
.RS 4
Edit URL.\&
.RE
\fBy\fR
.RS 4
Copy URL.\&
.P
.RE
\fBb\fR
.RS 4
Show bookmarks.\&
.RE
\fBs\fR
.RS 4
Save bookmark.\&
.RE
\fBa\fR
.RS 4
Show history.\& (Mnemonic: \fBAll\fR pages/history)
.P
.RE
\fBr\fR
.RS 4
View raw source.\&
.RE
\fBw\fR
.RS 4
Toggle wide mode.\&
.RE
\fBe\fR
.RS 4
Toggle encoding between UTF8 and CP437.\&
.P
.RE
.SS MENU NAVIGATION
.P
Up and down arrows
.RS 4
Use the up and down arrows, \fBj\fR and \fBk\fR keys, or \fBn\fR and \fBp\fR
keys to select links.\& \fBphetch\fR will scroll for you, or you can
use page up and page down (or \fB-\fR and spacebar) to scroll by
many lines at once.\&
.P
.RE
Number keys
.RS 4
If there are few enough menu items, pressing a number key will
open a link.\& Otherwise, the first matching number will be
selected.\& Use \fBEnter\fR to open the selected link.\&
.P
.RE
Incremental search
.RS 4
Press \fBf\fR or \fB/\fR to activate search mode, then just start
typing.\& \fBphetch\fR will look for the first case-insensitive match
and try to select it.\& Use arrow keys or \fBCtrl-p\fR/\fBCtrl-n\fR to cycle
through matches.\&
.P
.RE
.SH BOOKMARKS
.P
There are two ways to save the URL of the current page:
.P
\fBy\fR
.RS 4
Copy URL.\&
.RE
\fBs\fR
.RS 4
Save bookmark.\&
.P
.RE
Bookmarks will be saved to the file \fI~/.\&config/phetch/bookmarks.\&gph\fR if
the directory \fI~/.\&config/phetch/\fR exists.\&
.P
\fBb\fR
.RS 4
View saved bookmarks.\&
.P
.RE
The clipboard function uses \fBpbcopy\fR on MacOS, and \fBxsel\fR \fI-sel clip\fR
on Linux.\&
.P
.SH HISTORY
.P
If you create a \fIhistory.\&gph\fR file in \fI~/.\&config/phetch/\fR, each Gopher
URL you open will be stored there.\&
.P
New URLs are appended to the bottom, but loaded in reverse order, so
you'\&ll see all the most recently visited pages first when you press
the \fBa\fR key.\&
.P
Feel free to edit your history file directly, or share it with your
friends!\&
.P
.SH CONFIG
.P
If you create a \fIphetch.\&conf\fR file in \fI~/.\&config/phetch/\fR, it will be
automatically loaded when \fBphetch\fR starts.\& The config file supports
most command line options, for your convenience, as well as a few ways
to customize your browsing experience.\& For example, \fBphetch\fR will
always launch in TLS mode if `tls yes` appears in the  config file --
no need to pass `--tls` or `-t` on startup.\&
.P
Here is an example config with all options:
.P
.nf
.RS 4
# Page to load when launched with no URL argument\&.
start gopher://phetch/1/home

# Always use TLS mode\&. (--tls)
tls no

# Connect using local TOR proxy\&. (--tor)
tor no

# Always start in wide mode\&.
wide no

# Program to use to open media files\&.
media mpv

# Use emoji indicators for TLS & Tor\&.
emoji no

# Encoding\&. Only CP437 and UTF8 are supported\&.
encoding utf8

# Wrap text at N columns\&. 0 = off (--wrap)
wrap 0

# How many lines to page up/down by? 0 = full screen
scroll 0

# Path to theme file, if you want to use one
theme ~/\&.config/phetch/dark\&.theme
.fi
.RE
.P
.SH THEMES
.P
You can change phetch'\&s color scheme by supplying your own theme
file with `--theme`/`-t` or by setting `theme FILE` in your
phetch.\&conf.\&
.P
You can also view the current theme with:
.P
.RS 4
$ phetch --print-theme
.P
.RE
Theme files look like this:
.P
.nf
.RS 4
ui\&.cursor white bold
ui\&.number magenta
ui\&.menu yellow
ui\&.text white
item\&.text cyan
item\&.menu blue
item\&.error red
item\&.search white
item\&.telnet grey
item\&.external green
item\&.download white underline
item\&.media green underline
item\&.unsupported whitebg red
.fi
.RE
.P
Valid colors for use in phetch themes:
.P
.nf
.RS 4
bold
underline

grey
red
green
yellow
blue
magenta
cyan
white
black

darkred
darkgreen
darkyellow
darkblue
darkmagenta
darkcyan
darkwhite

blackbg
redbg
greenbg
yellowbg
bluebg
magentabg
cyanbg
whitebg
.fi
.RE
.P
.SH MEDIA PLAYER SUPPORT
.P
\fBphetch\fR includes support for opening video files (`;` item type) and
sound files (`s` item type) in `mpv` or an application of your choice
using the `-m` command line flag.\& To test it out, visit a compatible
Gopher server or check out the "gopher types" help page by lauching
\fBphetch\fR and then pressing `ctrl-h` then `3`.\&
.P
By default \fBphetch\fR will prompt you when you try to open a media file,
but you can change this behavior by starting it with `--autoplay`/`-a`
or by setting `autoplayer true` in your config file.\&
.P
.SH ABOUT
.P
\fBphetch\fR is maintained by chris west, and released under the MIT license.\&
.P
phetch'\&s Gopher hole:
.RS 4
\fIgopher://phkt.\&io/1/phetch\fR
.RE
phetch'\&s webpage:
.RS 4
\fIhttps://github.\&com/xvxx/phetch\fR