General Information
Stubb is a [gopher] client for the [terminal]. The application functions by printing gopher content to the terminal scrollback buffer, similar to using cat to output the contents of a file. Stubb listens for keypress events to control what actions it takes: navigate to a url, follow a link, write to file, open a new tab, forward, back, and pipe the output to a reader/pager (defaults to less). Stubb is written in Lua and has one outside dependency that can be acquired via [LuaRocks], Lua's package manager (more details in the [building] section).
Background
Stubb is named for the character [Stubb from Moby Dick], known for his imaginative patter and good humor. This client came about with a desire for a fast and very lightweight gopher client that was still feature rich. As a result, Lua was chosen as the language (for its speed) and Stubb was given the following features: bookmarks, tabs, piping, and (for privacy) history that only remains for the session (and is cleared on quit).
Quick Start
Once installed on a system and included in the system path, a user can start the application by typing stubb into their terminal and pressing enter.
At this point you will see the command bar appear. The command bar shows you what keys to press to get help and to quit as well as what tab you are on and where in the history of that tab you are.
To visit a gopher holetype gu, for go to url. You will be prompted for the URL. Once the content loads you car read it there or type pr for pipe to reader; which will try to open the content in a pager. Links can be followed with gl, for go to link; you will then be prompted for the link id, which will be visible in the content.
To go forward or backward in history you can press b for back or f for forward.
That should get you started using Stubb at a basic level. There are many more options and features. Please read the [Documentation] section to find out more.
Documentation
Gopher Support
Gopher is the sole protocol supported by Bombadillo at this time. Gopher types are implemented in a 4 tier fashion:
- Gophermaps are supported with all classic/standardized features
- Text documents are supported by being printed to the terminal scrollback buffer or piped to a reader
- Search is partially supported via a default search engine
- All other types (images, binaries, etc) are implemented as downloads
Hot Keys
Stubb is controlled via hot keys. Hot keys get combined in sequence with other hot keys to perform simple or complex actions.
Key Series | Action | ||||
---|---|---|---|---|---|
a b | bookmark | ||||
a t | add tab | ||||
b | back | ||||
c | clean the screen | ||||
d w | delete bookmark | ||||
d t | delete tab | ||||
f | forward | ||||
g b | go to bookmark | ||||
g l | go to link | ||||
g t | go to tab | ||||
g u | go to url | ||||
h | help | ||||
l b | list bookmark | ||||
l t | list tab | ||||
p d c | pipe to disk: current | ||||
p d l | pipe to disk: link | ||||
p r c | pipe to reader: current | ||||
p r l | pipe to reader: link | ||||
p t c | pipe to tab: current | ||||
p | pipe to tab: link | ||||
q | quit stubb | ||||
r | reload current page | ||||
s | search | ||||
u | update bookmark title |
Misc Information
When a gophermap is loaded, links will be enumerated. Pressing G and then l will prompt you for what link you would like to follow. Links are always based on the most recently loaded url for your current tab.
File save is always based out of the home directory of the user that launched Stubb.
Getting Stubb
Stubb is written in the programming language [Lua]. Since Lua is a scripting language it does not compile to binary files. As such, users will need to have Lua running on their system. Stubb has been tested with Lua versions >= 5.1.
If the system Stubb is intended to run on does not have Lua installed (run 'lua' in the terminal to find out), it can be acquired from the Lua [downloads page]. While you are at it, you may as well get [LuaRocks] as well.
Luasocket is required. It can be acquired via luarocks with: `luarocks install luasocket`. You can also get Luasocket from its [git repo]. Using luarocks is recommended as the easier option.
That should take care of dependencies. You just need to make sure that stubb, found in [this repo], is executable and on your path and you are good to go.
Links To Places Near and Far
If you are new to gopher, or the larger terminal based internet, this section is included to guide you to some points of interest. Full disclosure, a number of the below items are built by or administered by the developer(s) of Stubb (bombadillo, burrow, colorfield.space)
Gopher Clients
There are lots of gopher clients out there. Try a few and see which is a good fit for your workflow. Here are a few to get you started:
- Bombadillo Another terminal based client from the creator of Stubb. Bombadillo is a full screen terminal application/pager with vimlike key bindings.
- VF-1 A great client that works similarly to, and was the inspiration for, Stubb. Try both flavors!
- Burrow A graphical client that is more similar to the web browsers most users are likely accustomed to. It only works properly on linux (it will run on OSX, but will not look as nice and some features will not work).
- Lynx A classic web browser for the terminal that still supports gopher and is available for most systems.
Public Access *nix Servers
Public access *nix systems are often great places for community in the text/terminal based internet. Many provide gopher hosting for free and can be a solid way to get your feet wet with your own gopher hole.
- Circumlunar Space On the smaller side, but with a few different federated servers. CS offers gopher hosting, irc, chat, bulletin board, and a great user community.
- SDF A behemoth that has stood the test of time (many decades). SDF has a very large userbase, which has pros and cons. Gopher hosting is offered, along with games, chat, bulletin board, e-mail, and more.
- Rawtext.club Gopher hosting, web hosting, experimental tooling and creative userbase, internal blogging in the shell (shlog), e-mail, chat.
- Colorfield Space[gopher] Experimental shell hosted on a Raspberry Pi Zero. Correspondence gaming, chat, bulletin board, gopher hosting.
Gopher Holes To Visit
Links to various gopher holes have been included in order to give the user some places to visit with Bombadillo, or any other gopher client. Do not that regular web browsers will not usually load the following links, you will need to copy the address and enter it into a gopher client.
- Cosmic Voyage is a place for users to read and write science fiction stories. They also offer shell accounts to facilitate said sharing.
- Gopherpedia is a gopher version of wikipedia.
- Bongusta is a phlog (gopher's version of blogging) aggregator. Find lots of great places from here.
- Pubnix History Project collects information of public accerss *nix systems. Find a new home on the internet or research the old days.
- Gopher Black is the home of Tomasino, a very active gopher and *nix user. Lots of great links and posts to be read here.