350 lines
10 KiB
Go
350 lines
10 KiB
Go
package main
|
|
|
|
import (
|
|
"errors"
|
|
"fmt"
|
|
"os"
|
|
)
|
|
|
|
var ErrNotAHelpTopic = errors.New("don't recognize that help topic")
|
|
|
|
func Help(_ *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.
|
|
cli: Flags and options available when invoking x-1 on the command line.
|
|
urls: The forms of URLs which can be entered into x-1 commands.
|
|
mark: Information on the bookmarks and the "mark" meta-command.
|
|
tour: Information about tours and the "tour" meta-command.
|
|
identity: Identities and managing them with the "identity" meta-command.
|
|
config: The x-1 configuration file.
|
|
`[1:],
|
|
|
|
"commands": `
|
|
x-1 prompt commands
|
|
-------------------
|
|
root Root up
|
|
back forward
|
|
next previous
|
|
reload print pipe
|
|
about help
|
|
go history save
|
|
links outline
|
|
tour mark identity
|
|
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:],
|
|
|
|
"cli": `
|
|
x-1 -h
|
|
x-1 [-q] [-c COMMANDS] [URL]
|
|
-----------------------
|
|
With no arguments or flags, x-1 will just display the prompt and begin
|
|
executing your commands. Use the "help" command to begin exploring this
|
|
interactive mode.
|
|
|
|
With the -c flag, it will execute the provided commands (multiple may be
|
|
provided by separating them with a semi-colon ';') and then exit. In
|
|
this mode it also forces quiet mode, in which it doesn't automatically
|
|
print loaded pages.
|
|
|
|
The -q flag will force quiet mode, overriding "quiet" in the
|
|
configuration file.
|
|
|
|
With a URL argument, it will begin an interactive prompt session by
|
|
loading the requested url.
|
|
`[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.
|
|
* timeout (string): Maximum time to wait trying to make a connection
|
|
to the host. Should be in the form with a unit suffix, like "15s" or
|
|
"500ms". The default is "10s".
|
|
|
|
`[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", and "m[ark]" alone
|
|
is treated as "mark list".
|
|
|
|
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.
|
|
m[ark] d[elete] NAME: removes the named mark.
|
|
`[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:],
|
|
|
|
"identity": `
|
|
i[dentity]
|
|
----------
|
|
An identity is a managed credential in the form of a TLS client
|
|
certificate. This meta-command supports managing your various identities
|
|
and assigning them to be used on particular domains or on specific
|
|
pages.
|
|
|
|
i[dentity] c[reate] NAME: create a new identity (TLS key/certificate).
|
|
i[dentity] l[ist]: list identities and the domains and paths on which
|
|
they are assigned to be used.
|
|
i[dentity] u[se] NAME d[omain] DOMAIN: assign the named identity to be
|
|
used across a given domain.
|
|
i[dentity] u[se] NAME f[older] URL: assign an identity to be used on any
|
|
path which has URL as a prefix.
|
|
i[dentity] u[se] NAME p[age] URL: always use the named identity on a
|
|
specific page.
|
|
i[dentity] d[elete] NAME: remove the named identity and any
|
|
domain/folder/page associations it has.
|
|
|
|
Any "identity use" command will override existing associations to the
|
|
same domain/folder/page.
|
|
`[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:],
|
|
|
|
"outline": `
|
|
o[utline]
|
|
---------
|
|
Shortens the current page by online displaying the headers 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:],
|
|
}
|