From c114f8db1ed23646323ea6af518317168872fccc Mon Sep 17 00:00:00 2001 From: dvkt Date: Fri, 10 Jan 2020 20:19:54 -0800 Subject: [PATCH] document phetch.conf --- README.md | 1 - doc/phetch.1 | 60 ++++++++++++++++++++++++++++++++++++++++++++----- doc/phetch.1.md | 51 ++++++++++++++++++++++++++++++++++++----- src/config.rs | 2 +- src/help.rs | 35 +++++++++++++++++++++++++++++ 5 files changed, 137 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 45174ce..917ef8d 100644 --- a/README.md +++ b/README.md @@ -108,7 +108,6 @@ You can check whether TLS is enabled by visiting the About page: - [ ] Changelog generation (for gopher and github) - [ ] GIF screencast -- [ ] document ~/.config/phetch/phetch.conf ## future features diff --git a/doc/phetch.1 b/doc/phetch.1 index 1a09877..2974ec2 100644 --- a/doc/phetch.1 +++ b/doc/phetch.1 @@ -14,6 +14,22 @@ phetch - quick lil gopher client .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 @@ -43,6 +59,11 @@ Set the TOR_PROXY env variable to use an address other than the Tor default of 127.0.0.1:9050. .P .RE +\fB--emoji\fR +.RS 4 +Show TLS/Tor status as emoji. +.P +.RE \fB-h\fR, \fB--help\fR .RS 4 Print a help summary and exit. @@ -161,7 +182,7 @@ Toggle wide mode. 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. Phetch will scroll for you, or you can +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 @@ -176,7 +197,7 @@ selected. Use \fBEnter\fR to open the selected link. Incremental search .RS 4 Press \fBf\fR or \fB/\fR to activate search mode, then just start -typing. Phetch will look for the first case-insensitive match +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 @@ -217,14 +238,43 @@ the \fBa\fR key. 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. 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) +wide no + +# Use emoji indicators for TLS & Tor\&. (--emoji) +emoji no +.fi +.RE +.P .SH ABOUT .P -Phetch is maintained by dvkt, and released under the MIT license. +\fBphetch\fR is maintained by dvkt, and released under the MIT license. .P -Phetch's Gopher hole: +phetch's Gopher hole: .RS 4 \fIgopher://phkt.io/1/phetch\fR .RE -Phetch's webpage: +phetch's webpage: .RS 4 \fIhttps://github.com/dvkt/phetch\fR diff --git a/doc/phetch.1.md b/doc/phetch.1.md index 1882c65..08f666a 100644 --- a/doc/phetch.1.md +++ b/doc/phetch.1.md @@ -8,6 +8,20 @@ phetch - quick lil gopher client *phetch* [_OPTIONS_] [_URL_] +# DESCRIPTION + +*phetch* 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. + +Usually *phetch* is started with a Gopher URL: + + phetch gopher://some-gopher-url.com + +If no URL is given, however, *phetch* will launch and open its default +"start page". This can be configured to be any URL. (See *CONFIG*.) + # OPTIONS *-l*, *--local* @@ -103,7 +117,7 @@ and *Ctrl-h* are synonyms. Up and down arrows Use the up and down arrows, *j* and *k* keys, or *n* and *p* - keys to select links. Phetch will scroll for you, or you can + keys to select links. *phetch* will scroll for you, or you can use page up and page down (or *-* and spacebar) to scroll by many lines at once. @@ -114,7 +128,7 @@ Number keys Incremental search Press *f* or */* to activate search mode, then just start - typing. Phetch will look for the first case-insensitive match + typing. *phetch* will look for the first case-insensitive match and try to select it. Use arrow keys or *Ctrl-p*/*Ctrl-n* to cycle through matches. @@ -148,11 +162,38 @@ the *a* key. Feel free to edit your history file directly, or share it with your friends! +# CONFIG + +If you create a _phetch.conf_ file in _~/.config/phetch/_, it will be +automatically loaded when *phetch* starts. The config file supports +most command line options, for your convenience. For example, +*phetch* will always launch in TLS mode if `tls yes` appears in the +config file -- no need to pass `--tls` or `-t` on startup. + +Here is an example config with all options: + +``` +# 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) +wide no + +# Use emoji indicators for TLS & Tor. (--emoji) +emoji no +``` + # ABOUT -Phetch is maintained by dvkt, and released under the MIT license. +*phetch* is maintained by dvkt, and released under the MIT license. -Phetch's Gopher hole: +phetch's Gopher hole: _gopher://phkt.io/1/phetch_ -Phetch's webpage: +phetch's webpage: _https://github.com/dvkt/phetch_ diff --git a/src/config.rs b/src/config.rs index f604d4b..197362a 100644 --- a/src/config.rs +++ b/src/config.rs @@ -22,7 +22,7 @@ start gopher://phetch/1/home # Always use TLS mode. (--tls) tls no -# Connect using local TOR proxy. (--tor) +# Connect using local Tor proxy. (--tor) tor no # Always start in wide mode. (--wide) diff --git a/src/help.rs b/src/help.rs index 345a17d..94828b1 100644 --- a/src/help.rs +++ b/src/help.rs @@ -6,6 +6,7 @@ pub fn lookup(name: &str) -> Option { "" | "/" | "home" | "home/" => format!("{}{}", HEADER, START), "history" => history::as_raw_menu(), "bookmarks" => bookmarks::as_raw_menu(), + "help/config" => format!("{}{}", HEADER, CONFIG), "help/keys" => format!("{}{}", HEADER, KEYS), "help/nav" => format!("{}{}", HEADER, NAV), "help/types" => format!("{}{}", HEADER, TYPES), @@ -64,6 +65,7 @@ i 1gopher types /help/types phetch 1bookmarks /help/bookmarks phetch 1history /help/history phetch +1phetch.conf /help/config phetch i i ~ * ~ i @@ -186,6 +188,39 @@ ifile directly, or share it iwith your friends! "; +const CONFIG: &str = " +i ** config ** +i +iif you create a phetch.conf +ifile in ~/.config/phetch/ it +iwill be automatically loaded +iwhen phetch starts. the config +ifile supports most command line +ioptions, for your convenience. +i +ifor example, phetch will always +ilaunch in TLS mode if `tls yes` +iappears in the config file. +i +ihere is an example phetch.conf +iwith all possible keys: +i +i# page to load when launched +istart gopher://phetch/1/home +i +i# always use TLS mode +itls no +i +i# connect over tor proxy +itor no +i +i# start in wide mode +iwide no +i +i# show emoji status indicators +iemoji no +"; + const TYPES: &str = " i ** gopher types ** i