diff --git a/amfora.1 b/amfora.1 new file mode 100644 index 0000000..27d15e1 --- /dev/null +++ b/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\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\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 + + + + + Example Bookmark + + +.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