5.5 KiB
OFFPUNK
A command-line, text-based and offline Gemini browser.
Focused on Gemini first but with some Gopher/web support available or projected, the goal of Offpunk is to be able to synchronise your content once (a day, a week, a month) and then browse it while staying disconnected.
Offpunk is a fork of the original AV-98 by Solderpunk and was originally only called AV-98-offline as an experimental branch.
Lightning introduction
You use the go
command to visit a URL, e.g. go gemini.circumlunar.space
. If xsel is installed, go will automatically fetch the URL from your clipboard.
Links in Gemini documents are assigned numerical indices. Just type an index to follow that link.
If a Gemini document is too long to fit on your screen, use the less
command
to pipe it to the less
pager.
Use add
to add a capsule to your bookmarks and bm
to show your bookmarks (which are stored in a file in you .config).
Use offline
to only browse cached content and online
to go back online.
Use the help
command to learn about additional commands.
When launched with the "--sync" option, offpunk will run non-interactively and fetch content from your bookmarks and content tentatively accessed while offline. New content found in your bookmarks will be added to your tour.
With "--sync", one could specify a "--cache validity" in seconds. This option will not refresh content if a cache exists and is less than the specified amount of seconds old.
For example, running
offpunk.py --sync --cache-validity 43200
will refresh your bookmarks if those are at least 12h old.
TODO
Known issues in the code:
-
WONTFIX: Sync is slow if you have bookmarks with lot of links that change very often.
-
FIXME0: Certificates error are not handled in --sync
-
FIXME1: consider root file is always index.gmi
-
FIXME2: offline web browser use os.system because it’s the only one that understands the ">> file.txt"
-
TODO: Update blackbox to reflect cache hits.
This fork is an experiment by Ploum (=> gemini://rawtext.club/~ploum ) to add offline capabilities to AV-98, including a persistent "tour" option.
See how I browse Gemini offline => gemini://rawtext.club/~ploum/2021-12-17-offline-gemini.gmi
In AV-98, use the commands "online" and "offline" to switch between offline/online. While offline, only content cached in .cache/av-98/ is accessed.
Use "av-98.py --sync" to build a cache containing your bookmarks and all links in your bookmarks. It might be quite slow the first time, be patient. You can also use the option "--cache-validity 3600" to only refresh cache which are at least 1h old (set the number of seconds according to your needs. If 0 or not set, cache-validity is considered as infinite).
Uncached ressources tentatively accessed offline will be accessed with the next --sync, including reload of already cached ressources. Already cached ressources might randomly be reloaded from time to time.
New ressources discovered in your bookmarks while --sync will be added to your tour. This means that if you have gemlogs in your bookmarks, any new posts in those will be added to your tour.
At the moment, caching only work for gemini:// ressources. gopher:// is not implemented and http(s):// ressources are sent to an "offline browser" (by default, None, nothing is done). It could be useful to, for example, send the http:// links to a text file in order to visit them while online.
Dependencies
Offpunk has no "strict dependencies", i.e. it will run and work without anything else beyond the Python standard library. However, it will "opportunistically import" a few other libraries if they are available to offer an improved experience.
- The ansiwrap library may result in neater display of text which makes use of ANSI escape codes to control colour.
- The cryptography library will provide a better and slightly more secure experience when using the default TOFU certificate validation mode and is highly recommended.
- Python magic is useful to determine the MIME type of cached object. If not present, the file extension will be used but some capsules provide wrong extension or no extension at all.
Features
- TOFU or CA server certificate validation
- Extensive client certificate support if an
openssl
binary is available - Ability to specify external handler programs for different MIME types
- Gopher proxy support (e.g. for use with Agena)
- Advanced navigation tools like
tour
andmark
(as per VF-1) - Bookmarks
- IPv6 support
- Supports any character encoding recognised by Python
RC files
You can use an RC file to automatically run any sequence of valid AV-98
commands upon start up. This can be used to make settings controlled with the
set
or handler
commanders persistent. You can also put a go
command in
your RC file to visit a "homepage" automatically on startup, or to pre-prepare
a tour
of your favourite Gemini sites.
The RC file should be called av98rc
. AV-98 will look for it first in
~/.av98/
and second in ~/.config/av98/
. Note that either directory might
already exist even if you haven't created it manually, as AV-98 will, if
necessary, create the directory itself the first time you save a bookmark (the
bookmark file is saved in the same location). AV-98 will create
~/.config/av98
only if ~/.config/
already exists on your system, otherwise
it will create ~/.av98/
.