xxxterm.1

   1 .\"     $xxxterm$
   2 .\"
   3 .\" Copyright (c) 2010, 2011 Marco Peereboom <marco@peereboom.us>
   4 .\" Copyright (c) 2011 Jason McIntyre <jmc@kerhand.co.uk>
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software for any
   7 .\" purpose with or without fee is hereby granted, provided that the above
   8 .\" copyright notice and this permission notice appear in all copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17 .\"
  18 .Dd $Mdocdate$
  19 .Dt XXXTERM 1
  20 .Os
  21 .Sh NAME
  22 .Nm xxxterm
  23 .Nd lightweight web browser
  24 .Sh SYNOPSIS
  25 .Nm xxxterm
  26 .Bk -words
  27 .Op Fl nSTtV
  28 .Op Fl f Ar file
  29 .Op Ar url ...
  30 .Ek
  31 .Sh DESCRIPTION
  32 .Nm
  33 is a minimalistic web browser that tries to stay out of the way so that
  34 valuable screen real estate can be used for much more important stuff.
  35 It has sane defaults and does not require one to learn a language to do any
  36 configuration.
  37 It was written by hackers for hackers
  38 and it strives to be small, compact, and fast.
  39 .Pp
  40 .Nm
  41 is very simple in its use.
  42 Most actions are initiated via key or mouse bindings.
  43 Key bindings are based on those of the
  44 .Xr vi 1
  45 text editor,
  46 giving web browsing a similar feel to navigating a text document.
  47 The
  48 .Sx KEY BINDINGS
  49 section below documents the various defaults and possible customizations.
  50 .Pp
  51 The options are as follows:
  52 .Bl -tag -width Ds
  53 .It Fl f Ar file
  54 Specify an alternative configuration file.
  55 .It Fl S
  56 Disable the toolbar.
  57 .It Fl T
  58 Disable visualization of tabs.
  59 .It Fl t
  60 Disable tabs.
  61 .It Fl n
  62 Open a new tab in a running
  63 .Nm
  64 for each specified URL.
  65 This option requires
  66 .Cm enable_socket
  67 to be enabled.
  68 .It Fl V
  69 Display version and exit.
  70 .El
  71 .Sh FAST STARTUP
  72 The following notation is used throughout this page:
  73 .Pp
  74 .Bl -tag -width Ds -offset indent -compact
  75 .It Cm C
  76 Control
  77 .It Cm M
  78 Meta (sometimes marked Alt)
  79 .It Cm M1
  80 Mouse button 1
  81 .It Cm S
  82 Shift
  83 .El
  84 .Pp
  85 To browse to a specific address,
  86 either use the mouse to click on the address bar
  87 or press
  88 .Cm F6
  89 to shift the keyboard focus to the address bar.
  90 The address is then entered manually.
  91 .Pp
  92 The mouse can be used to navigate the page in the traditional manner,
  93 or the keyboard can be used instead.
  94 For example,
  95 .Cm PageUp
  96 and
  97 .Cm PageDown
  98 will scroll up and down the page.
  99 .Pp
 100 To follow a link,
 101 either click on it or use the
 102 .Cm f
 103 key and have
 104 .Nm
 105 assign numbers to each link on the page;
 106 entering that number on the keyboard will prompt
 107 .Nm
 108 to follow the link.
 109 .Sh KEY BINDINGS
 110 .Nm
 111 provides many actions accessed via key or mouse bindings.
 112 Note that WebKit & GTK+ have their own set of key bindings
 113 that are not overruled and therefore are available as-is.
 114 .Ss Search Commands
 115 These commands are used to search for text strings within a web page.
 116 .Pp
 117 .Bl -tag -width Ds -offset indent -compact
 118 .It Cm /
 119 Start a search
 120 .It Cm \&?
 121 Start a backwards search
 122 .It Cm n
 123 Next item matching search
 124 .It Cm N
 125 Previous item matching search
 126 .El
 127 .Ss Focus Commands
 128 These commands are used to shift the focus of
 129 .Nm
 130 from one area to another.
 131 .Pp
 132 .Bl -tag -width Ds -offset indent -compact
 133 .It Cm F6
 134 Focus on address bar
 135 .It Cm F7
 136 Focus on search entry
 137 .El
 138 .Ss Command Aliases
 139 These commands allow the user to map specific actions to specific keys.
 140 It can be useful when the
 141 .Fl S
 142 option is used.
 143 .Pp
 144 .Bl -tag -width Ds -offset indent -compact
 145 .It Cm F9
 146 Alias for ":open"
 147 .It Cm F10
 148 Alias for ":open current-uri"
 149 .It Cm F11
 150 Alias for ":tabnew"
 151 .It Cm F12
 152 Alias for ":tabnew current-uri"
 153 .El
 154 .Ss Navigation Commands
 155 These commands allow the user to navigate web pages and,
 156 to some extent,
 157 control the browser.
 158 .Pp
 159 .Bl -tag -width "Space, C-f, PageDownXXX" -offset indent -compact
 160 .It Cm F5, C-r, C-l
 161 Reload page
 162 .It Cm C-R
 163 Reload page without using any cached data
 164 .It Cm Backspace, M-Left
 165 Previous page
 166 .It Cm S-BackSpace, M-Right
 167 Forward page
 168 .It Cm j, Down
 169 Next line on page
 170 .It Cm k, Up
 171 Previous line on page
 172 .It Cm G, End
 173 Bottom of page
 174 .It Cm gg, Home
 175 Top of page
 176 .It Cm Space, C-f, PageDown
 177 Page down
 178 .It Cm C-b, PageUp
 179 Page up
 180 .It Cm l, Right
 181 Page right
 182 .It Cm h, Left
 183 Page left
 184 .It Cm $
 185 Page far right
 186 .It Cm 0
 187 Page far left
 188 .It Cm M-f
 189 Favorites
 190 .It Cm M-d
 191 Download manager
 192 .It Cm C-p
 193 Print page
 194 .It Cm M-h
 195 Global history
 196 .It Cm C-j
 197 Toggle javascript enabled for domain
 198 .It Cm C-s
 199 Toggle source view
 200 .El
 201 .Ss Tab Manipulation
 202 .Nm
 203 supports tabbed browsing.
 204 That is, web pages may be opened in separate tabs,
 205 allowing the user to quickly move from one page to another,
 206 and back.
 207 These commands then are used to create, destroy, and move between tabs.
 208 .Pp
 209 .Bl -tag -width "C-plus, C-equalXXX" -offset indent -compact
 210 .It Cm C-M1
 211 Open new tab with the clicked link
 212 .It Cm C-t
 213 Create new tab with focus in URL entry
 214 .It Cm C-w
 215 Destroy current tab
 216 .It Cm U
 217 Undo close tab
 218 .It Cm C-Left
 219 Go to the previous tab
 220 .It Cm C-Right
 221 Go to the next tab
 222 .It Cm C-[1..0]
 223 Jump to page
 224 .Ar N
 225 .It Cm C-minus
 226 Shrink font size by one point
 227 .It Cm C-plus, C-equal
 228 Grow font size by one point
 229 .El
 230 .Ss Yanking and pasting
 231 These commands copy and paste text to and from the clipboard.
 232 .Pp
 233 .Bl -tag -width Ds -offset indent -compact
 234 .It Cm p
 235 Paste the contents of the clipboard into the address bar
 236 .It Cm P
 237 Paste the contents of the clipboard into a new tab
 238 .It Cm y
 239 Yank the current URL into the clipboard
 240 .El
 241 .Ss Hyperlink Following
 242 This allows the user to follow hyperlinks
 243 without using a mouse.
 244 Enter the corresponding number to follow the link.
 245 Alternatively one can type the name of the link and when there are no more
 246 possibilities
 247 .Nm
 248 will follow the link.
 249 .Pp
 250 .Bl -tag -width Ds -offset indent -compact
 251 .It Cm f
 252 Highlight all links and prefix them with a number.
 253 .El
 254 .Ss Exiting
 255 Commands to exit the browser.
 256 .Pp
 257 .Bl -tag -width Ds -offset indent -compact
 258 .It Cm C-Q
 259 Quit
 260 .El
 261 .Sh COMMAND MODE
 262 Command mode works in a similar fashion to the
 263 .Xr vi 1
 264 editor;
 265 it is entered by typing a colon and exited by typing Esc.
 266 The commands and their descriptions are listed below.
 267 .Bl -tag -width Ds -offset indent
 268 .It Cm about , version
 269 Show the "About" page.
 270 .It Cm ca
 271 Display CA certificates.
 272 .It Cm cert , cert show
 273 Download and display certificates of domain on tab.
 274 .It Cm cert save
 275 Save certificate into a local store.
 276 The next time the site is visited it is compared against the store.
 277 If the certificate matches,
 278 the address bar will be blue;
 279 if it doesn't the bar will be red.
 280 .It Cm cookie
 281 The
 282 .Cm cookie
 283 command is used to manipulate the cookie whitelist.
 284 Used by itself it expands to
 285 .Cm cookie show all .
 286 .It Cm cookies
 287 Show cookie jar contents.
 288 .It Cm cookie save
 289 .It Cm cookie save domain
 290 Save the top level domain name to the persitent whitelist.
 291 For example,
 292 the www.peereboom.us domain would result in saving .peereboom.us.
 293 .Pp
 294 This action enables cookies if it is currently disabled for this entry.
 295 .It Cm cookie save fqdn
 296 Save the current fully qualified domain name (FQDN)
 297 to the persitent whitelist.
 298 .It Cm cookie show all
 299 Show all persistent and session entries in the cookie whitelist.
 300 .It Cm cookie show persistent
 301 Show all persistent entries in the cookie whitelist.
 302 .It Cm cookie show session
 303 Show all session entries in the cookie whitelist.
 304 .It Cm cookie toggle
 305 .It Cm cookie toggle domain
 306 Toggle cookie support for the current top level domain.
 307 .It Cm cookie toggle fqdn
 308 Toggle Java Script execution for the current FQDN.
 309 .It Cm dl
 310 Show download manager.
 311 .It Cm fav
 312 Show favorites.
 313 .It Cm favadd
 314 Add the current page to favorites.
 315 .It Cm fullscreen , f
 316 Toggle hiding tabs and url entry toolbar.
 317 .It Cm h , hist , history
 318 Show global history.
 319 .It Cm help
 320 Show help page.
 321 .It Cm home
 322 Go to home URL.
 323 .It Cm js
 324 The
 325 .Cm js
 326 command is used to manipulate the Java Script whitelist.
 327 Used by itself it expands to
 328 .Cm js show all .
 329 .It Cm js save
 330 .It Cm js save domain
 331 Saves the top level domain name to the persitent whitelist.
 332 For example,
 333 the www.peereboom.us domain would result in saving .peereboom.us.
 334 .Pp
 335 This action enables Java Script if it is currently disabled for this entry.
 336 .It Cm js save fqdn
 337 Saves the current FQDN to the persitent whitelist.
 338 .It Cm js show all
 339 Shows all persistent and session entries in the JS whitelist.
 340 .It Cm js show persistent
 341 Shows all persistent entries in the JS whitelist.
 342 .It Cm js show session
 343 Shows all session entries in the JS whitelist.
 344 .It Cm js toggle
 345 .It Cm js toggle domain
 346 Toggle Java Script execution for the current top level domain.
 347 .It Cm js toggle fqdn
 348 Toggle Java Script execution for the current FQDN.
 349 .It Cm open , op , o URL
 350 Open URL.
 351 .It Cm print
 352 Print page.
 353 .It Cm qa , qa! , q!
 354 Quit
 355 .Nm .
 356 .It Cm quit , q
 357 Close current tab and quit
 358 .Nm
 359 if it is the last tab.
 360 .It Cm restart
 361 Restart
 362 .Nm
 363 and reload all current tabs.
 364 .It Cm session , Cm session show
 365 Display the current session name.
 366 By default the session name is main_session.
 367 To create a new session use the
 368 .Cm session save
 369 command.
 370 A session is defined as the lifetime of the browser window.
 371 .It Cm session delete <session_name>
 372 Delete session session_name from persistent storage.
 373 If session_name is the current session then the session will revert to
 374 main_session.
 375 .It Cm session open <session_name>
 376 Open session_name and close all currently open tabs.
 377 Going forward this session is named session_name.
 378 .It Cm session save <session_name>
 379 Save current tabs to session_name session.
 380 This will close the current session and going forward this session is named
 381 session_name.
 382 .It Cm stats
 383 Show blocked cookie statistics.
 384 These statistics vary based on settings and are not persistent.
 385 .It Cm tabclose , tabc
 386 Close current tab.
 387 .It Cm tabhide , tabh
 388 Hide tabs.
 389 .It Cm tabnew , tabedit , tabe URL
 390 Create new tab and optionally open provided URL.
 391 .It Cm tabnext , tabn
 392 Go to the next tab.
 393 .It Cm tabprevious , tabp
 394 Go to the previous tab.
 395 .It Cm tabshow , tabs
 396 Show tabs.
 397 .It Cm urlhide , urlh
 398 Hide url entry and toolbar.
 399 .It Cm urlshow , urls
 400 Show url entry and toolbar.
 401 .It Cm w
 402 Save open tabs to current session.
 403 The tabs will be restored next time
 404 .Nm
 405 the session is opened.
 406 See the session command for additional details.
 407 .It Cm wq , wq!
 408 Save open tabs and quit.
 409 The tabs will be restored next time
 410 .Nm
 411 the session is opened.
 412 See the session command for additional details.
 413 .El
 414 .Sh FILES
 415 .Bl -tag -width "/etc/xxxterm.confXXX" -compact
 416 .It Pa ~/.xxxterm.conf
 417 .Nm
 418 user specific settings.
 419 .It Pa ~/.xxxterm
 420 .Nm
 421 scratch directory.
 422 .El
 423 .Pp
 424 .Nm
 425 tries to open the user specific file,
 426 .Pa ~/.xxxterm.conf .
 427 If that file is unavailable,
 428 it then uses built-in defaults.
 429 .Pp
 430 The format of the file is \*(Ltkeyword\*(Gt = \*(Ltsetting\*(Gt.
 431 For example:
 432 .Pp
 433 .Dl http_proxy = http://127.0.0.1:8080
 434 .Pp
 435 Enabling or disabling an option is done by using 1 or 0 respectively.
 436 .Pp
 437 The file supports the following keywords:
 438 .Pp
 439 .Bl -tag -width "enable_cookie_whitelistXXX" -offset indent -compact
 440 .It Cm alias
 441 Defines an alias for a given URL, so that the URL is loaded when the alias is
 442 entered in the address bar.
 443 If the aliased URL includes a %s format specifier, then any argument given after
 444 the alias on the address bar is substituted.
 445 For example, if g,http://www.google.com/search?q=%s is defined as an alias,
 446 then the URL http://www.google.com/search?q=foo is loaded when navigating to
 447 "g foo".
 448 .It Cm allow_volatile_cookies
 449 If set cookies are stored in the session cache but will be discarded once
 450 .Nm
 451 exits.
 452 Unfortunately enabling this does allow for some limited tracking on the web.
 453 .It Cm append_next
 454 When set a new tab is appended after the current tab instead of being appended
 455 as the last tab.
 456 .It Cm cookie_policy
 457 This field delineates the cookie policy.
 458 Possible values are: no3rdparty, reject 3rd party cookies.
 459 accept, accept all cookies.
 460 reject, reject all cookies.
 461 .It Cm cookie_wl
 462 This is a cookie whitelist item.
 463 Use multiple times to add multiple entries.
 464 Valid entries are for example *.moo.com and the equivalent .moo.com.
 465 A fully qualified host is also valid and is for example www.moo.com.
 466 .It Cm cookies_enabled
 467 Enable cookies.
 468 .It Cm ctrl_click_focus
 469 Give focus in newly created tab instead of opening it in the background.
 470 .It Cm default_font_size
 471 Set the default browsing font size.
 472 .It Cm download_dir
 473 Locations where files are downloaded to.
 474 This directory must exist and
 475 .Nm
 476 validates that during startup.
 477 .It Cm enable_cookie_whitelist
 478 When enabled all cookies must be in the whitelist or they are rejected.
 479 .It Cm enable_js_whitelist
 480 When enabled all domains must be in the js whitelist in order to run javascript.
 481 NOTE: Make sure
 482 .Cm enable_scripts
 483 is set to 0.
 484 .It Cm enable_plugins
 485 Enable plugins.
 486 .It Cm enable_scripts
 487 Enable scripts.
 488 .It Cm enable_socket
 489 When enabled the first instance of
 490 .Nm
 491 will create a socket in the
 492 .Pa ~/.xxxterm
 493 directory.
 494 Using the -n url option on subsequent
 495 .Nm
 496 invocations will cause the specified URL to be loaded in a new tab.
 497 Only a user with identical UID and GID can use this option.
 498 .It Cm fancy_bar
 499 Enables a backward, forward, and stop button to the toolbar.
 500 Additionally if
 501 .Cm search_string
 502 is set it'll enable an entry box for searches.
 503 .It Cm http_proxy
 504 Proxy server in URL format.
 505 .Nm
 506 overrides
 507 .Cm http_proxy
 508 if it is specified as an environment variable.
 509 It must be noted that one MUST use an IP address and not a FQDN.
 510 .Pp
 511 If one desires to use a socks proxy then an intermediary tool must be used.
 512 It has been reported that tsocks works with
 513 .Nm .
 514 .It Cm icon_size
 515 Permits icon sizes to be changed if
 516 .Cm fancy_bar
 517 is enabled.
 518 Size 1 is small; 2 is normal; 3 through 6 are progressively larger.
 519 .It Cm js_wl
 520 This is a javascript whitelist item.
 521 See
 522 .Cm cookie_wl
 523 for semantics and more details.
 524 .It Cm mime_type
 525 Sets an action for a specific or default MIME type.
 526 For example, to download and view a pdf using kpdf set mime_type =
 527 application/pdf,kpdf.
 528 To set a default value use *, for example mime_type = video/*,mplayer.
 529 Note that the action is only passed the URL and not all applications are
 530 capable of downloading content and therefore one might have to create a wrapper
 531 script to download the content first.
 532 .It Cm read_only_cookies
 533 Mark cookies file read-only and discard all cookies once the session is
 534 terminated.
 535 .It Cm refresh_interval
 536 Refresh interval while in the download manager.
 537 The default is 10.
 538 .It Cm resource_dir
 539 Directory that contains various
 540 .Nm
 541 resources such as icons.
 542 This is OS-specific and should be handled by the porter.
 543 .It Cm save_global_history
 544 If set the global history will be saved to
 545 .Pa ~/.xxxterm/history
 546 when quitting
 547 and restored at startup.
 548 See the
 549 .Sx KEY BINDINGS
 550 section above for how the global history is accessed.
 551 Global history is not saved to disk by default.
 552 .It Cm save_rejected_cookies
 553 Saves rejected cookies in cookie format in {work_dir}/rejected.txt.
 554 All cookies are saved and unlike a cookie jar they are never replaced.
 555 Make sure there is enough disk space to enable this feature.
 556 .It Cm search_string
 557 Default search engine string.
 558 See the
 559 .Pa xxxterm.conf
 560 file for details.
 561 .It Cm session_autosave
 562 Enable session auto-saving when changing state (e.g. adding or removing a tab).
 563 The session name is what is currently in use and is described in the
 564 .Cm session save
 565 and
 566 .Cm session open
 567 commands.
 568 .It Cm session_timeout
 569 If this value is greater than 3600 then it is the time added in seconds to a
 570 session cookie.
 571 If the value is smaller than 3600 then there is no change
 572 to the expiration of a session cookie.
 573 .It Cm show_tabs
 574 Enable or disable showing tabs.
 575 .It Cm show_url
 576 Enable or disable showing the url and toolbar.
 577 .It Cm single_instance
 578 If set only one
 579 .Nm
 580 will be permitted to run.
 581 If there is a URL specified it will be opened in a new tab in the already
 582 running
 583 .Nm
 584 session.
 585 .It Cm ssl_ca_file
 586 If set to a valid PEM file
 587 all server certificates will be validated against it.
 588 The URL bar will be colored green when the certificate is trusted
 589 and yellow when untrusted.
 590 .It Cm ssl_strict_certs
 591 If this value is set connections to untrusted sites will be aborted.
 592 This value is only used if
 593 .Cm ssl_ca_file
 594 is set.
 595 .It Cm user_agent
 596 Set to override the default
 597 .Nm
 598 user-agent string.
 599 .It Cm window_height
 600 Set the default height of the browser window.
 601 .It Cm window_width
 602 Set the default width of the browser window.
 603 If
 604 .Cm ssl_ca_file
 605 is not set then the URL bar will color all HTTPS connections red.
 606 .El
 607 .Sh HISTORY
 608 .Nm
 609 was inspired by vimprobable2 and the bloat in other
 610 .Ux
 611 web browsers.
 612 .Sh AUTHORS
 613 .An -nosplit
 614 .Nm
 615 was written by
 616 .An Marco Peereboom Aq marco@peereboom.us ,
 617 .An Stevan Andjelkovic Aq stevan@student.chalmers.se ,
 618 .An Edd Barrett Aq vext01@gmail.com ,
 619 and
 620 .An Todd T. Fries Aq todd@fries.net .
 621 .Sh BUGS
 622 When
 623 .Cm save_global_history
 624 is enabled
 625 .Nm
 626 is supposed to, in addition to restoring the global history, color the
 627 visited links accordingly; however due to bug #51747 in WebKit this does
 628 not happen.