path: root/xxxterm.1

.\"	$xxxterm$
.\"
.\" Copyright (c) 2010 Marco Peereboom <marco@peereboom.us>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt XXXTERM 1
.Os
.Sh NAME
.Nm xxxterm
.Nd lightweight web browser with vi key bindings
.Sh SYNOPSIS
.Nm xxxterm
.Bk -words
.Op Fl STtV
.Op Fl f Ar file
.Op Fl n
.Op Ar url ...
.Ek
.Sh DESCRIPTION
.Nm
is a minimalistic web browser that tries to stay out of the way so that
valuable screen real estate can be used for much more important stuff.
It has sane defaults and does not require one to learn a language to do any
configuration.
It was written by hackers for hackers and it strives to be small, compact and
fast.
.Pp
When
.Nm
starts up, it reads settings from its configuration file,
.Pa xxxterm.conf .
See the
.Sx CONFIGURATION FILES
section below.
.Pp
The following notation is used throughout this page:
.Pp
.Bl -tag -width Ds -offset indent -compact
.It Cm M
Meta
.It Cm S
Shift
.It Cm C
Control
.It Cm M1
Mouse button 1
.El
.Pp
.Nm
is very simple in its use.
Most of the actions are initiated via key or mouse bindings.
See the
.Sx BINDINGS
section below for defaults and customizations.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl f Ar file
Use alternate config file.
.It Fl S
Disable the toolbar.
.It Fl T
Disable visualization of tabs.
.It Fl t
Disable tabs.
.It Fl n
Open a new tab in a running
.Nm
for each specified url.
This option requires enable_socket to be enabled.
.It Fl V
Display version and exit.
.El
.Sh CONFIGURATION FILES
.Nm
tries to open the user specific file,
.Pa ~/.xxxterm.conf .
If that file is unavailable,
it then uses built-in defaults.
.Pp
The format of the file is \*(Ltkeyword\*(Gt = \*(Ltsetting\*(Gt.
For example:
.Pp
.Dl http_proxy = http://127.0.0.1:8080
.Pp
Enabling or disabling an option is done by using 1 or 0 respectively.
.Pp
The file supports the following keywords:
.Pp
.Bl -tag -width "title_class_enabledXXX" -offset indent -compact
.It Cm ctrl_click_focus
Give focus in newly created tab instead of opening it in the background.
.It Cm read_only_cookies
Mark cookies file read-only and discard all cookies once the sessions is
terminated.
.It Cm append_next
When set a new tab is appended after the current tab instead of being appended
as the last tab.
.It Cm cookies_enabled
Enable cookies.
.It Cm allow_volatile_cookies
If set cookies are stored in the session cache but will be discarded once
.Nm
exits.
Unfortunately enabling this does allow for some limited tracking on the web.
.It Cm enable_scripts
Enable scripts.
.It Cm enable_plugins
Enable plugins.
.It Cm default_font_size
Set the default browsing font size.
.It Cm http_proxy
Proxy server in URI format.
.It Cm download_dir
Locations where files are downloaded to.
This directory must exist and
.Nm
validates that during startup.
.It Cm fancy_bar
Enables a backward, forward and stop button to the toolbar.
Additionally if search_string is set it'll enable an entry box for searches.
.It Cm refresh_interval
Refresh interval while in the download manager.
Default is 10.
.It Cm session_timeout
If this value is greater than 3600 then it is the time added in seconds to a
session cookie.  If the value is smaller than 3600 then there is no change
to the expiration of a session cookie.
.It Cm enable_cookie_white list
When enabled all cookies must be in the white list or they are rejected.
.It Cm cookie_wl
This is a cookie white list item.
Use multiple times to add multiple entries.
Valid entries are for example *.moo.com and the equivalent .moo.com.
A fully qualified host is also valid and is for example www.moo.com.
.It Cm cookie_policy
This field delineates the cookie policy.
Possible values are: no3rdparty, reject 3rd party cookies.
accept, accept all cookies.
reject, reject all cookies.
.It Cm enable_js_whitelist
When enabled all domains must be in the js white list in order to run javascript.
NOTE: Make sure enable_scripts is set to 0.
.It Cm js_wl
This is a javascript white list item.
See cookie_wl for semantics and more details.
.It Cm search_string
Default search engine string.
See xxxterm.conf file for details.
.It Cm mime_type
Sets an action for a specific or default MIME type.
For example, to download and view a pdf using kpdf set mime_type =
application/pdf,kpdf.
To set a default value use *, for example mime_type = video/*,mplayer.
Note that the action is only passed the URI and not all applications are
capable of downloading content and therefore one might have to create a wrapper
script to download the content first.
.It Cm alias
Defines an alias for a given URL, so that the URL is loaded when the alias is
entered in the address bar.
If the aliased URL includes a %s format specifier, then any argument given after
the alias on the address bar is substituted.
For example, if g,http://www.google.com/search?q=%s is defined as an alias,
then the URL http://www.google.com/search?q=foo is loaded when navigating to
"g foo".
.It Cm ssl_ca_file
If set to a valid PEM file all server certificates will be validated against it.
The URL bar will be colored green when the certificate is trusted and yellow when
untrusted.
.Pp
If ssl_ca_file is not set then the URL bar will color all https connections red.
.It Cm ssl_strict_certs
If this value is set connections to untrusted sites will be aborted.
This value is only used if ssl_ca_file is set.
.It Cm enable_socket
When enabled the first instance of
.Nm
will create a socket in the ~/.xxxterm directory.
Using the -n url option on subsequent
.Nm
invocations will cause the specified url to be loaded in a new tab.
Only a user with identical UID and GID can use this option.
.It Cm resource_dir
Directory that contains various xxxterm resources such as icons.
This is OS specific and should be handled by the porter.
.It Cm single_instance
If set only one
.Nm
will be permitted to run.
If there is a url specified it will be opened in a new tab in the already
running
.Nm
session.
.It Cm runtime_settings
This setting points to a filename in the .xxxterm work directory that contains
runtime configuration entries.
This file is parsed as a normal configuration file and will override settings
since it is read at a later time.
One should only use this file to add js_wl, cookie_wl and mime_type entries.
This file is machine generated and should not be edited by hand.
.El
.Pp
.Nm
overrides http_proxy if it is specified as an environment variable.
.Sh BINDINGS
.Nm
provides many functions (or actions) accessed via key or mouse bindings.
.Pp
The current mouse bindings are described below:
.Pp
.Bl -tag -width "tabnew, tabedit, tabe [URI]" -offset indent -compact
.It Cm C-M1
Open new tab with the clicked link.
.El
.Pp
The default key bindings are described below.
.Pp
Search:
.Pp
.Bl -tag -width "tabnew, tabedit, tabe [URI]" -offset indent -compact
.It Cm /
Start a search
.It Cm ?
Start a backwards search
.It Cm n
Next item matching search
.It Cm N
Previous item matching search
.El
.Pp
Focus:
.Pp
.Bl -tag -width "tabnew, tabedit, tabe [URI]" -offset indent -compact
.It Cm F6
Focus on URI entry
.It Cm F7
Focus on search entry
.El
.Pp
Command aliases (useful when -S flag is used):
.Pp
.Bl -tag -width "tabnew, tabedit, tabe [URI]" -offset indent -compact
.It Cm F9
Alias for ":open" (See command descriptions below)
.It Cm F10
Alias for ":open <current-uri>"
.It Cm F11
Alias for ":tabnew"
.It Cm F12
Alias for ":tabnew <current-uri>"
.El
.Pp
Navigation:
.Pp
.Bl -tag -width "tabnew, tabedit, tabe [URI]" -offset indent -compact
.It Cm F5, C-r, C-l
Reload page
.It Cm C-R
Reload page without using any cached data
.It Cm Backspace, M-Left
Previous page
.It Cm S-BackSpace, M-Right
Forward page
.It Cm j, Down
Next line on page
.It Cm k, Up
Previous line on page
.It Cm G, End
Bottom of page
.It Cm gg, Home
Top of page
.It Cm Space, C-f, PageDown
Page down
.It Cm C-b, PageUp
Page up
.It Cm l, Right
Page right
.It Cm h, Left
Page left
.It Cm $
Page far right
.It Cm 0
Page far left
.It Cm M-f
Favorites
.It Cm M-d
Download manager
.It Cm C-p
Print page
.It Cm M-h
Global history
.It Cm C-j
Toggle javascript enabled for domain.
.It Cm C-s
Toggle source view.
.El
.Pp
Tab Manipulation:
.Pp
.Bl -tag -width "tabnew, tabedit, tabe [URI]" -offset indent -compact
.It Cm C-t
Create new tab with focus in URI entry
.It Cm C-w
Destroy current tab
.It Cm U
Undo close tab
.It Cm C-Left
Go to the previous tab.
.It Cm C-Right
Go to the next tab.
.It Cm C-[1..0]
Jump to page N
.It Cm C-minus
Shrink font size by one point.
.It Cm C-plus, C-equal
Grow font size by one point.
.El
.Pp
Yanking and pasting:
.Pp
.Bl -tag -width "tabnew, tabedit, tabe [URI]" -offset indent -compact
.It Cm y
Yank the current URI into the clipboard.
.It Cm p
Paste the contents of the clipboard into the address bar.
.It Cm P
Paste the contents of the clipboard into a new tab.
.El
.Pp
Mouse-less browsing (a.k.a. link following):
.Pp
.Bl -tag -width "tabnew, tabedit, tabe [URI]" -offset indent -compact
.It Cm f
Highlight all links and prefix them with a number.
Press number to follow link.
Alternatively one can type the name of the link and when there are no more
possibilities
.Nm
will follow the link.
.El
.Pp
Exiting:
.Pp
.Bl -tag -width "tabnew, tabedit, tabe [URI]" -offset indent -compact
.It Cm C-Q
Quit
.El
.Pp
Note: WebKit & GTK+ have many default key bindings that are not overruled and
therefore are available as-is.
.Pp
Command mode is entered by typing a colon and exited by typing Esc.
The commands and descriptions are listed below:
.Pp
.Bl -tag -width "tabnew, tabedit, tabe [URI]" -offset indent -compact
.It Cm qa, qa!, q!
Quit
.Nm
.It Cm w
Save open tabs.
The tabs will be restored next time
.Nm
is started.
.It Cm restart
Restart
.Nm
and reload all current tabs.
.It Cm wq, wq!
Save open tabs and quit.
The tabs will be restored next time
.Nm
is started.
.It Cm cert
Download and display certificate(s) of domain on tab.
.It Cm ca
Display CA certificate(s).
.It Cm fav
Show favorites
.It Cm favadd
Add current page to favorites
.It Cm jsadd
Add current page domain as a JavaScript white list entry to the runtime
configuration file.
This action will also enable JavaScript if it is currently disabled for this
domain.
.It Cm cookieadd
Add current page domain as a cookie white list entry to the runtime
configuration file.
This action will also allow cookies if it is currently disallowed for this
domain.
If there are volatile session cookies then those will be saved into the
persistent cookie jar.
.It Cm dl
Show download manager
.It Cm print
Print page
.It Cm h, hist, history
Global history
.It Cm help
Show help page.
.It Cm home
Go to home URL.
.It Cm about, version
Show about page.
.It Cm cookies
Show cookie jar contents.
.It Cm stats
Show blocked cookies statistics.
These statistics vary based on settings and are not persistent.
.It Cm open, op, o <URI>
Open URI.
.It Cm tabnew, tabedit, tabe [URI]
Create new tab and optionally open provided URI
.It Cm tabclose, tabc
Close current tab.
.It Cm quit, q
Close current tab and quit
.Nm
if it is the last tab.
.It Cm tabprevious, tabp
Go to the previous tab.
.It Cm tabnext, tabn
Go to the next tab.
.El
.Sh FILES
.Bl -tag -width "/etc/xxxterm.confXXX" -compact
.It Pa ~/.xxxterm.conf
.Nm
user specific settings.
.It Pa ~/.xxxterm
.Nm
scratch directory.
.El
.Sh HISTORY
.Nm
was inspired by vimprobable2 and the bloat in other UNIX web browsers.
.Sh AUTHORS
.An -nosplit
.Pp
.Nm
was written by
.An Marco Peereboom Aq marco@peereboom.us ,
and
.An Edd Barrett Aq vext01@gmail.com