1 files changed, 74 insertions, 0 deletions
diff --git a/README.gmi b/README.gmi
new file mode 100644
index 0000000..13175ca
--- /dev/null
+++ b/README.gmi
@@ -0,0 +1,74 @@
+# X-1: fly around the small web at the speed of sound
+
+## 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 is "go", so just putting an integer or URL in the command bar goes there.
+
+* 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]: back in history
+* f[orward]: 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)
+* p[revious]: 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
+* l[ess]: pipe the current page's content through less(1)
+* |<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] [<command>]: show a help screen, optionally the one about a specific command
+* m[ark]: bookmarks, see below
+* t[our]: tours, seee below
+
+## 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] <url> <name>" adds a single mark. <name> can contain slashes to create a heirarchy
+* "mark g[o] <name>" visits the given url
+* "mark l[s]" 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 arguments including both integer indices and absolute or relative URLs
+* additional URL specifiers specific to "tour add" are "x-y" which expands to the integer range between x and y (inclusive on both ends), and "*" meaning everything on the current page
+* the variant "tour add n[ext] x y z" adds its items to the next position in the tour, before anything else that was still to come
+
+* "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[s]" lists the default tour and any non-empty letter tours
+* "tour p[revious]" goes back to the previous link in the tour
+* "tour g[o]" takes an index and jumps to that position in the tour
+
+* "tour s[et]" takes a single lower-case alphabetic character to select *which* tour should become active
+* without this letter, it re-selects the default tour
+* the default tour is the empty one. it is always active and empty upon startup
+* the other letter-identified tours have their state preserved when the program exits