Updates man file

This commit is contained in:
sloumdrone 2019-10-12 14:52:51 -07:00
parent 9e8e7ee5b1
commit e44666cd05
1 changed files with 131 additions and 67 deletions

View File

@ -1,5 +1,4 @@
." Text automatically generated by txt2man
.TH "bombadillo" 1 "21 SEP 2019" "" "General Opperation Manual"
.TH "bombadillo" 1 "12 OCT 2019" "" "General Opperation Manual"
.SH NAME
\fBbombadillo \fP- a non-web client
.SH SYNOPSIS
@ -9,7 +8,7 @@
.fam T
.fi
.SH DESCRIPTION
\fBbombadillo\fP is a terminal based client for a number of internet protocols, including gopher and gemini. \fBbombadillo\fP will also connect links to a user's default web browser or telnet client. Commands input is loosely based on Vi and Less and is comprised of two modes: key and line input mode.
\fBbombadillo\fP is a terminal based client for a number of internet protocols. \fBbombadillo\fP will also connect links to a user's default web browser or telnet client. Commands input is loosely based on Vi and Less and is comprised of two modes: key and line input mode.
.SH OPTIONS
.TP
.B
@ -19,6 +18,32 @@ Display the version number of \fBbombadillo\fP.
.B
\fB-h\fP
Usage help. Displays all command line options with a short description.
.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). Client certificates are also supported via option configuration. Gemini maps and other text types are rendered in the client and non-text types will trigger a prompt to the user to download or open in an appropriate program.
.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 who's phlogs you follow.
.TP
.B
local
Local is similar to the \fIfile\fP protocol user's may be used to in web browsers or the like. The only difference is that the feature set of local may be smaller than file. User's 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.
.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. However, bombadillo is capable of attempting to open web links in a user's default web browser. This feature is opt-in only and controlled in a user's settings. This feature does not function properly in a terminal only environment at present.
.SH COMMANDS
.SS KEY COMMANDS
These commands work as a single keypress anytime \fBbombadillo\fP is not taking in a line based command. This is the default command mode of \fBbombadillo\fP.
@ -60,6 +85,10 @@ q
Quit \fBbombadillo\fP.
.TP
.B
R
Reload the current page (does not destroy forward history)
.TP
.B
u
Scroll up an amount corresponding to 75% of your terminal window height in the current document.
.TP
@ -73,10 +102,9 @@ Enter line command mode. Once a line command is input, the mode will automatical
.TP
.B
:
Alias for <space>. Enter line command mode.
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.
.SS NAVIGATION
.TP
.B
[url]
@ -87,55 +115,6 @@ Navigates to the requested url.
Follows a link on the current document with the given number.
.TP
.B
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
home
Navigates to the document set by the \fIhomeurl\fP setting. \fIh\fP can be entered, rather than the full \fIhome\fP.
.TP
.B
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
search
Queries the user for search terms and submits a search to the search engine set by the \fIsearchengine\fP setting.
.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 folder set by the \fIsavelocation\fP setting. \fIw\fP can be entered rather than the full \fIwrite\fP.
.TP
.B
write [url] [filename\.\.\.]
Writes data from a given url to a file. The file is named by the filename argument should should not include a leading \fI/\fP. The file saves to the folder set by the \fIsavelocation\fP setting. \fIw\fP can be entered rather than the full \fIwrite\fP.
.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 folder set by the \fIsavelocation\fP setting. \fIw\fP can be entered rather than the full \fIwrite\fP.
.TP
.B
write [link id] [filename\.\.\.]
Writes data from a given link id in the current document to a file. The file is named by the filename argument should should not include a leading \fI/\fP. The file saves to the folder set by the \fIsavelocation\fP setting. \fIw\fP can be entered rather than the full \fIwrite\fP.
.TP
.B
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 folder set by the \fIsavelocation\fP setting. \fIw\fP can be entered rather than the full \fIwrite\fP.
.TP
.B
write . [filename\.\.\.]
Writes the current document to a file. The file is named by the filename argument should should not include a leading \fI/\fP. The file saves to the folder set by the \fIsavelocation\fP setting. \fIw\fP can be entered rather than the full \fIwrite\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.
.SS BOOKMARKS
.TP
.B
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
add [url] [name\.\.\.]
Adds the url as a bookmarks labeled by name. \fIa\fP can be used instead of the full \fIadd\fP.
.TP
@ -144,13 +123,16 @@ 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
add [.] [name\.\.\.]
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
delete [bookmark id]]
Deletes the bookmark matching the bookmark id. \fId\fP can be used instead of the full \fIdelete\fP.
.SS MISC
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
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
check [link id]
@ -161,14 +143,70 @@ 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
set [setting name]
Sets the value for a given configuration setting. \fIs\fP can be used instead of the full \fIset\fP.
delete [bookmark id]]
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
home
Navigates to the document set by the \fIhomeurl\fP setting. \fIh\fP can be entered, rather than the full \fIhome\fP.
.TP
.B
purge *
Deletes all pinned gemini server certificates. \fIp\fP can be used instead of the full \fIpurge\fP.
.TP
.B
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
quit
Quits \fBbombadillo\fP. Alias for KEY COMMAND \fIq\fP. \fIq\fP can be used instead of the full \fIquit\fP.
.TP
.B
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
search
Queries the user for search terms and submits a search to the search engine set by the \fIsearchengine\fP setting.
.TP
.B
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
set [setting name]
Sets the value for a given configuration setting. \fIs\fP can be used instead of the full \fIset\fP.
.TP
.B
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 folder set by the \fIsavelocation\fP setting. \fIw\fP can be entered rather than the full \fIwrite\fP.
.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 folder set by the \fIsavelocation\fP setting. \fIw\fP can be entered rather than the full \fIwrite\fP.
.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 folder set by the \fIsavelocation\fP setting. \fIw\fP can be entered rather than the full \fIwrite\fP.
.TP
.B
write . [filename\.\.\.]
Writes the current document to a file. The file is named by the filename argument should should not include a leading \fI/\fP. The file saves to the folder set by the \fIsavelocation\fP setting. \fIw\fP can be entered rather than the full \fIwrite\fP.
.TP
.B
write [url] [filename\.\.\.]
Writes data from a given url to a file. The file is named by the filename argument should should not include a leading \fI/\fP. The file saves to the folder set by the \fIsavelocation\fP setting. \fIw\fP can be entered rather than the full \fIwrite\fP.
.TP
.B
write [link id] [filename\.\.\.]
Writes data from a given link id in the current document to a file. The file is named by the filename argument should should not include a leading \fI/\fP. The file saves to the folder 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 home directory. The file is a simplified ini file titled '.bombadillo.ini'. 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.
\fBbombadillo\fP keeps a hidden configuration file in a user's home 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.
.SH SETTINGS
The following is a list of the settings that \fBbombadillo\fP recognizes, as well as a description of their valid values.
.TP
@ -177,6 +215,10 @@ 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
openhttp
Tells the client whether or not to try to follow web (http/https) links. If set to \fItrue\fP, \fBbombadillo\fP will try to open a user's default web browser to the link in question. Any value other than \fItrue\fP is considered false. Defaults to \fIfalse\fP. Does not work in a terminal only environment.
.TP
.B
savelocation
The path to the folder that \fBbombadillo\fP should write files to. This should be a valid filepath for the system and should end in a \fI/\fP. Defaults to a user's home directory.
.TP
@ -185,17 +227,39 @@ searchengine
The url to use for the LINE COMMANDs \fI?\fP and \fIsearch\fP. Should be a valid search path that terms may be appended to. Defaults to \fIgopher://gopher.floodgap.com:70/7/v2/vs\fP.
.TP
.B
openhttp
Tells the client whether or not to try to follow web (http/https) links. If set to \fItrue\fP, \fBbombadillo\fP will try to open a user's default web browser to the link in question. Any value other than \fItrue\fP is considered false. Defaults to \fIfalse\fP.
.TP
.B
telnetcommand
Tells the client 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. Defaults to \fItelnet\fP.
.TP
.B
terminalonly
Sets whether or not to try to open non-text files served via gemini in gui programs or not. If set to \fItrue\fP, bombdaillo will only attempt to use terminal programs to open files. If set to anything else, \fBbombadillo\fP may choose graphical and terminal programs. Defaults to \fItrue\fP.
.TP
.B
theme
Can toggle between visual modes. Valid values are \fInormal\fP and \fIinverse\fP. When set to ivnerse, the terminal color mode is inversed. Defaults to \fInormal\fP.
.TP
.B
terminalonly
Sets whether or not to try to open non-text files served via gemini in gui programs or not. If set to \fItrue\fP, bombdaillo will only attempt to use terminal programs to open files. If set to anything else, \fBbombadillo\fP may choose graphical and terminal programs. Defaults to \fItrue\fP.
tlscertificate
A path to a tls certificate file on a user's local filesystem. Defaults to NULL. Both \fItlscertificate\fP and \fItlskey\fP must be set for client certificates to work in gemini.
.TP
.B
tlskey
A path the a tls key that pairs with the tlscertificate setting, on a user's local filesystem. Defaults to NULL. Both \fItlskey\fP and \fItlscertificate\fP must be set for client certificates to work in gemini.
.SH BUGS
There are very likely bugs. Many known bugs can be found in the issues section of \fBbombadillo\fP's software repository (see \fIlinks\fP).
.SH LINKS
\fBbombadillo\fP maintains a web presence in the following locations:
.TP
.B
Code Repository
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.