add README and LICENSE

1 files changed, 124 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..924a1f3
--- /dev/null
+++ b/README.md
@@ -0,0 +1,124 @@
+   gophed: burrowing the gopherspace with ed
+===============================================
+
+`gophed` is a simple gopher client in a POSIX shell script. `gophed`
+uses ed(1) as a pager and navigator, and is based on an original idea of
+an ed-based client by Solene Rapenne (gopher://bitreich.org/1/usr/solene/).
+
+`gophed` is distributed under the ISC License. A copy of the LICENSE is
+available in the repo.
+ 
+The first time you run `gophed` you need to initialise it via:
+
+  ./gophed -i
+
+This will create a few symlinks in the current folder, namely `g`, `v`,
+and `d`,  which will be used as `gophed` commands. Once `gophed` has
+been initialised, you can start visiting some gopherholes:
+
+  ./gophed / kalos.mine.nu 70
+
+or equivalently:
+
+  ./v / kalos.mine.nu 70
+
+This command will download the corresponding resource, and print it on
+output with line numbers. An excerpt is reported below:
+
+...
+15      i+------------------------------------------+   Err     kalos.mine.nu   70
+16      i    Welcome to kalos.mine.nu Gopher-hole       Err     kalos.mine.nu   70
+17      i+------------------------------------------+   Err     kalos.mine.nu   70
+18      0 About me      /me.txt kalos.mine.nu   70
+19      0 About this gopherhole /about.txt      kalos.mine.nu   70
+20      1 Contacts      /contacts       kalos.mine.nu   70
+21      i                       Err     kalos.mine.nu   70
+22      1 My gopherhole @SDF    /users/katolaz  sdf.org 70
+23      1 My gopherhole @republic.circumlunar.space     /~katolaz/      republic.circumlunar.space      70
+24      1 My Phlog @republic.circumlunar.space  /~katolaz/phlog republic.circumlunar.space      70
+25      i+------------------------------------------+   Err     kalos.mine.nu   70
+26      i                  Projects                     Err     kalos.mine.nu   70
+27      i+------------------------------------------+   Err     kalos.mine.nu   70
+28      1 Burrow the Burrows (crawling the Gopherspace) /burrow/index.gph       kalos.mine.nu   70
+29      1 gosher -- a Gopher server in a shell script   /software/gosher        kalos.mine.nu   70
+...
+=
+
+The final "=" is the `gophed` default prompt. No need to say that you
+can change the default prompt to any single character by changing the
+PROMPT variable. Now, if you want to visit the selector at line 23, you
+would type:
+
+  !./g % 24 [ENTER]
+
+at the prompt. This will effectively spawn another `gophed` instance,
+telling it to get the selector at line 23 in the current document, and
+to load the corresponding resource. In this case we will have something
+like:
+
+1       i    ________            ____                                           Err     republic.circumlunar.space      70
+2       i   /_  __/ /_  ___     / __ \_      ______ _______   _____  ____       Err     republic.circumlunar.space      70
+3       i    / / / __ \/ _ \   / / / / | /| / / __ `/ ___/ | / / _ \/ __ \      Err     republic.circumlunar.space      70
+4       i   / / / / / /  __/  / /_/ /| |/ |/ / /_/ / /   | |/ /  __/ / / /      Err     republic.circumlunar.space      70
+5       i  /_/ /_/ /_/\___/  /_____/ |__/|__/\__,_/_/    |___/\___/_/ /_/       Err     republic.circumlunar.space      70
+6       i       Err     republic.circumlunar.space      70
+7       i         ____  __           __                  _ __  __       Err     republic.circumlunar.space      70
+8       i        / __ )/ /___ ______/ /___________ ___  (_) /_/ /_      Err     republic.circumlunar.space      70
+9       i       / __  / / __ `/ ___/ //_/ ___/ __ `__ \/ / __/ __ \     Err     republic.circumlunar.space      70
+10      i      / /_/ / / /_/ / /__/ ,< (__  ) / / / / / / /_/ / / /     Err     republic.circumlunar.space      70
+11      i     /_____/_/\__,_/\___/_/|_/____/_/ /_/ /_/_/\__/_/ /_/      Err     republic.circumlunar.space      70
+12      i       Err     republic.circumlunar.space      70
+13      i+------------------------------------------------------------------+   Err     republic.circumlunar.space      70
+14      i   "their swords were forged by dwarves, in the mists of time..."      Err     republic.circumlunar.space      70
+15      i+------------------------------------------------------------------+   Err     republic.circumlunar.space      70
+16      i       Err     republic.circumlunar.space      70
+17      0 About this phlog      /~katolaz/phlog/about.txt       republic.circumlunar.space      70
+18      i       Err     republic.circumlunar.space      70
+.....
+26      i+------------------------------------------------------------------+   Err     republic.circumlunar.space      70
+27      1 << Back to my gopherhole      /~katolaz/      republic.circumlunar.space      70
+28      .
+=
+
+Well, if you want now to go to the resource at line 17, you would type: 
+
+  !./g % 17 [ENTER]
+
+when you are done with viewing the current resource, you just type:
+
+  q [ENTER]
+
+at the `gophed` prompt (well, that one is indeed ed(1) prompt...), and
+you will be back at the gopher resources you had visited before. Typing 
+
+  q [ENTER]
+
+again will bring you back in history again. If you give a `q` command on
+the first page, you will leave `gophed`. If you would instead like to
+save the resource pointed by a selector, you will use the command:
+
+  !./d % NUMBER [ENTER]
+
+where NUMBER is the number of the line where the selector appears in the
+current page. The resource will be saved at "HOSTNAME/URI" where
+HOSTNAME is the name of the host and URI is the path to the resource.
+If you don't remember which line is which, you can just give:
+
+  %n [ENTER]
+
+at the prompt. If you don't remember which resource you are currently
+visiting, typing: 
+
+ f [ENTER]
+
+at the `gophed` prompt will give some hints. If you are an ed(1) user,
+you will totally understand what we are up to here, and probably will
+now have a good laugh. If you don't know how to use ed(1), instead, then
+this is probably the right time to start learning it. Remember: ed(1) is
+the standard editor, and an awesome one at that...
+
+HND
+
+KatolaZ
+
+