Merge 8352784dfc into 926b77275f

.github/FUNDING.yml

@@ -1,2 +1,2 @@
-github: makeworld-the-better-one
+github: makew0rld
 ko_fi: makeworld

amfora.1

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