document phetch.conf

4 years ago · c114f8db1e
parent 30ded8ed69
commit c114f8db1e
5 changed files with 137 additions and 12 deletions
--- 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

--- 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
--- 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_
--- 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)
--- a/src/help.rs
+++ b/src/help.rs
@ -6,6 +6,7 @@ pub fn lookup(name: &str) -> Option<String> {
        "" | "/" | "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