gemini - kennedy.gemi.dev

💾 Archived View for gem.sdf.org › oak3 › files › man.bombadillo.gmi captured on 2023-04-26 at 13:29:15. Gemini links have been rewritten to link to archived content

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

bombadillo(1) General Operation Manual bombadillo(1)

NAME

bombadillo - a non-web browser

SYNOPSIS

bombadillo [options] [url]

DESCRIPTION

bombadillo is a non-web browser for the terminal. It features a full

terminal user interface, vim-like keybindings, document pager, config‐

urable settings, and a robust command selection.

bombadillo supports the following protocols as first class citizens:

gopher, gemini, finger, and local (a user’s file system). Support for

telnet, http and https is also available via integration with third

party applications.

OPTIONS

-h Display usage help and exit. Provides a list of all command

line options with a short description and exits.

-t Set the window title to 'Bombadillo'. Can be used in a GUI en‐

vironment, however not all terminals support this feature.

-v Display version information and exit.

PROTOCOL SUPPORT

All of the below protocols are supported. With the exception of go‐

pher, the protocol name must be present as the scheme component of a

url in the form of [protocol]://[the rest of the url].

gopher Gopher is the default protocol for bombadillo. Any textual item

types will be visited and shown to the user and any non-text

types will be downloaded. Type 7 (querying) is fully supported.

As the default protocol, any url that is not prefixed with the

scheme section of a url (gopher:// for example) will be treated

as gopher urls.

gemini Gemini is supported, but as a new protocol with an incomplete

specification, features may change over time. At present Bom‐

badillo supports TLS with a trust on first use certificate pin‐

ning system (similar to SSH). Gemini maps and other text types

are rendered in the browser and non-text types will be down‐

loaded.

finger Basic support is provided for the finger protocol. The format

is: finger://[[username@]][hostname]. Many servers still sup‐

port finger and it can be fun to see if friends are online or

read about the users whose phlogs you follow.

local Local is similar to the file protocol used in web browsers or

the like, with a smaller set of features. Users can use the lo‐

cal scheme to view files on their local system. Directories are

supported as viewable text object as well as any files. Wild‐

cards and globbing are not supported. Using ~ to represent a

user's home directory, as well as relative paths, are sup‐

ported. The color theme has no effect on this protocol and all

terminal escape sequences will be rendered to the screen liter‐

ally.

telnet Telnet is not supported directly, but addresses will be fol‐

lowed and opened as a subprocess by whatever telnet client a

user sets in their settings (defaulting to telnet). In some

cases this behavior may be buggy.

http, https

Neither of the world wide web protocols are supported directly.

bombadillo can be configured to open web links in a user's de‐

fault graphical web browser. It is also possible to display web

content directly in bombadillo using lynx, w3m, or elinks ter‐

minal web browsers to render pages. Opening http/https links is

opt-in only, controlled by the webmode setting.

Opening links in a default graphical web browser will only work

in a GUI environment.

Displaying web content directly in bombadillo requires lynx,

w3m or elinks terminal web browsers are installed on the sys‐

tem.

COMMANDS

KEY COMMANDS

These commands work as a single keypress anytime bombadillo is not

taking in a line based command or when the user is being prompted for

action. This is the default command mode of bombadillo.

b, h Navigate back one place in your document history.

B Toggle the bookmarks panel open/closed.

d Scroll down an amount corresponding to 75% of your terminal

window height in the current document.

f, l Navigate forward one place in your document history.

g Scroll to the top of the current document.

G Scroll to the bottom of the current document.

j Scroll down a single line in the current document.

k Scroll up a single line.

n Jump to next found text item.

N Jump to previous found text item.

q Quit bombadillo.

R Reload the current page (does not destroy forward history).

1, 2, 3, 4, 5, 6, 7, 8, 9, 0

Quick navigation to the first 10 links on a page. The 0 key

will navigate to the link numbered '10', all other numbers nav‐

igate to their matching link number.

u Scroll up an amount corresponding to 75% of your terminal win‐

dow height in the current document.

/ Search for text within current document. / followed by a text

query will highlight and allow navigation of found text. / with

an empty query will clear the current query.

<tab> Toggle the scroll focus between the bookmarks panel and the

document panel. Only has an effect if the bookmarks panel is

open.

<spc> Enter line command mode. Once a line command is input, the mode

will automatically revert to key command mode.

: Alias for <spc>. Enter line command mode.

LINE COMMANDS

These commands are typed in by the user to perform an action of some

sort. As listed in KEY COMMANDS, this mode is initiated by pressing :

or <space>. The command names themselves are not case sensitive,

though the arguments supplied to them may be.

[url] Navigates to the requested url.

[link id]

Follows a link on the current document with the given number.

add [url] [name...]

Adds the url as a bookmarks labeled by name. a can be used in‐

stead of the full add.

add [link id] [name...]

Adds the url represented by the link id within the current doc‐

ument as a bookmark labeled by name. a can be used instead of

the full add.

add . [name...]

Adds the current document's url as a bookmark labeled by name.

a can be used instead of the full add.

bookmarks

Toggles the bookmarks panel open/closed. Alias for KEY COMMAND

B. b can be used instead of the full bookmarks.

bookmarks [bookmark id]

Navigates to the url represented by the bookmark matching book‐

mark id. b can be entered, rather than the full bookmarks.

check [link id]

Displays the url corresponding to a given link id for the cur‐

rent document. c can be used instead of the full check.

check [setting name]

Displays the current value for a given configuration setting. c

can be used instead of the full check.

delete [bookmark id]

Deletes the bookmark matching the bookmark id. d can be used

instead of the full delete.

help Navigates to the gopher based help page for bombadillo. ? can

be used instead of the full help.

home Navigates to the document set by the homeurl setting. h can be

entered, rather than the full home.

jump Navigates to the previous page in history from the current

page. Useful for keeping the current page in your history while

still browsing. j can be used instead of the full jump.

jump [history location]

Navigates to the given history location. The history location

should be an integer between 0 and 20. j can be used instead of

the full jump.

purge *

Deletes all pinned gemini server certificates. p can be used

instead of the full purge.

purge [host name]

Deletes the pinned gemini server certificate for the given

hostname. p can be used instead of the full purge.

quit Quits bombadillo. Alias for KEY COMMAND q. q can be used in‐

stead of the full quit.

reload Requests the current document from the server again. This does

not break forward history the way entering the url again would.

r can be used instead of the full reload.

search Queries the user for search terms and submits a search to the

search engine set by the searchengine setting.

search [keywords...]

Submits a search to the search engine set by the searchengine

setting, with the query being the provided keyword(s).

set [setting name] [value]

Sets the value for a given configuration setting. s can be used

instead of the full set.

version

Shows the current Bombadillo version number.

write .

Writes the current document to a file. The file is named by the

last component of the url path. If the last component is blank

or / a default name will be used. The file saves to the direc‐

tory set by the savelocation setting. w can be entered rather

than the full write.

write [url]

Writes data from a given url to a file. The file is named by

the last component of the url path. If the last component is

blank or / a default name will be used. The file saves to the

directory set by the savelocation setting. w can be entered

rather than the full write.

write [link id]

Writes data from a given link id in the current document to a

file. The file is named by the last component of the url path.

If the last component is blank or / a default name will be

used. The file saves to the directory set by the savelocation

setting. w can be entered rather than the full write.

FILES

bombadillo keeps a hidden configuration file in a user's XDG configu‐

ration directory. The file is a simplified ini file titled .bom‐

badillo.ini. It is generated when a user first loads bombadillo and is

updated with bookmarks and settings as a user adds them. The file can

be directly edited, but it is best to use the SET command to update

settings whenever possible. To return to the state of a fresh install,

simply remove the file and a new one will be generated with the bom‐

badillo defaults. On some systems an administrator may set the config‐

uration file location to somewhere other than the default setting. If

you do not see the file where you expect it, or if your settings are

not being read, try :check configlocation to see where the file should

be, or contact your system administrator for more information.

SETTINGS

The following is a list of the settings that bombadillo recognizes, as

well as a description of their valid values.

configlocation

The path to the directory that the .bombadillo.ini configura‐

tion file is stored in. This is a read only setting and cannot

be changed with the set command, but it can be read with the

check command.

defaultscheme

The scheme that should be used when no scheme is present in a

given URL. gopher, gemini, http, and https are valid values.

geminiblocks

Determines how to treat preformatted text blocks in text/gemini

documents. block will show the contents of the block, alt will

show any available alt text for the block, both will show both

the content and the alt text, and neither will show neither.

Unlike other settings, a change to this value will require a

fresh page load to see the change.

homeurl

The url that bombadillo navigates to when the program loads or

when the home or h LINE COMMAND is issued. This should be a

valid url. If a scheme/protocol is not included, gopher will be

assumed.

savelocation

The path to the directory that bombadillo should write files

to. This must be a valid filepath for the system, must be a di‐

rectory, and must already exist.

searchengine

The url to use for the LINE COMMAND search. Should be a valid

search path that terms may be appended to.

telnetcommand

Tells the browser what command to use to start a telnet ses‐

sion. Should be a valid command, including any flags. The ad‐

dress being navigated to will be added to the end of the com‐

mand.

theme Can toggle between visual modes. Valid values are normal,

color, and inverse. When set to inverse, the normal mode colors

are inverted. Both normal and inverse modes filter out terminal

escape sequences. When set to color, Bombadillo will render

terminal escape sequences representing colors when it finds

them in documents.

timeout

The number of seconds after which connections to gopher or gem‐

ini servers should time out if the server has not responded.

webmode

Controls behavior when following web links. The following val‐

ues are valid: none will disable following web links, gui will

have the browser attempt to open web links in a user's default

graphical web browser; lynx, w3m, and elinks will have the

browser attempt to use the selected terminal web browser to

handle the rendering of web pages and will display the pages

directly in Bombadillo.

BUGS

There are very likely bugs. Many known bugs can be found in the issues

section of bombadillo's source code repository (see links).

LINKS

bombadillo maintains a presence in the following locations:

Source Code Repository

https://tildegit.org/sloum/bombadillo

Web Homepage

http://bombadillo.colorfield.space

Gopher Homepage

gopher://bombadillo.colorfield.space

AUTHORS

bombadillo was primarily developed by sloum, with kind and patient as‐

sistance from ~asdf and jboverf.

27 OCT 2019 bombadillo(1)