diff options
| -rw-r--r-- | README | 393 | ||||
| -rw-r--r-- | man1/lariza.1 | 115 | ||||
| -rw-r--r-- | man1/lariza.usage.1 | 203 |
3 files changed, 368 insertions, 343 deletions
@@ -1,7 +1,6 @@ - - ========== + ====== lariza - ========== + ====== A simple web browser using GTK+ 3, GLib and WebKit2GTK+. @@ -22,367 +21,75 @@ Features: - Adblock -============== -About the name -============== - -"lariza" stems from a german sentence: - - Alle anderen waren mir zu anstrengend. - l a r i z a - -That phrase basically means: "It was too tiresome to deal with any other -browser." I couldn't find a simple browser that does just what I need. -Most of them are utterly bloated, others lack essential functions. Thus, -I was forced to write scripts and tools and stuff to deal with these -issues. That is what was tiresome. I don't want to work around bugs or -nonsensical behavior anymore. - -So, I wrote my own browser^W WebKit GUI. WebKit does all the dirty work. - - -================================ -What lariza is and what it's not -================================ - -lariza does what I need. It won't do other things. I'm open for pull -requests but please don't be upset if I turn them down -- which might -happen if it's a feature that I simply don't need. - -Especially, it's very likely that lariza will never have a "follow -mode" like dwb, luakit or others have. I've used these browsers for -quite some time and I've also used Firefox extensions that add a "follow -mode". The point is, "follow mode" doesn't work anymore. This was a good -thing ten years ago. Today, a lot of websites make heavy use of -JavaScript or hovering. You NEED some kind of pointing device. I found -using "follow mode" to be very frustrating today, because you still have -to reach for the mouse all the time. So, you might as well just optimize -your mousing workflow. - -lariza does not compete with powerful browsers like dwb or luakit, nor -with monstrous applications like Firefox or Chromium. lariza won't have -persistent storage, nor a plugin system, nor cloud sync, nor bookmarks. - -lariza tries not to exceed 1000 lines of code. - - -======================== -Using lariza with tabbed -======================== - -By default, lariza automatically launches an instance of suckless' -tabbed. - -You can turn this feature off (see command line arguments) or you can -specify a command line argument to embed lariza in an arbitrary -container (XEMBED). Note that lariza will also automatically embed new -windows in the same container. - -When using the automatically launched tabbed instance, you can't use -tabbed's Ctrl + Shift + Return hotkey. This is because tabbed is -launched with "-d", so it knows nothing about lariza. However, lariza -provides its own hotkey to launch a new window which will be embedded in -the same instance of tabbed. - - -======= -Hotkeys -======= - -Main windows - - When the WebKit viewport is focused: - - Mod1 + q - Close the current window. - - Mod1 + w - Go to your "homepage". See the environment variable - $LARIZA_HOME_URI. - - Mod1 + e - Open a new window. - - Mod1 + r - Reload the current page. - - Mod1 + d - Open the download manager. - - Mod1 + l - Focus the location bar. - - Mod1 + k - Focus the location bar and set its text to "/", allowing you - to easily initiate a search. - - Mod1 + 2 or Mod1 + n - Repeat the last search (forward). - - Mod1 + 3 - Repeat the last search (backward). - - Mod1 + c - Reload trusted certificates. - - Escape - Stop loading. - - Middle mouse - Open the link under the pointer in a new window. - - Backward / forward (mouse keys 8 and 9) - Does the obvious. - - Mod1 + Scroll up or Ctrl + Scroll up - Increase zoom level of the current page. - - Mod1 + Scroll down or Ctrl + Scroll down - Decrase zoom level of the current page. - - Mod1 + Scroll horizontally or Ctrl + Scroll horizontally - Reset zoom to $LARIZA_ZOOM. - - - When the location bar is focused: - - Mod1 + q - Close the current window. - - Mod1 + d - Open the download manager. - - Mod1 + r - Reload the current page. - - Mod1 + k - Reset the content of the location bar to "/". - - Mod1 + c - Reload trusted certificates. - - Escape - Reset the content of the location bar to the current URI. - - Return - "Commit", i.e. begin searching, do a keyword based search or - open the URI. - - -Download manager - - Mod1 + d - Close the download manager (downloads are not aborted). - - -====================== -Command line arguments -====================== - -Usage: - - lariza [OPTION]... [URI]... - -In addition to the standard arguments of GTK+ 3, lariza knows about the -following options: - - -e <wid> - Embeds the main window and all newly created windows in the - window specified by <wid>. The download manager is always a - "popup". - - -C - Disables cooperative instances. - - -T - Disables automatic launching of suckless' tabbed. - -After these options there can be any number of URIs. If no URIs are -given, $LARIZA_HOME_URI will be opened. - - -===================== -Environment variables -===================== - -In addition to the standard variables of GTK+ 3, lariza knows about the -following environment variables: - - LARIZA_ACCEPTED_LANGUAGE - In HTTP requests, WebKit sets the "Accepted-Language" header to - this value. Defaults to "en-US". - - LARIZA_CRASH_AUTORELOAD_DELAY - If/when the WebKit process crashes, lariza's main process will - receive a signal and can act accordingly. The default value of - this variable is "2", which means that lariza will wait two - seconds and then reload each window/tab. - - If you set $LARIZA_CRASH_AUTORELOAD_DELAY to zero or any - negative value, then lariza will not automatically reload - anything. Note, however, that you can still do this manually by - pressing the "reload" hotkey for each window. - - LARIZA_DOWNLOAD_DIR - All downloads are automatically stored in this directory. If you - want to stick to XDG directories, then you should configure your - "xdg-user-dirs" and use this: - - LARIZA_DOWNLOAD_DIR=$(xdg-user-dir DOWNLOAD) - - This variable defaults to "/var/tmp". - - LARIZA_FIFO_SUFFIX - Cooperative instances are implemented using a named pipe in the - file system. The name of this pipe usually is (at least on - modern systems following XDG "standards"): - - /var/run/user/$UID/lariza.fifo-$LARIZA_FIFO_SUFFIX - - $UID is the id of your user. $LARIZA_FIFO_SUFFIX defaults to - "main". If you change this variable, you can launch several - independent cooperative instances of lariza. - - LARIZA_HOME_URI - This URI will be opened by pressing the appropriate hotkeys - ("homepage" or "new window") and if no URIs are specified on the - command line. Defaults to "about:blank". - - LARIZA_USER_AGENT - Lariza will identify itself with this string. Uses WebKit's - default value if unset. - - LARIZA_WEB_EXTENSIONS_DIR - Sets the directory where WebKit will look for "web extensions". - Defaults to "~/.local/share/lariza/web_extensions". - - LARIZA_ZOOM - Zoom level for WebKit viewports. Defaults to 1.0. - - -======================= -Keyword based searching -======================= - -In this file, you can configure keywords and the associated URIs: - - ~/.config/lariza/keywordsearch - -Each line has to look like this: - - wi https://en.wikipedia.org/w/index.php?title=Special:Search&search=%s - -"wi" is the keyword, so when opening "wi foo", lariza will search in -Wikipedia. Note the "%s" at the end of the URI: This is where your -search term will be placed. - -Lines starting with "#" are ignored. - - -================ -Download manager -================ - -Open the download manager using the appropriate hotkey. A new window -listing your downloads will appear. Clicking on an item will remove it -from the list and -- if needed -- cancel the download. - -There's no file manager integration (I don't use one), nor does lariza -delete, overwrite or resume downloads. If a file already exists, it -won't be touched. Instead, the new file name will have a suffix such as -".1", ".2", ".3" and so on. - - -====================== -Bundled web extensions -====================== - -On startup, WebKit checks ~/.local/share/lariza/web_extensions for any -.so files. See this blog post for further information on these -extensions: - -http://blogs.igalia.com/carlosgc/2013/09/10/webkit2gtk-web-process-extensions/ - -lariza comes with the following extensions: - - we_adblock.so - - Generic adblock. Reads patterns from the following file: - - ~/.config/lariza/adblock.black - - Each line can contain a regular expression. These expressions - match case-insensitive and partially, i.e. ".*foo.*" is the same - as ".*FOO.*" and you can use anchors like "^https?://...". +Installation +------------ - Lines starting with "#" are ignored. +The following C libraries are required: -Those bundled web extensions are automatically compiled when you run -make. To use them, though, make sure to copy them to the directory -mentioned above. + - GTK+ 3 + - WebKit2 API for GTK+ 3 +lariza expects to be run on a POSIX-ish operating system. -==================== -Trusted certificates -==================== +To build the program and install it to /usr/local: -By default, lariza trusts whatever CAs are trusted by WebKit, i.e. by -your GnuTLS installation. If you wish to trust additional certificates, -such as self-signed certificates, the first thing you should do is try -to add the appropriate CAs to your system-wide store. + $ make + # make install -If you wish to add simple exceptions, you can grab the certificate and -store it in the directory ~/.config/lariza/certs. The filename must be -equal to the hostname: +To use bundled web extensions, they must be copied or symlinked to the +appropriate path. Please refer to the manpage. - $ echo | openssl s_client -connect foo.de:443 | openssl x509 >foo.de -This tells lariza to trust the given certificate when connecting to host -"foo.de". +Running +------- -You can reload these certificates at runtime by pressing the appropriate -hotkey (see above). Note that removed certificates will be kept in -memory until you restart lariza. +You simply invoke the main program: -Note: This is NOT equal to certificate pinning. WebKit ignores -user-specified certificates if the server's certificate can be validated -by any system-wide CA. + $ lariza +Refer to the manpage for all options. -==================== -WebKit local storage -==================== -WebKit does create files in your $XDG_* directories, i.e. ~/.local/share -or ~/.cache. It's up to you what you want to do with this junk. I remove -it regularly when no WebKit browser is running. Another option would be -to change the $XDG_* variables. +Background information +---------------------- -I have explicitly not turned off the local storage feature in WebKit -because I don't know if this breaks web applications. + What lariza is and what it's not + lariza does what I need. It won't do other things. I'm open for pull + requests but please don't be upset if I turn them down -- which might + happen if it's a feature that I simply don't need. -============ -Dependencies -============ + Especially, it's very likely that lariza will never have a "follow + mode" like dwb, luakit or others have. I've used these browsers for + quite some time and I've also used Firefox extensions that add a + "follow mode". The point is, "follow mode" doesn't work anymore. This + was a good thing ten years ago. Today, a lot of websites make heavy + use of JavaScript or hovering. You NEED some kind of pointing device. + I found using "follow mode" to be very frustrating today, because you + still have to reach for the mouse all the time. So, you might as well + just optimize your mousing workflow. -lariza needs the following Arch Linux packages: + lariza does not compete with powerful browsers like dwb or luakit, nor + with monstrous applications like Firefox or Chromium. lariza won't + have persistent storage, nor a plugin system, nor cloud sync, nor + bookmarks. - - gtk3 - - webkit2gtk (WebKit2 API for GTK+ 3) + lariza tries not to exceed 1000 lines of code. -========== -Literature -========== + About the name -API references: + "lariza" stems from a german sentence: - - http://webkitgtk.org/reference/webkit2gtk/stable/index.html - - https://developer.gnome.org/gtk3/stable/index.html - - https://developer.gnome.org/glib/stable/index.html + Alle anderen waren mir zu anstrengend. + l a r i z a -Regular expressions supported by GRegex, you can use these in your -adblock patterns: + That phrase basically means: "It was too tiresome to deal with any + other browser." I couldn't find a simple browser that does just what I + need. Most of them are utterly bloated, others lack essential + functions. Thus, I was forced to write scripts and tools and stuff to + deal with these issues. That is what was tiresome. I don't want to + work around bugs or nonsensical behavior anymore. - - https://developer.gnome.org/glib/stable/glib-regex-syntax.html + So, I wrote my own browser^W WebKit GUI. WebKit does all the dirty + work. diff --git a/man1/lariza.1 b/man1/lariza.1 new file mode 100644 index 0000000..a8f504e --- /dev/null +++ b/man1/lariza.1 @@ -0,0 +1,115 @@ +.TH lariza 1 "2015-11-28" "lariza" "User Commands" +.\" -------------------------------------------------------------------- +.SH NAME +lariza \- simple web browser +.\" -------------------------------------------------------------------- +.SH SYNOPSIS +\fBlariza\fP +[\fB\-e\fP \fIwid\fP] +[\fB\-C\fP] +[\fB\-T\fP] +[\fIURI ...\fP] +.\" -------------------------------------------------------------------- +.SH DESCRIPTION +\fBlariza\fP is a simple web browser using GTK+ 3, GLib and WebKit2GTK+. +.\" -------------------------------------------------------------------- +.SH OPTIONS +In addition to the standard arguments of GTK+ 3, \fBlariza\fP knows +about the following options: +.TP +\fB\-e\fP \fIwid\fP +Embeds the main window and all newly created windows in the window +specified by \fIwid\fP. The download manager is always a \(lqpopup\(rq. +.TP +\fB\-C\fP +Disables cooperative instances. +.TP +\fB\-T\fP +Disables automatic launching of suckless' \fBtabbed\fP(1). +.P +After these options there can be any number of URIs. If no URIs are +given, $\fBLARIZA_HOME_URI\fP will be opened. +.\" -------------------------------------------------------------------- +.SH ENVIRONMENT +In addition to the standard variables of GTK+ 3, \fBlariza\fP knows +about the following environment variables: +.P +.TP +\fBLARIZA_ACCEPTED_LANGUAGE\fP +In HTTP requests, WebKit sets the \(lqAccepted-Language\(rq header to +this value. Defaults to \fBen-US\fP. +.TP +\fBLARIZA_CRASH_AUTORELOAD_DELAY\fP +If/when the WebKit process crashes, \fBlariza\fP's main process will +receive a signal and can act accordingly. The default value of this +variable is \fB2\fP, which means that \fBlariza\fP will wait two seconds +and then reload each window/tab. + +If you set $\fBLARIZA_CRASH_AUTORELOAD_DELAY\fP to zero or any negative +value, then \fBlariza\fP will not automatically reload anything. Note, +however, that you can still do this manually by pressing the +\(lqreload\(rq hotkey for each window. +.TP +\fBLARIZA_DOWNLOAD_DIR\fP +All downloads are automatically stored in this directory. If you want to +stick to XDG directories, then you should configure your +\(lqxdg-user-dirs\(rq and use this: + +\f(CW +.nf +\&LARIZA_DOWNLOAD_DIR=$(xdg-user-dir DOWNLOAD) +.fi +\fP + +This variable defaults to \fB/var/tmp\fP. +.TP +\fBLARIZA_FIFO_SUFFIX\fP +Cooperative instances are implemented using a named pipe in the file +system. The name of this pipe usually is (at least on modern systems +following XDG \(lqstandards\(rq): +\fI/var\:/run\:/user\:/$UID\:/lariza.fifo\:-$LARIZA_FIFO_SUFFIX\fP. + +$\fBUID\fP is the id of your user. $\fBLARIZA_FIFO_SUFFIX\fP defaults to +\fBmain\fP. If you change this variable, you can launch several +independent cooperative instances of \fBlariza\fP. +.TP +\fBLARIZA_HOME_URI\fP +This URI will be opened by pressing the appropriate hotkeys +(\(lqhomepage\(rq or \(lqnew window\(rq) and if no URIs are specified on +the command line. Defaults to \fBabout:blank\fP. +.TP +\fBLARIZA_USER_AGENT\fP +\fBlariza\fP will identify itself with this string. Uses WebKit's +default value if unset. +.TP +\fBLARIZA_WEB_EXTENSIONS_DIR\fP +Sets the directory where WebKit will look for \fBweb extensions\fP. +Defaults to \fI~/.local\:/share\:/lariza\:/web_extensions\fP. +.TP +\fBLARIZA_ZOOM +Zoom level for WebKit viewports. Defaults to \fB1.0\fP. +.\" -------------------------------------------------------------------- +.SH FILES +.TP +\fI~/.config\:/lariza\:/adblock.black\fP +Adblock patterns. See \fBlariza.usage\fP(1). +.TP +\fI~/.config\:/lariza\:/certs\fP +Directory where trusted certificates are stored. See +\fBlariza.usage\fP(1). +.TP +\fI~/.config\:/lariza\:/keywordsearch\fP +Configuration file for keyword base searching. See +\fBlariza.usage\fP(1). +.\" -------------------------------------------------------------------- +.SH LICENSE +\fBlariza\fP is released as \(lqPIZZA-WARE\(rq. See the accompanying +\fILICENSE\fP file. +.\" -------------------------------------------------------------------- +.SH HISTORY +\fBlariza\fP was originally written by Peter Hofmann. The project +was started in June 2014. +.\" -------------------------------------------------------------------- +.SH "SEE ALSO" +.BR lariza.usage (1), +.BR tabbed (1). diff --git a/man1/lariza.usage.1 b/man1/lariza.usage.1 new file mode 100644 index 0000000..7c4cb1b --- /dev/null +++ b/man1/lariza.usage.1 @@ -0,0 +1,203 @@ +.TH lariza 1 "2015-11-28" "lariza" "User Commands" +.\" -------------------------------------------------------------------- +.SH NAME +lariza.usage \- extended usage hints +.\" -------------------------------------------------------------------- +.SH DESCRIPTION +\fBlariza\fP is a simple web browser using GTK+ 3, GLib and WebKit2GTK+. +This manpage contains additional hints and pointers regarding its usage. +.\" -------------------------------------------------------------------- +.SH "BUNDLED WEB EXTENSIONS" +On startup, WebKit checks \fI~/.local/share/lariza/web_extensions\fP for +any \fB.so\fP files. See +.UR http://\:blogs.igalia.com/\:carlosgc/\:2013/\:09/\:10/\:webkit2gtk-\:web-\:process-\:extensions/ +this blog post +.UE +for further information on these extensions. +.P +\fBlariza\fP comes with the following extensions: +.TP +\fBwe_adblock.so\fP +Generic adblock. Reads patterns from the file +\fI~/.config/lariza/adblock.black\fP. Each line can contain a regular +expression. These expressions match case-insensitive and partially, i.e. +\fB.*foo.*\fP is the same as \fB.*FOO.*\fP and you can use anchors like +\fB^https?://...\fP. Please refer to +.UR https://\:developer.\:gnome.\:org/\:glib/\:stable/\:glib-\:regex-\:syntax.html +the GLib reference +.UE +for more details. Lines starting with \fB#\fP are ignored. +.P +Those bundled web extensions are automatically compiled when you run +\fBmake\fP. To use them, though, make sure to copy them to the directory +mentioned above. +.\" -------------------------------------------------------------------- +.SH "DOWNLOAD MANAGER" +Open the download manager using the appropriate hotkey. A new window +listing your downloads will appear. Clicking on an item will remove it +from the list and \(em if needed \(em cancel the download. +.P +There's no file manager integration, nor does \fBlariza\fP delete, +overwrite or resume downloads. If a file already exists, it won't be +touched. Instead, the new file name will have a suffix such as \fB.1\fP, +\fB.2\fP, \fB.3\fP, and so on. +.\" -------------------------------------------------------------------- +.SH "HOTKEYS" +.SS "Main window \(em WebKit viewport focused" +.TP +\fBMod1\fP + \fBq\fP +Close the current window. +.TP +\fBMod1\fP + \fBw\fP +Go to your \(lqhomepage\(rq. See the environment variable +$\fBLARIZA_HOME_URI\fP. +.TP +\fBMod1\fP + \fBe\fP +Open a new window. +.TP +\fBMod1\fP + \fBr\fP +Reload the current page. +.TP +\fBMod1\fP + \fBd\fP +Open the download manager. +.TP +\fBMod1\fP + \fBl\fP +Focus the location bar. +.TP +\fBMod1\fP + \fBk\fP +Focus the location bar and set its text to \fB/\fP, allowing you to +easily initiate a search. +.TP +\fBMod1\fP + \fB2\fP +.TQ +\fBMod1\fP + \fBn\fP +Repeat the last search (forward). +.TP +\fBMod1\fP + \fB3\fP +Repeat the last search (backward). +.TP +\fBMod1\fP + \fBc\fP +Reload trusted certificates. +.TP +\fBEscape\fP +Stop loading. +.TP +\fBMiddle mouse\fP +Open the link under the pointer in a new window. +.TP +\fBBackward\fP / \fBforward\fP (mouse keys 8 and 9) +Does the obvious. +.TP +\fBMod1\fP + \fBScroll up\fP +.TQ +\fBCtrl\fP + \fBScroll up\fP +Increase zoom level of the current page. +.TP +\fBMod1\fP + \fBScroll down\fP +.TQ +\fBCtrl\fP + \fBScroll down\fP +Decrase zoom level of the current page. +.TP +\fBMod1\fP + \fBScroll horizontally\fP +.TQ +\fBCtrl\fP + \fBScroll horizontally\fP +Reset zoom to $\fBLARIZA_ZOOM\fP. +.P +.SS "Main window \(em location bar focused" +.TP +\fBMod1\fP + \fBq\fP +Close the current window. +.TP +\fBMod1\fP + \fBd\fP +Open the download manager. +.TP +\fBMod1\fP + \fBr\fP +Reload the current page. +.TP +\fBMod1\fP + \fBk\fP +Reset the content of the location bar to \fB/\fP. +.TP +\fBMod1\fP + \fBc\fP +Reload trusted certificates. +.TP +\fBEscape\fP +Reset the content of the location bar to the current URI. +.TP +\fBReturn\fP +Commit, i.e. begin searching, do a keyword based search or open the URI. +.SS "Download manager" +.TP +\fBMod1\fP + \fBd\fP +Close the download manager (downloads are not aborted). +.\" -------------------------------------------------------------------- +.SH "KEYWORD BASED SEARCHING" +In this file, you can configure keywords and the associated URIs: +\fI~/.config\:/lariza\:/keywordsearch\fP. Each line has to look like +this: +.P +\f(CW +.nf +\&wi https://en.wikipedia.org/w/index.php?title=Special:Search&search=%s +.fi +\fP +.P +\fBwi\fP is the keyword, so when opening \fBwi foo\fP, \fBlariza\fP +will search in Wikipedia. Note the \fB%s\fP at the end of the URI: This +is where your search term will be placed. +.P +Lines starting with \fB#\fP are ignored. +.\" -------------------------------------------------------------------- +.SH "TRUSTED CERTIFICATES" +By default, \fBlariza\fP trusts whatever CAs are trusted by WebKit, i.e. by +your GnuTLS installation. If you wish to trust additional certificates, +such as self-signed certificates, the first thing you should do is try +to add the appropriate CAs to your system-wide store. +.P +If you wish to add simple exceptions, you can grab the certificate and +store it in the directory \fI~/.config/lariza/certs\fP. The filename +must be equal to the hostname: +.P +.\f(CW +.nf +\&$ echo | openssl s_client -connect foo.de:443 | openssl x509 >foo.de +.fi +\fP +.P +This tells \fBlariza\fP to trust the given certificate when connecting +to host \fBfoo.de\fP. +.P +You can reload these certificates at runtime by pressing the appropriate +hotkey. Note that removed certificates will be kept in memory until you +restart \fBlariza\fP. +.P +Note: This is NOT equal to certificate pinning. WebKit ignores +user-specified certificates if the server's certificate can be validated +by any system-wide CA. +.\" -------------------------------------------------------------------- +.SH "USING LARIZA WITH TABBED" +By default, \fBlariza\fP automatically launches an instance of suckless' +\fBtabbed\fP(1). +.P +You can turn this feature off (see command line arguments) or you can +specify a command line argument to embed \fBlariza\fP into an arbitrary +container (XEMBED). Note that \fBlariza\fP will also automatically embed +new windows in the same container. +.P +When using the automatically launched \fBtabbed\fP(1) instance, you +can't use \fBtabbed\fP(1)'s \fBCtrl + Shift + Return\fP hotkey. This is +because \fBtabbed\fP(1) is launched with \fB\-d\fP, so it knows nothing +about \fBlariza\fP. However, \fBlariza\fP provides its own hotkey to +launch a new window which will be embedded in the same instance of +\fBtabbed\fP(1). +.\" -------------------------------------------------------------------- +.SH "WEBKIT LOCAL STORAGE" +WebKit does create files in your $\fBXDG_*\fP directories, i.e. +\fI~/.local/share\fP or \fI~/.cache\fP. It's up to you what you want to +do with this junk. I remove it regularly when no WebKit browser is +running. Another option would be to change the $\fBXDG_*\fP variables. +.P +I have explicitly not turned off the local storage feature in WebKit +because I don't know if this breaks web applications. +.\" -------------------------------------------------------------------- +.SH "SEE ALSO" +.BR lariza (1). |