path: root/help.go

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 also has 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
about   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 "~" (the user's home directory).
  * quiet (boolean): Disables automatically printing the page after any
    navigation action. The default is false.
  * pager (string): Set this to "always", "never", or "auto". "always"
    will pipe every page printed through less(1), "never" will not, and
    "auto" will pipe it through "less -F", which skips the pager when
    the output fits on a single screen anyway.

`[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] [N]
----------
Navigates to the previous page in the browser history.

With an integer argument, goes N positions back.
`[1:],

	"forward": `
f[orward] [N]
-------------
Navigates to the next page in the browser history.

With an integer argument, goes N positions forward.
`[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.

By default, the print action (whether automatic or upon the print
command) will pipe the output through "less -F", where the -F switch
disables the pager if the output fits in one screen. This can be
disabled with the "auto_pager" configuration option.
`[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:],

	"about": `
a[bout]
-------
Displays a short page about the x-1 browser.
`[1:],

	"quit": `
q[uit]
------
Quits x-1 immediately.
`[1:],
}