diff options
Diffstat (limited to 'help.go')
| -rw-r--r-- | help.go | 271 |
1 files changed, 271 insertions, 0 deletions
@@ -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:], +} |