bombadillo/bombadillo.1

305 lines
14 KiB
Groff
Raw Permalink Normal View History

2019-10-27 18:09:45 +00:00
.TH "bombadillo" 1 "27 OCT 2019" "" "General Operation Manual"
.SH NAME
\fBbombadillo \fP- a non-web browser
.SH SYNOPSIS
.nf
.fam C
\fBbombadillo\fP [\fIoptions\fP] [\fIurl\fP]
.fam T
.fi
.SH DESCRIPTION
\fBbombadillo\fP is a non-web browser for the terminal. It features a full terminal user interface, vim-like keybindings, document pager, configurable settings, and a robust command selection.
2019-11-13 03:22:45 +00:00
.TP
\fBbombadillo\fP supports the following protocols as first class citizens: gopher, gemini, finger, and local (a users file system). Support for telnet, http and https is also available via integration with third party applications.
.SH OPTIONS
.TP
.B
\fB-h\fP
Display usage help and exit. Provides a list of all command line options with a short description and exits.
.TP
.B
\fB-t\fP
Set the window title to 'Bombadillo'. Can be used in a GUI environment, however not all terminals support this feature.
.TP
.B
\fB-v\fP
Display version information and exit.
2019-10-12 21:52:51 +00:00
.SH PROTOCOL SUPPORT
All of the below protocols are supported. With the exception of gopher, the protocol name must be present as the scheme component of a url in the form of \fI[protocol]://[the rest of the url]\fP.
.TP
.B
gopher
Gopher is the default protocol for \fBbombadillo\fP. 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 (\fIgopher://\fP for example) will be treated as gopher urls.
.TP
.B
gemini
Gemini is supported, but as a new protocol with an incomplete specification, features may change over time. At present Bombadillo supports TLS with a trust on first use certificate pinning system (similar to SSH). Gemini maps and other text types are rendered in the browser and non-text types will be downloaded.
2019-10-12 21:52:51 +00:00
.TP
.B
finger
Basic support is provided for the finger protocol. The format is: \fIfinger://[[username@]][hostname]\fP. Many servers still support finger and it can be fun to see if friends are online or read about the users whose phlogs you follow.
2019-10-12 21:52:51 +00:00
.TP
.B
local
2019-12-14 15:37:56 +00:00
Local is similar to the \fIfile\fP protocol used in web browsers or the like, with a smaller set of features. Users can use the local scheme to view files on their local system. Directories are supported as viewable text object as well as any files. Wildcards and globbing are not supported. Using \fI~\fP to represent a user's home directory, as well as relative paths, are supported. The \fIcolor\fP theme has no effect on this protocol and all terminal escape sequences will be rendered to the screen literally.
2019-10-12 21:52:51 +00:00
.TP
.B
telnet
Telnet is not supported directly, but addresses will be followed and opened as a subprocess by whatever telnet client a user sets in their settings (defaulting to \fItelnet\fP). In some cases this behavior may be buggy.
.TP
.B
http, https
Neither of the world wide web protocols are supported directly. \fBbombadillo\fP can be configured to open web links in a user's default graphical web browser. It is also possible to display web content directly in \fBbombadillo\fP using lynx, w3m, or elinks terminal web browsers to render pages. Opening http/https links is opt-in only, controlled by the \fIwebmode\fP setting.
.IP
Opening links in a default graphical web browser will only work in a GUI environment.
.IP
Displaying web content directly in \fBbombadillo\fP requires lynx, w3m or elinks terminal web browsers are installed on the system.
.SH COMMANDS
.SS KEY COMMANDS
2019-12-01 02:17:03 +00:00
These commands work as a single keypress anytime \fBbombadillo\fP is not taking in a line based command or when the user is being prompted for action. This is the default command mode of \fBbombadillo\fP.
.TP
.B
b, h
Navigate back one place in your document history.
.TP
.B
B
Toggle the bookmarks panel open/closed.
.TP
.B
d
Scroll down an amount corresponding to 75% of your terminal window height in the current document.
.TP
.B
f, l
Navigate forward one place in your document history.
.TP
.B
g
Scroll to the top of the current document.
.TP
.B
G
Scroll to the bottom of the current document.
.TP
.B
j
Scroll down a single line in the current document.
.TP
.B
k
Scroll up a single line.
.TP
.B
2020-01-04 19:19:01 +00:00
n
Jump to next found text item.
.TP
.B
N
2020-01-04 19:19:01 +00:00
Jump to previous found text item.
.TP
.B
q
Quit \fBbombadillo\fP.
.TP
.B
2019-10-12 21:52:51 +00:00
R
2019-12-01 02:17:03 +00:00
Reload the current page (does not destroy forward history).
2019-10-12 21:52:51 +00:00
.TP
.B
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 navigate to their matching link number.
.TP
.B
2021-04-24 21:26:33 +00:00
U
Move up a level in the current url path. \fI/mydir/mysubdir/myfile.txt\fP would become \fI/mydir/mysubdir/\fP, and so on.
.TP
.B
u
Scroll up an amount corresponding to 75% of your terminal window height in the current document.
.TP
.B
2020-01-04 19:19:01 +00:00
/
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.
.TP
.B
<tab>
Toggle the scroll focus between the bookmarks panel and the document panel. Only has an effect if the bookmarks panel is open.
.TP
.B
<spc>
Enter line command mode. Once a line command is input, the mode will automatically revert to key command mode.
.TP
.B
:
2019-10-12 21:52:51 +00:00
Alias for <spc>. Enter line command mode.
.SS 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.
.TP
.B
[url]
Navigates to the requested url.
.TP
.B
[link id]
Follows a link on the current document with the given number.
.TP
.B
2019-10-12 21:52:51 +00:00
add [url] [name\.\.\.]
Adds the url as a bookmarks labeled by name. \fIa\fP can be used instead of the full \fIadd\fP.
.TP
.B
2019-10-12 21:52:51 +00:00
add [link id] [name\.\.\.]
Adds the url represented by the link id within the current document as a bookmark labeled by name. \fIa\fP can be used instead of the full \fIadd\fP.
.TP
.B
2019-10-12 21:52:51 +00:00
add . [name\.\.\.]
Adds the current document's url as a bookmark labeled by name. \fIa\fP can be used instead of the full \fIadd\fP.
.TP
.B
2019-10-12 21:52:51 +00:00
bookmarks
Toggles the bookmarks panel open/closed. Alias for KEY COMMAND \fIB\fP. \fIb\fP can be used instead of the full \fIbookmarks\fP.
.TP
.B
2019-10-12 21:52:51 +00:00
bookmarks [bookmark id]
Navigates to the url represented by the bookmark matching bookmark id. \fIb\fP can be entered, rather than the full \fIbookmarks\fP.
.TP
.B
2019-10-12 21:52:51 +00:00
check [link id]
Displays the url corresponding to a given link id for the current document. \fIc\fP can be used instead of the full \fIcheck\fP.
.TP
.B
2019-10-12 21:52:51 +00:00
check [setting name]
Displays the current value for a given configuration setting. \fIc\fP can be used instead of the full \fIcheck\fP.
.TP
.B
2019-12-03 08:21:05 +00:00
delete [bookmark id]
2019-10-12 21:52:51 +00:00
Deletes the bookmark matching the bookmark id. \fId\fP can be used instead of the full \fIdelete\fP.
.TP
.B
help
Navigates to the gopher based help page for \fBbombadillo\fP. \fI?\fP can be used instead of the full \fIhelp\fP.
.TP
.B
2019-10-12 21:52:51 +00:00
home
Navigates to the document set by the \fIhomeurl\fP setting. \fIh\fP can be entered, rather than the full \fIhome\fP.
.TP
.B
jump
Navigates to the previous page in history from the current page. Useful for keeping the current page in your history while still browsing. \fIj\fP can be used instead of the full \fIjump\fP.
.TP
.B
jump [history location]
Navigates to the given history location. The history location should be an integer between 0 and 20. \fIj\fP can be used instead of the full \fIjump\fP.
.TP
.B
2019-10-12 21:52:51 +00:00
purge *
Deletes all pinned gemini server certificates. \fIp\fP can be used instead of the full \fIpurge\fP.
.TP
.B
2019-10-12 21:52:51 +00:00
purge [host name]
Deletes the pinned gemini server certificate for the given hostname. \fIp\fP can be used instead of the full \fIpurge\fP.
.TP
.B
2019-10-12 21:52:51 +00:00
quit
Quits \fBbombadillo\fP. Alias for KEY COMMAND \fIq\fP. \fIq\fP can be used instead of the full \fIquit\fP.
.TP
.B
2019-10-12 21:52:51 +00:00
reload
Requests the current document from the server again. This does not break forward history the way entering the url again would. \fIr\fP can be used instead of the full \fIreload\fP.
.TP
.B
2019-10-12 21:52:51 +00:00
search
Queries the user for search terms and submits a search to the search engine set by the \fIsearchengine\fP setting.
.TP
.B
2019-10-12 21:52:51 +00:00
search [keywords\.\.\.]
Submits a search to the search engine set by the \fIsearchengine\fP setting, with the query being the provided keyword(s).
.TP
.B
2019-12-03 08:21:05 +00:00
set [setting name] [value]
Sets the value for a given configuration setting. \fIs\fP can be used instead of the full \fIset\fP.
.TP
.B
2020-11-05 15:47:08 +00:00
version
Shows the current Bombadillo version number.
.TP
.B
2019-10-12 21:52:51 +00:00
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 \fI/\fP a default name will be used. The file saves to the directory set by the \fIsavelocation\fP setting. \fIw\fP can be entered rather than the full \fIwrite\fP.
2019-10-12 21:52:51 +00:00
.TP
.B
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 \fI/\fP a default name will be used. The file saves to the directory set by the \fIsavelocation\fP setting. \fIw\fP can be entered rather than the full \fIwrite\fP.
2019-10-12 21:52:51 +00:00
.TP
.B
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 \fI/\fP a default name will be used. The file saves to the directory set by the \fIsavelocation\fP setting. \fIw\fP can be entered rather than the full \fIwrite\fP.
.SH FILES
\fBbombadillo\fP keeps a hidden configuration file in a user's XDG configuration directory. The file is a simplified ini file titled \fI.bombadillo.ini\fP. It is generated when a user first loads \fBbombadillo\fP 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 \fBbombadillo\fP defaults. On some systems an administrator may set the configuration 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 \fI:check configlocation\fP to see where the file should be, or contact your system administrator for more information.
.SH SETTINGS
The following is a list of the settings that \fBbombadillo\fP recognizes, as well as a description of their valid values.
.TP
.B
configlocation
The path to the directory that the \fI.bombadillo.ini\fP configuration file is stored in. This is a \fBread only\fP setting and cannot be changed with the \fIset\fP command, but it can be read with the \fIcheck\fP command.
.TP
.B
2019-12-07 06:19:25 +00:00
defaultscheme
The scheme that should be used when no scheme is present in a given URL. \fIgopher\fP, \fIgemini\fP, \fIhttp\fP, and \fIhttps\fP are valid values.
.TP
.B
2020-05-18 05:01:31 +00:00
geminiblocks
Determines how to treat preformatted text blocks in text/gemini documents. \fIblock\fP will show the contents of the block, \fIalt\fP will show any available alt text for the block, \fIboth\fP will show both the content and the alt text, and \fIneither\fP will show neither. Unlike other settings, a change to this value will require a fresh page load to see the change.
2020-05-18 05:01:31 +00:00
.TP
.B
homeurl
The url that \fBbombadillo\fP navigates to when the program loads or when the \fIhome\fP or \fIh\fP LINE COMMAND is issued. This should be a valid url. If a scheme/protocol is not included, gopher will be assumed.
.TP
.B
maxwidth
The number of characters at which lines should be wrapped. If this is bigger than the available terminal width, the full width of the terminal will be used. If a non-integer or an integer less than 10 is given, a default value will be used.
.TP
.B
savelocation
The path to the directory that \fBbombadillo\fP should write files to. This must be a valid filepath for the system, must be a directory, and must already exist.
.TP
.B
searchengine
The url to use for the LINE COMMAND \fIsearch\fP. Should be a valid search path that terms may be appended to.
.TP
.B
telnetcommand
Tells the browser what command to use to start a telnet session. Should be a valid command, including any flags. The address being navigated to will be added to the end of the command.
2019-10-12 21:52:51 +00:00
.TP
.B
theme
2019-12-14 15:37:56 +00:00
Can toggle between visual modes. Valid values are \fInormal\fP, \fIcolor\fP, and \fIinverse\fP. 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.
.TP
.B
2020-06-30 05:19:14 +00:00
timeout
The number of seconds after which connections to gopher or gemini servers should time out if the server has not responded.
.TP
.B
webmode
Controls behavior when following web links. The following values are valid: \fInone\fP will disable following web links, \fIgui\fP will have the browser attempt to open web links in a user's default graphical web browser; \fIlynx\fP, \fIw3m\fP, and \fIelinks\fP 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.
2019-10-12 21:52:51 +00:00
.SH BUGS
2019-11-13 03:22:45 +00:00
There are very likely bugs. Many known bugs can be found in the issues section of \fBbombadillo\fP's source code repository (see \fIlinks\fP).
2019-10-12 21:52:51 +00:00
.SH LINKS
\fBbombadillo\fP maintains a presence in the following locations:
2019-10-12 21:52:51 +00:00
.TP
.B
2019-11-13 03:22:45 +00:00
Source Code Repository
2019-10-12 21:52:51 +00:00
https://tildegit.org/sloum/bombadillo
.TP
.B
Web Homepage
http://bombadillo.colorfield.space
.TP
.B
Gopher Homepage
gopher://bombadillo.colorfield.space
.SH AUTHORS
\fBbombadillo\fP was primarily developed by sloum, with kind and patient assistance from ~asdf and jboverf.