help command, quiet mode, and s/set/select

1 files changed, 271 insertions, 0 deletions

diff --git a/help.go b/help.go
new file mode 100644
index 0000000..3de618b
--- /dev/null
+++ b/help.go
@@ -0,0 +1,271 @@
+package main
+
+import (
+	"errors"
+	"fmt"
+	"os"
+)
+
+var ErrNotAHelpTopic = errors.New("don't recognize that help topic")
+
+func Help(state *BrowserState, topic string) error {
+	if topic == "" {
+		topic = "topics"
+	}
+
+	out, ok := helpTopics[topic]
+	if !ok {
+		return ErrNotAHelpTopic
+	}
+
+	_, err := fmt.Fprintln(os.Stdout, out)
+	return err
+}
+
+var helpTopics = map[string]string{
+	"topics": `
+help topics
+-----------
+commands: Basics of x-1 commands, and a full listing of them. Each
+	  command is also its own help topic.
+urls:     The forms of URLs which can be entered into x-1 commands.
+mark:     Information on the "mark" meta-command.
+tour:     Information about the "tour" meta-command.
+config:   The x-1 configuration file.
+`[1:],
+
+	"commands": `
+x-1 prompt commands
+-------------------
+root    Root      up
+back    forward
+next    previous
+reload  print     pipe
+help    links     history
+tour    mark
+go      save      quit
+
+Any command may be written as any prefix sufficiently long to be unique.
+So for instance, "reload" can be specified by just typing "re". This is
+clarified in the help pages with a form that shows which characters are
+required, such as "re[load]" or "q[uit]".
+
+The empty command (just hitting Enter at the prompt) is interpreted as
+"print".
+
+Typing just any URL is interpreted as a "go" command to that URL. See
+"help urls" for more information on forms of allowed URLs.
+
+Consult "help COMMAND" for more information on any single command.
+`[1:],
+
+	"urls": `
+x-1 urls
+--------
+Commands which take URLs can have them specified in different forms:
+  * full absolute URLs with or without a scheme,
+  * relative URLs will be interpreted relative to the current page,
+  * "." always refers to the current page's URL,
+  * positive integers follow numbered links on the current page,
+  * "m:NAME" follows the bookmark with the given name (or identified
+    by a unique prefix of the name),
+  * "t:N" is the link in the current tour with number N,
+  * and "t[NAME]:N" is the link in the named tour (or again with the
+    given name prefix) at number N.
+
+The "tour add" command also supports URL ranges in a few forms:
+  * "*" refers to all the links in the current page,
+  * and "M-N" refers to the links numbered M through N (inclusive on
+    both ends) on the current page.
+`[1:],
+
+	"config": `
+x-1 config file
+---------------
+The configuration file for x-1 is in TOML format and lives under
+$XDG_CONFIG_HOME (or $HOME/.config) in "x-1/config.toml".
+
+The section "[main]" contains general configuration options:
+  * vim_keys (boolean): Whether to use vim keybindings for the readline
+    prompt. Defaults to true.
+  * default_scheme (string): The scheme to use in absolute URLs which
+    don't provide one. The default is "gemini".
+  * soft_wrap (int): The number of columns at which to wrap long lines.
+    Be aware that additional columns will be used on the left to display
+    link indices.
+  * download_folder (string): The folder in which to store files saved
+    by the "save" command. This string may also start with "~", which
+    stands in for $HOME. The default is "~" (or $HOME).
+  * quiet (boolean): Disables automatically printing the page after any
+    navigation action. The default is false.
+
+`[1:],
+
+	"mark": `
+m[ark]
+------
+Marks are URLs saved and associated with a name which can be used to
+look them up again. Marks are preserved across x-1 sessions.
+
+The mark meta-command has multiple sub-commands which can be used to
+manage and navigate to your saved marks. "m[ark] X" with any mark name
+or unique prefix of a name can be used as "mark go".
+
+m[ark] a[dd] NAME URL: adds a new name/url pair to your saved marks.
+m[ark] g[o] NAME: navigates to the named mark's URL.
+m[ark] l[ist]: shows the list of marks and their URLs.
+`[1:],
+
+	"tour": `
+t[our]
+------
+Tours are ordered lists of links. You can create a tour and save it
+under a name in which case it will be preserved across x-1 sessions, or
+there is always a "default" tour which is always active and empty at
+startup.
+
+Tour is another meta-command with multiple sub-commands for managing and
+navigating tours. "t[our]" alone with no sub-command implies "tour
+next", and "t[our]" followed by one or more URLs behaves as "tour add".
+
+t[our] a[dd] URL...: add urls to the end of the current tour.
+t[our] a[dd] n[ext] URL...: add urls to the next position in the tour.
+t[our] n[ext]: visit the next link in the current tour.
+t[our] p[revious]: visit the previous link in the current tour.
+t[our] sh[ow]: display the links in the current tour.
+t[our] c[lear]: empty out the current tour.
+t[our] g[o] N: jump to integer position N in the current tour.
+t[our] s[elect] [NAME]: make the named tour active (optionally named
+  by a unique prefix), or without a name, selects the default tour.
+`[1:],
+
+	"root": `
+r[oot]
+------
+Navigates to the root of the current site.
+
+On most sites this will be the domain level, but if you are within a URL
+path beginning with a tilde-name "/~name", it will navigate up to the
+root of that tilde-name path.
+
+The "R[oot]" variant does the same thing but will ignore tilde paths.
+`[1:],
+
+	"Root": `
+R[oot]
+------
+Navigate up to the root of the current domain.
+`[1:],
+
+	"up": `
+u[p]
+----
+Navigates to the parent directory path of the current page's path.
+`[1:],
+
+	"back": `
+b[ack]
+------
+Navigates to the previous page in the browser history.
+`[1:],
+
+	"forward": `
+f[orward]
+---------
+Navigates to the next page in the browser history.
+`[1:],
+
+	"next": `
+n[ext]
+------
+Navigates to the next link in the previous page.
+
+This command actually executes "back", then follows the link which comes
+after the link that was previously used.
+
+It will fail if some other means of navigation was used to get to the
+current page, such as "go" or a mark or tour.
+`[1:],
+
+	"previous": `
+pre[vious]
+----------
+Navigates to the previous link on the previous page.
+
+This command executes "back" and then follows the link which comes
+before the one that was previously used to get to the current page.
+
+It will fail if some other means of navigation was used to get here,
+such as "go" or a mark or tour.
+`[1:],
+
+	"reload": `
+re[load]
+--------
+Re-requests and displays the current page.
+`[1:],
+
+	"print": `
+p[rint]
+-------
+Displays the current page.
+
+This will happen anyway by default with any navigation action, but the
+"quiet" configuration option can disable that.
+`[1:],
+
+	"pipe": `
+pi[pe] CMD
+----------
+Run a shell command, sending the current page into its standard input.
+
+The cmd may contain spaces and will be run in a shell with
+"sh -c 'CMD'".
+`[1:],
+
+	"help": `
+h[elp] [TOPIC]
+--------------
+Display help text.
+
+Without TOPIC, it will display "help topics" which lists some useful
+starting points.
+`[1:],
+
+	"links": `
+l[inks]
+-------
+Shortens the current page by only displaying the links in it.
+`[1:],
+
+	"history": `
+h[istory]
+---------
+Displays the current history stack.
+
+Navigate across it with "back" and "forward" commands.
+`[1:],
+
+	"go": `
+g[o] URL
+--------
+Navigates to any URL.
+
+See "help urls" for more on the forms supported.
+`[1:],
+
+	"save": `
+s[ave] FILENAME
+---------------
+Saves the current page under a given filename.
+
+The directory can be controlled with the "download_folder" option in the
+config file, but defaults to the user's home directory.
+`[1:],
+
+	"quit": `
+q[uit]
+------
+Quits x-1 immediately.
+`[1:],
+}