|
|
|
@ -0,0 +1,266 @@
|
|
|
|
|
.Dd $Mdocdate$
|
|
|
|
|
.Dt AMFORA 1
|
|
|
|
|
.Os
|
|
|
|
|
.Sh NAME
|
|
|
|
|
.Nm amfora
|
|
|
|
|
.Nd fancy terminal gemini browser
|
|
|
|
|
.Sh SYNOPSIS
|
|
|
|
|
.Nm amfora
|
|
|
|
|
.Op Fl h | Fl v | Ar gemini-url
|
|
|
|
|
.Sh DESCRIPTION
|
|
|
|
|
.Nm
|
|
|
|
|
is a fancy gemini client in your terminal.
|
|
|
|
|
.Nm
|
|
|
|
|
is written in Go and supports tabs, caching, theming, proxying, subscriptions, client certificates, external link handling, and a built in search engine.
|
|
|
|
|
Subscriptions are supported through gemini, atom, RSS, and JSON Feed files.
|
|
|
|
|
.Nm
|
|
|
|
|
caches documents
|
|
|
|
|
.Pq aka Qq pages
|
|
|
|
|
it loads, to reduce latency: if you're navigating through history, or simply just returning to the same page again.
|
|
|
|
|
.Nm
|
|
|
|
|
supports proxies so that certain types of URLs will not require opening another application.
|
|
|
|
|
.Pp
|
|
|
|
|
The
|
|
|
|
|
.Nm
|
|
|
|
|
config allows you to set the command to be run when following links that are non-Gemini URLs.
|
|
|
|
|
For example, you may want mailto: links to be opened with your email client, or magnet: links to be opened with your torrent software.
|
|
|
|
|
In
|
|
|
|
|
.Nm
|
|
|
|
|
you can specify proxies so that certain types of URLs will not require opening another application.
|
|
|
|
|
In the config,
|
|
|
|
|
.Bq proxies
|
|
|
|
|
take precedence over
|
|
|
|
|
.Bo url-handlers Bc .
|
|
|
|
|
.Pp
|
|
|
|
|
By default, when clicking a non-text file,
|
|
|
|
|
.Nm
|
|
|
|
|
will present you with options to either Open or Download the file.
|
|
|
|
|
If you choose Open,
|
|
|
|
|
.Nm
|
|
|
|
|
will download the file to a temporary folder, and then open it using your OS's default application for that file type.
|
|
|
|
|
You can configure what applications
|
|
|
|
|
.Nm
|
|
|
|
|
uses if you want to override this behaviour.
|
|
|
|
|
You can also configure whether streaming is used.
|
|
|
|
|
.Pp
|
|
|
|
|
By default
|
|
|
|
|
.Nm
|
|
|
|
|
will automatically attempt to highlight blocks of preformatted source code.
|
|
|
|
|
This is accomplished by searching for a string at the start of the alt text; if the string corresponds to a language name or MIME type supported by chroma.go, then the syntax will be highlighted if possible.
|
|
|
|
|
.Ss CONFIGURATION
|
|
|
|
|
A default configuration file is generated on first use if it doesn't already exist.
|
|
|
|
|
.Nm
|
|
|
|
|
configuration is located from
|
|
|
|
|
.Pa ~/.config/amfora/config.toml
|
|
|
|
|
by default.
|
|
|
|
|
If the
|
|
|
|
|
.Va $XDG_CONFIG_HOME
|
|
|
|
|
variable is set then the configuration file can be found at
|
|
|
|
|
.Pa $XDG_CONFIG_HOME/amfora/config.toml .
|
|
|
|
|
.Pp
|
|
|
|
|
On Windows, the configuration file can be found at
|
|
|
|
|
.Pa %APPDATA%\eamfora\econfig.toml ,
|
|
|
|
|
which usually expands to
|
|
|
|
|
.Pa C:\eUsers\e<username>\eAppData\eRoaming\eamfora\econfig.toml .
|
|
|
|
|
.Pp
|
|
|
|
|
In this directory you can also create a gemtext file called
|
|
|
|
|
.Pa newtab.gmi
|
|
|
|
|
to customize your new tab page.
|
|
|
|
|
.Ss DEFAULT KEY BINDINGS
|
|
|
|
|
You can view the keybindings in the help menu, which can be brought up using
|
|
|
|
|
.Ic \&?
|
|
|
|
|
and exited with
|
|
|
|
|
.Ic Esc .
|
|
|
|
|
The keybindings in the help menu will update if you change your keybindings in the config.
|
|
|
|
|
.Pp
|
|
|
|
|
.Bl -tag -width 16v -compact
|
|
|
|
|
.It Ic \&?
|
|
|
|
|
Open help menu
|
|
|
|
|
.It Ic Space
|
|
|
|
|
Open bottom bar
|
|
|
|
|
.It Ic Esc
|
|
|
|
|
Close menu/bar
|
|
|
|
|
.It Ic q
|
|
|
|
|
Exit
|
|
|
|
|
.Nm
|
|
|
|
|
.It Ic 0-9
|
|
|
|
|
Access link 1-10 on page
|
|
|
|
|
.It Ic F1
|
|
|
|
|
Previous tab
|
|
|
|
|
.It Ic F2
|
|
|
|
|
Next tab
|
|
|
|
|
.It Ic Tab or Ic Enter
|
|
|
|
|
Begin link highlighting
|
|
|
|
|
.It Ic Shift-Tab
|
|
|
|
|
Highlight previous link
|
|
|
|
|
.It Ic Tab
|
|
|
|
|
Highlight next link
|
|
|
|
|
.It Ic Ctrl-T
|
|
|
|
|
Open highlighted link in new tab
|
|
|
|
|
.It Ic Ctrl-X
|
|
|
|
|
Subscribe to current page
|
|
|
|
|
.It Ic Ctrl-A
|
|
|
|
|
Visit subscription feed
|
|
|
|
|
.It Ic Ctrl-S
|
|
|
|
|
Save loaded page to disk
|
|
|
|
|
.It Ic Ctrl-C
|
|
|
|
|
Hard quit
|
|
|
|
|
.El
|
|
|
|
|
.Ss BOTTOM BAR COMMANDS
|
|
|
|
|
.Bl -tag -width 16v -compact
|
|
|
|
|
.It Cm new: Ns Va N
|
|
|
|
|
Visit link
|
|
|
|
|
.Va N
|
|
|
|
|
.It Cm about:version
|
|
|
|
|
.Nm
|
|
|
|
|
version info
|
|
|
|
|
.It Cm about:subscriptions
|
|
|
|
|
Visit subscription feed
|
|
|
|
|
.It Cm about:manage-subscriptions
|
|
|
|
|
Visit unsubscribe list
|
|
|
|
|
.It Va foo
|
|
|
|
|
Search the geminispace for
|
|
|
|
|
.Va foo .
|
|
|
|
|
.El
|
|
|
|
|
.Ss BOOKMARKS
|
|
|
|
|
.Nm
|
|
|
|
|
stores its bookmarks in an XML format called XBEL, located at
|
|
|
|
|
.Pa ~/.local/share/amfora/bookmarks.xml
|
|
|
|
|
by default.
|
|
|
|
|
If the
|
|
|
|
|
.Va XDG_DATA_HOME
|
|
|
|
|
variable is set then the configuration file can be found at
|
|
|
|
|
.Pa XDG_DATA_HOME/amfora/bookmarks.xml .
|
|
|
|
|
.Pp
|
|
|
|
|
On Windows, the file can be found at
|
|
|
|
|
.Pa %APPDATA%\eamfora\ebookmarks.xml ,
|
|
|
|
|
which usually expands to
|
|
|
|
|
.Pa C:\eUsers\e<username>\eAppData\eRoaming\eamfora\ebookmarks.xml .
|
|
|
|
|
.Pp
|
|
|
|
|
See
|
|
|
|
|
.Sx EXAMPLE BOOKMARK
|
|
|
|
|
.Sh FILES
|
|
|
|
|
.Ss *NIX
|
|
|
|
|
.Bl -tag -width 2v -compact
|
|
|
|
|
.It Pa ~/.config/amfora/config.toml
|
|
|
|
|
.It Pa ~/.local/share/amfora/bookmarks.xml
|
|
|
|
|
.El
|
|
|
|
|
.Ss XDG
|
|
|
|
|
.Bl -tag -width 2v -compact
|
|
|
|
|
.It Pa $XDG_CONFIG_HOME/amfora/config.toml
|
|
|
|
|
.It Pa $XDG_DATA_HOME/amfora/bookmarks.xml
|
|
|
|
|
.El
|
|
|
|
|
.Ss WINDOWS
|
|
|
|
|
.Bl -tag -width 2v -compact
|
|
|
|
|
.It Pa %APPDATA%\eamfora\econfig.toml
|
|
|
|
|
.It Pa %APPDATA%\eamfora\ebookmarks.xml
|
|
|
|
|
.El
|
|
|
|
|
.Sh EXIT STATUS
|
|
|
|
|
.Nm
|
|
|
|
|
exits
|
|
|
|
|
.Va 0
|
|
|
|
|
on success, and
|
|
|
|
|
.Va 1
|
|
|
|
|
if an error occurs.
|
|
|
|
|
.Sh EXAMPLES
|
|
|
|
|
.Ss EXAMPLE BOOKMARK
|
|
|
|
|
.Bd -literal
|
|
|
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
|
|
|
<!DOCTYPE xbel
|
|
|
|
|
PUBLIC "+//IDN python.org//DTD XML Bookmark Exchange Language 1.1//EN//XML"
|
|
|
|
|
"http://www.python.org/topics/xml/dtds/xbel-1.1.dtd">
|
|
|
|
|
<xbel version="1.1">
|
|
|
|
|
<bookmark href="gemini://example.com/">
|
|
|
|
|
<title>Example Bookmark</title>
|
|
|
|
|
</bookmark>
|
|
|
|
|
</xbel>
|
|
|
|
|
.Ed
|
|
|
|
|
.Ss EXAMPLE PROXY
|
|
|
|
|
.Bd -literal
|
|
|
|
|
[proxies]
|
|
|
|
|
# Allows setting a Gemini proxy for different schemes.
|
|
|
|
|
# The settings are similar to the url-handlers section above.
|
|
|
|
|
# E.g. to open a gopher page by connecting to a Gemini proxy server:
|
|
|
|
|
# gopher = "example.com:123"
|
|
|
|
|
#
|
|
|
|
|
# Port 1965 is assumed if no port is specified.
|
|
|
|
|
#
|
|
|
|
|
# NOTE: These settings override any external handlers specified in
|
|
|
|
|
# the url-handlers section.
|
|
|
|
|
#
|
|
|
|
|
# Note that HTTP and HTTPS are treated as separate protocols here
|
|
|
|
|
.Ed
|
|
|
|
|
.Ss EXAMPLE CERTIFICATE
|
|
|
|
|
.Bd -literal
|
|
|
|
|
[auth]
|
|
|
|
|
# Authentication settings
|
|
|
|
|
|
|
|
|
|
[auth.certs]
|
|
|
|
|
# Client certificates
|
|
|
|
|
# Set domain name equal to path to client cert
|
|
|
|
|
# "example.com" = "mycert.crt"
|
|
|
|
|
"astrobotany.mozz.us" = "~/.local/share/amfora/astrobotany-cert.pem"
|
|
|
|
|
|
|
|
|
|
[auth.keys]
|
|
|
|
|
# Client certificate keys
|
|
|
|
|
# Set domain name equal to path to key for the client cert above
|
|
|
|
|
# "example.com" = "mycert.key"
|
|
|
|
|
"astrobotany.mozz.us" = "~/.local/share/amfora/astrobotany-key.pem"
|
|
|
|
|
.Ed
|
|
|
|
|
.Sh DIAGNOSTICS
|
|
|
|
|
Errors are printed to
|
|
|
|
|
.Dv stderr .
|
|
|
|
|
.Sh SEE ALSO
|
|
|
|
|
The official documentation is maintained in two places:
|
|
|
|
|
.Bl -tag -width 2v -compact
|
|
|
|
|
.It Lk gemini://makeworld.space/amfora-wiki/
|
|
|
|
|
.It Lk https://github.com/makeworld-the-better-one/amfora/wiki
|
|
|
|
|
.El
|
|
|
|
|
.Pp
|
|
|
|
|
.Bl -tag -width 2v -compact
|
|
|
|
|
.It agena.py gemini-to-gopher proxy.
|
|
|
|
|
.It duckling-proxy.go gemini-to-HTTPS proxy.
|
|
|
|
|
.El
|
|
|
|
|
.Sh STANDARDS
|
|
|
|
|
.Bl -tag -width 2v -compact
|
|
|
|
|
.It Lk https://gemini.circumlunar.space/docs/specification.gmi
|
|
|
|
|
Gemini Protocol
|
|
|
|
|
.It Lk https://toml.io/en/
|
|
|
|
|
Configuration syntax
|
|
|
|
|
.It Lk http://pyxml.sourceforge.net/topics/xbel/docs/html/xbel.html
|
|
|
|
|
Bookmark syntax
|
|
|
|
|
.It Lk https://www.iana.org/assignments/media-types/media-types.xhtml
|
|
|
|
|
Media Types
|
|
|
|
|
.El
|
|
|
|
|
.Sh HISTORY
|
|
|
|
|
.Bl -tag -width 2v -compact
|
|
|
|
|
.It v1.0 was released on June 1, 2020 with tabs, TOFU, colors, history and input.
|
|
|
|
|
.It Bookmarks, charsets, and search were added in v1.1 on Jun 24.
|
|
|
|
|
.It Downloading was implemented in v1.3 on Jul 2.
|
|
|
|
|
.It Themeing came in v1.4 on Jul 28.
|
|
|
|
|
.It Emojies and extended proxy support came in v1.5 on Sep 01.
|
|
|
|
|
.It Client certificates were implemented in v1.6 on Nov 4.
|
|
|
|
|
.It Subscriptions and a wiki were implemented in v1.7 on Dec 20.
|
|
|
|
|
.It v1.8 added media type handlers on Feb 17, 2021.
|
|
|
|
|
.It v1.9 began storing bookmarks in XBEL on Dec 7.
|
|
|
|
|
.El
|
|
|
|
|
.Sh AUTHORS
|
|
|
|
|
The principle author of the
|
|
|
|
|
.Nm
|
|
|
|
|
project is
|
|
|
|
|
.An makeworld Aq Mt makeworld@protonmail.com .
|
|
|
|
|
By v1.9.2, 47 people had committed to the amfora repository, see
|
|
|
|
|
.Pa THANKS.md
|
|
|
|
|
in the source for more information.
|
|
|
|
|
.Sh CAVEATS
|
|
|
|
|
Using OpenSSL on Windows is not so easy.
|
|
|
|
|
One way is to install Chocolatey, and run
|
|
|
|
|
.Qq choco install openssl
|
|
|
|
|
.Pp
|
|
|
|
|
.Nm
|
|
|
|
|
does not support gopher or other non-web protocols - check out
|
|
|
|
|
.Lk https://bombadillo.colorfield.space/ "bombadillo"
|
|
|
|
|
for that.
|
|
|
|
|
.Sh BUGS
|
|
|
|
|
There are sometimes known UI rendering glitches.
|
|
|
|
|
.\" .Sh SECURITY CONSIDERATIONS
|