💾 Archived View for gemini.ctrl-c.club › ~spookman › gbrowse › README.gmi captured on 2023-06-16 at 19:45:40. Gemini links have been rewritten to link to archived content

-=-=-=-=-=-=-

Vim GBrowse

A vim plugin for the browsing of Gopher and Gemini.

Dependencies

openssl
curl
Some other posix core utils such as mkdir and echo

Installation

It is recommended that you use a plugin manager. I use pathogen, so I just put the `gbrowse` directory in the `bundle` directory. Follow the intructions for whatever plugin manager you use. If you don't use a plugin manager, you probably know what to do anyway, so do it.

Usage

Once GBrowse has been loaded by vim, any file names starting with `gopher://` or `gemini://` will be downloaded and displayed (assuming they are valid URLs).

Bookmarks

GBrowse has a simple but effective bookmarking system.

`g:gbrowse_bookmarks_file` - default `$HOME/.gbrowse_bookmarks` - This is where your bookmarks are stored
Use the `GBrowseBookmark` command to add the current page to your bookmarks. You will be prompted to add a description.
Use the `GBrowseBookmarks` command to open a new tab displaying your bookmarks file. It is formatted in gemtext, and your bookmarks can be accessed like normal links.
While viewing your bookmarks, use the `GBrowseEdit` command to "unformat" the file, and enable editing. This allows you to reorder your bookmarks, add headings etc. The file will be reformatted when you save (`:w`).
New bookmarks are added to the end of the file.

Display

For Gopher and Gemini pages, GBrowse will format the page. The default formatting options are designed to be as portable as possible, It is recommended that you set these in your .vimrc for a more pleasant experience (HINT: `:dig!` will display the special characters available to your vim!).

Icons for gemini bullets, quotes and lists

`g:gbrowse_gemini_bullet` - default `*`
`g:gbrowse_gemini_quote` - default `> `
`g:gbrowse_gemini_link` - default `=>`

Icons to use to draw boxes around gemini preformatted text

`g:gbrowse_gemini_box_h` - default `-`
`g:gbrowse_gemini_box_v` - defualt `|`
`g:gbrowse_gemini_box_tl` - default `-`
`g:gbrowse_gemini_box_tr` - default `+`
`g:gbrowse_gemini_box_bl` - default `+`
`g:gbrowse_gemini_box_br` - default `+`

GBrowse can optionally pretty-print certain info using figlet

`g:gbrowse_use_figlet` - default 0 (change to 1 to use figlet)
`g:gbrowse_gemini_heading_font` - default `smmono9.tlf`
`g:gbrowse_gemini_subheading_font` - default `smblock.tlf`
`g:gbrowse_gemini_subsubheading_font` - default `wideterm.tlf`
`g:gbrowse_gemini_error_code_font` - default `bigmono12.tlf`
`g:gbrowse_error_message_font` - default `smmono9r.,tlf`

Size of page margin in spaces

`g:gbrowse_margin` - default 6

Dictionary for Gopher link types

`g:gbrowse_gopher_link_displays` - default empty `{}`. Add items like `{ "i": " ", "1": "=>" }` (this will make info lines display with no character at the start, and links display like Gemini links).

History

Pages you visit are automatically logged to the history file, with the date and time.

`g:gbrowse_history_file` - default `$HOME/.gbrowse_history` - This is where your history is stored. If you would like GBrowse to not store your history at all, set this to `/dev/null`.
Use the `GBrowseHistory` command to open a tab containing your history.
While viewing your history, use the `GBrowseEdit` command to "unformat" the file, and enable editing. This can be used to clear specific items from your history. The file will be reformatted when you save (`:w`). Clearing your history will reset any logs you subscribe to, and all entries will be considered unread.

Navigation

All vim mappings work the same as normal, with the exception of `gf` (and `CTRL-w gf`), which (for Gemini/Gopher files) open the link on the current line, no matter where the cursor is on that line (default behaviour would be to open whatever file is directly under the cursor).
For Gemini pages, opening a new file is generally treated as a relative link (this is required for proper Gemini navigation). i.e. if the open page is `gemini://gemini.circumlunar.space:1965` and you enter `:e docs`, you will be taken to `gemini://gemini.circumlunar.space:1965/docs`.
The exception to the above is if there is a local (and readable) file with the name. GBrowse will prefer the local file.
If you wish to create a new file, and not have GBrowse request a page with that name from the server that provided the current page, first open an empty buffer (`:e` or `:tabe`), from where you can again open and create normal buffers.
As files are loaded into their own buffers, vim's buffer list functions as a history (it can be viewed with `:ls`, and a numbered buffer can be loaded with `:b` followed by the buffer number).
`:e #` loads the previous buffer (similar to a browser's back button), while `:e %` reloads the current buffer.
`:w` can be used to save a local copy of the page

Other file types

Some sites contain files, such as images, that are not displayable in vim. GBrowse allows you to select how these files are handled:

`g:gbrowse_gopher_file_handlers` - default empty `{}` - Add items like `{ "I": "feh" }` to open image links using feh
`g:gbrowse_gemini_file_handlers` - default empty `{}` - Add items like `{ "image/jpeg": "feh"}` to open files with the mimetype `image/jpeg` using feh
`g:gbrowse_default_file_handler` - default "xdg-open" - If there is no specified handler in the dictionaries above, this command will be used to open the file.

Subscribing to logs

_Currently, only Gemlog subscriptions are supported, I couldn't find any info on the format of Phlogs. Please contact me if you have any info and I'll implement it_

GBrowse keeps a file, like it does for bookmarks, to manage subscriptions.

`g:gbrowse_subscription_file` - default `$HOME/.gbrowse_subscriptions` - This is where your subscriptions are stored
Use the `GBrowseSubscribe` command to add the current page to your subscriptions (the current page must be the menu page, which has links labelled with dates).
Use the `GBrowseSubscriptions` command to display your subscriptions file.
Use the `GBrowseFetch` command to check for any new entries on pages you have subscribed to. Unread entries will be listed as bullets, and there will be a link to the log page.
Use the `GBrowseMarkRead` command while a log menu page is loaded to update the "Last Read" time for that page to the current time. This will clear anyunread entries in your subscription file for that log (presuming all entries are in the past).
While viewing your subscriptions, use the `GBrowseEdit` command to "unformat" the file, and enable editing. This allows you to reorder your subscriptions, add headings etc. The file will be reformatted when you save (`:w`). Bullet points are automatically generated. Removing bulletted lines may affect the operation of the subscriptions, and bulletted lines you add may be removed without warning.

GBrowse keeps a table of contents for gemini files, containing headings from thoughout the file.

The table of contents can be viewed with the `GBrowseTOC` command.
To jump to a heading, use the `GBrowseJump` command, using either the chapter number listed by TOC or the chapter title
Pressing tab after typing some characters will autocomplete chapter numbers or titles

TLS Certificates

When loading a Gemini page, GBrowse uses a Trust On First Use (TOFU) policy. This means that the first time you visit a site, we assume that the certificate provided is legitimate. We store it, and if next time a different certificate is provided, we treat that as a malicious attack, and end the transaction.

`g:gbrowse_acceptable_openssl_errors` - default `[18]`. Any openssl error codes will cause the connection to be closed unless they are listed here. 18 is included by default, as self-signed certificates are common in Gemini space.
`g:gbrowse_server_certs` - default `$HOME/.gbrowse_server_certs/` allows you to select where GBrowse stores server certificates.
If you wish to access a server that has failed validation, you can force GBrowse to accept the new certificate by deleting the old one from this directory.

If you wish (or are required) to use a client certificate, use the `GBrowseUseCert` command to set the certificate to use (tab will autocomplete file names).

Sample setup

This is my settings from my `.vimrc`. If all of these characters display on your system and you have figlet on your path, I suggest trying these settings if you don't feel like experimenting with your own.

let g:gbrowse_use_figlet=1
let g:gbrowse_gemini_bullet="○"
let g:gbrowse_gemini_quote="░ "
let g:gbrowse_gemini_link="⇒"
let g:gbrowse_gemini_box_h="─"
let g:gbrowse_gemini_box_v="│"
let g:gbrowse_gemini_box_tl="┌"
let g:gbrowse_gemini_box_tr="┐" 
let g:gbrowse_gemini_box_bl="└"
let g:gbrowse_gemini_box_br="┘"
let g:gbrowse_gopher_link_displays=get(g:,'g:gbrowse_gopher_link_displays', {"i": " ","0":"▨", "1": "⇒", "3": "✗", "I": "□", "S": "♪", "<": "♫"})

This is my bookmarks file, note how I've added some headings, and the `### Uncategorised` heading at the end (as new bookmarks will be added under there).

## Spookman's bookmarks

### Certificates & security
=> gemini://gemini.susa.net:1965/openssl_cheats.gmi Openssl cheatsheet
=> gemini://makeworld.space:1965/gemlog/2020-07-06-openssl.gmi Openssl commands
=> gemini://makeworld.space:1965/gemlog/2020-07-03-tofu-rec.gmi TOFU explanation
=> gemini://gemini.circumlunar.space:1965/docs/specification.gmi Gemini spec

### General
=> gopher://floodgap.com:70 Floodgap
=> gemini://gemini.circumlunar.space:1965/ Circumlunar

### Uncategorised