# X-1: fly around the small web at the speed of sound

```ASCII art image of a Bell X-1 in flight
                                                                                ...
                                                                              *=:::.
                                                     ---======-              -+-.....
                                                     .#@@@@@@@=             .+=-:....:++
                                                    +@@@@@@@@#              :-::.. ...*+
                                                  :%@@@@@@@@@.             =*+++==:....
                                                .*@@@@@@@@@@=            -#%###**++-:..
                                               -@@@@@@@@@@@%     .::-=*#@@#*#@@@@@@@%-.
                              ..:::----=====++#@@@@@@@@@@@@%%%@@@@@@@@@@%%#**@@@@@@@=
                     .-+#%%@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@-
                    =*@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@##%@@*%@@@@@@@@@@-  ..
           -+*.     .#@@@@@@@@@@@@@@@@@@@@@@@@@@@%@@@@@@%%%%###- =- .=.==----==--:...
...:::::=#@@@@#**+*##@@@#*%%%%%%%%##############******+==-:-=-:.-==-:..   ...
         .:.:-==++++====::-----::---:-+%@@@@@@@@@@@@@#-...
                   .  ...............=@@@@@@@@@@@@@@+....
                                    -@@@@@@@@@@@@@#.
                                   -@@@@@@@@@@@@%-
                                  -@@%%##@@@@@@=
                                 =%++*=-=%@@@*.
                                =--*%%%::#@#:
                               *@+=#-+*%@%-
                             .*%****###@+.
                   ::..:::.::*@@@%%%%%#:
```

## Prior art

=> gemini://mozz.us/journal/2021-01-01.gmi Mozz post on gemini client navigation
=> gemini://zaibatsu.circumlunar.space/~solderpunk/gemlog/gemini-client-navigation.gmi Solderpunk response with more thoughts

These posts offer up some helpful but uncommon ideas for a browser:

* previous/next link actions: reference the previous page in the history, follow the link before or after the one that was followed to get here
* parent: go to the relative path "../"
* root: go to site-relative path "/" - although I like lagrange's modification where if you're within a /~username url it takes you to /~username
* dedicated refresh action: old idea but going away

## Commands

The default action for a completely empty command is "print", which will display the current page. If, however, a URL is entered then "go" is implied.

* re[load]: re-request and re-display the current page
* r[oot]: go to the root of the current site, or /~username root if in a tilde-path
* R[oot]: go to /, ignoring tilde-paths
* b[ack] [N]: back in history
* f[orward] [N]: forward in history
* n[ext]: go to the next link in the previous history page - see below (like "back" followed by "go N+1" where N is the link index we used to get to the current page)
* pre[vious]: go to the previous link in the previous history page - see below
* u[p]: go to the parent directory of the current page
* g[o] <link>: visits a URL, which may be an integer in which case it's the numbered link on the current page, or an absolute or relative URL
* hi[story]: display the current history
* p[rint]: display the current page
* l[inks]: filter the page down to just a list of its links
* pi[pe] <shell command>, or |<shell command>: pipe the page's content through any shell command, executed with "sh -c"
* s[ave] <path>: save the page's content at a particular filesystem path
* h[elp] [<topic>]: show a help screen
* m[ark]: bookmarks, see below
* t[our]: tours, seee below
* q[uit]: exit the browser

## URL specifiers

Commands which take URLs can take them in a variety of forms:
* full absolute URLs with or without a scheme
* relative URLs interpreted relative to the current page
* "." always refers to the current page's URL
* positive integers - the link index shown next to links on the current page
* "m:<name>" - the link saved by a mark with a specific name (or unique prefix of a mark name)
* "t:<N>" - the URL in the current tour at index N
* "t[<X>]:<N>" - The URL in the named X tour at index N

The "tour add" command additionally also supports ranges of URLs in these forms:
* "x-y" where x and y are integers, this expands to the range of links in the current page from x to y, inclusive on both ends
* "*" adds all the links on the current page

## Next/Previous

On any numeric-index page navigation, the page being navigated *away from*, and the index used to do so, are saved for context. Then "previous" and "next" actions will use the links from that page before or after the saved index, respectively.

On any other nagivation, this context is cleared and next/previous actions won't function. This could include:
* "go <URL>" for any URL besides an integer index
* "up"
* "mark go <name>"
* any navigation via "tour"

## Marks

* named "m[ark]" instead of "bookmark" so "m" is used instead of interfering with "back/b"
* "mark a[dd] <name> <url>" adds a single mark. <name> can contain slashes to create a heirarchy
* "mark g[o] <name>" visits the given url
* "mark l[ist]" shows the list of marks
* "mark X" with a non-command argument defaults to "mark go X"

## Tour

* "t[our]" on it's own defaults to "tour next"
* "tour x y z", where x is not a valid command name, defaults to "tour add x y z"

* "tour a[dd]" allows any valid links as additional arguments - see "URL specifiers" above for details
* the variant "tour add n[ext] x y z" adds items next in the tour after the current position

* "tour next" visits the next link in the current tour
* "tour sh[ow]" prints the current tour and where we currently are
* "tour c[lear]" empties the current tour

* "tour l[ist]" lists the default tour and any non-empty named tours
* "tour p[revious]" goes back to the previous link in the tour
* "tour g[o] i" takes an index and jumps to that position in the tour

* "tour s[elect] x" takes a name to select *which* tour should become active - any unique prefix will work, but the precise name will be used if it doesn't match any existing tour
* without this name it re-selects the default tour
* the default tour is always active and empty upon startup
* the named tours have their state preserved upon any change to them

## Config file

The config file is located at XDG_DATA_HOME/x-1/config.toml. This is usually under .local/share in your home directory.

It has a "[main]" section with the following configuration options:
* quiet (bool): disables automatic printing of pages upon navigation. default "false"
* vim_keys (bool): whether to activate vim keybindings for the readline prompt. default "true"
* default_scheme (string): the URL scheme to use in the "go" command when none is provided. default "gemini"
* soft_wrap (int): the number of columns to wrap, or -1 to not add soft wrapping. default 72
* download_folder (string): path at which to store files saved by the "save" command. default $HOME

Then a "[handlers]" section contains mappings of mimetypes to shell commands which should be used to handle them.