diff options
| -rw-r--r-- | MANIFEST.in | 1 | ||||
| -rw-r--r-- | doc/faq.asciidoc | 335 | ||||
| -rw-r--r-- | qutebrowser/api/cmdutils.py | 34 | ||||
| -rw-r--r-- | qutebrowser/keyinput/modeman.py | 2 |
4 files changed, 20 insertions, 352 deletions
diff --git a/MANIFEST.in b/MANIFEST.in index 3a29ba690..cd9e50cf9 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -40,5 +40,6 @@ exclude .* exclude misc/qutebrowser.spec exclude misc/qutebrowser.nsi exclude misc/qutebrowser.rcc +prune doc/extapi global-exclude __pycache__ *.pyc *.pyo diff --git a/doc/faq.asciidoc b/doc/faq.asciidoc deleted file mode 100644 index 113a11f09..000000000 --- a/doc/faq.asciidoc +++ /dev/null @@ -1,335 +0,0 @@ -Frequently asked questions -========================== -:title: Frequently asked questions -The Compiler <mail@qutebrowser.org> - -[qanda] -What is qutebrowser based on?:: - qutebrowser uses https://www.python.org/[Python], https://www.qt.io/[Qt] and - https://www.riverbankcomputing.com/software/pyqt/intro[PyQt]. -+ -The concept of it is largely inspired by https://bitbucket.org/portix/dwb/[dwb] -and http://www.vimperator.org/vimperator[Vimperator]. Many actions and -key bindings are similar to dwb. - -Why another browser?:: - It might be hard to believe, but I didn't find any browser which I was - happy with, so I started to write my own. Also, I needed a project to get - into writing GUI applications with Python and - link:https://www.qt.io/[Qt]/link:https://www.riverbankcomputing.com/software/pyqt/intro[PyQt]. -+ -Read the next few questions to find out why I was unhappy with existing -software. - -What's wrong with link:https://bitbucket.org/portix/dwb/[dwb]/link:https://sourceforge.net/projects/vimprobable/[vimprobable]/link:https://mason-larobina.github.io/luakit/[luakit]/jumanji/... (projects based on WebKitGTK)?:: - Most of them are based on the https://webkitgtk.org/[WebKitGTK+] - https://webkitgtk.org/reference/webkitgtk/stable/index.html[WebKit1] API, - which causes a lot of crashes. As the GTK API using WebKit1 is - https://lists.webkit.org/pipermail/webkit-gtk/2014-March/001821.html[deprecated], - these bugs are never going to be fixed. -+ -When qutebrowser was created, the newer -https://webkitgtk.org/reference/webkit2gtk/stable/index.html[WebKit2 API] lacked -basic features like proxy support, and almost no projects have started porting -to WebKit2. In the meantime, this situation has improved a bit, but there are -still only a few projects which have some kind of WebKit2 support (see the -https://github.com/qutebrowser/qutebrowser#similar-projects[list of -alternatives]). -+ -qutebrowser uses https://www.qt.io/[Qt] and -https://wiki.qt.io/QtWebEngine[QtWebEngine] by default (and supports -https://wiki.qt.io/QtWebKit[QtWebKit] optionally). QtWebEngine is based on -Google's https://www.chromium.org/Home[Chromium]. With an up-to-date Qt, it has -much more man-power behind it than WebKitGTK+ has, and thus supports more modern -web features - it's also arguably more secure. - -What's wrong with https://www.mozilla.org/en-US/firefox/new/[Firefox] and link:http://bug.5digits.org/pentadactyl/[Pentadactyl]/link:http://www.vimperator.org/vimperator[Vimperator]?:: - Firefox likes to break compatibility with addons on each upgrade, gets - slower and more bloated with every upgrade, and has some - https://blog.mozilla.org/advancingcontent/2014/02/11/publisher-transformation-with-users-at-the-center/[horrible - ideas] lately. -+ -Also, developing addons for it is a nightmare. - -What's wrong with https://www.chromium.org/Home[Chromium] and https://vimium.github.io/[Vimium]?:: - The Chrome plugin API doesn't seem to allow much freedom for plugin - writers, which results in Vimium not really having all the features you'd - expect from a proper minimal, vim-like browser. - -Why Python?:: - I enjoy writing Python since 2011, which made it one of the possible - choices. I wanted to use https://www.qt.io/[Qt] because of - https://wiki.qt.io/QtWebKit[QtWebKit] so I didn't have - https://wiki.qt.io/Category:LanguageBindings[many other choices]. I don't - like C++ and can't write it very well, so that wasn't an alternative. - -But isn't Python too slow for a browser?:: - https://www.infoworld.com/d/application-development/van-rossum-python-not-too-slow-188715[No.] - I believe efficiency while coding is a lot more important than efficiency - while running. Also, most of the heavy lifting of qutebrowser is done by Qt - and WebKit in C++, with the - https://wiki.python.org/moin/GlobalInterpreterLock[GIL] released. - -Is qutebrowser secure?:: - Most security issues are in the backend (which handles networking, - rendering, JavaScript, etc.) and not qutebrowser itself. -+ -qutebrowser uses https://wiki.qt.io/QtWebEngine[QtWebEngine] by default. -QtWebEngine is based on Google's https://www.chromium.org/Home[Chromium]. While -Qt only updates to a new Chromium release on every minor Qt release (all ~6 -months), every patch release backports security fixes from newer Chromium -versions. In other words: As long as you're using an up-to-date Qt, you should -be recieving security updates on a regular basis, without qutebrowser having to -do anything. Chromium's process isolation and -https://chromium.googlesource.com/chromium/src/+/master/docs/design/sandbox.md[sandboxing] -features are also enabled as a second line of defense. -+ -https://wiki.qt.io/QtWebKit[QtWebKit] is also supported as an alternative -backend, but hasn't seen new releases -https://github.com/annulen/webkit/releases[in a while]. It also doesn't have any -process isolation or sandboxing. See -https://github.com/qutebrowser/qutebrowser/issues/4039[#4039] for more details. -+ -Security issues in qutebrowser's code happen very rarely (as per July 2018, -there have been three security issues caused by qutebrowser in over 4.5 years). -Those were handled appropriately -(http://seclists.org/oss-sec/2018/q3/29[example]) and fixed timely. To report -security bugs, please contact me directly at mail@qutebrowser.org, GPG ID -https://www.the-compiler.org/pubkey.asc[0x916eb0c8fd55a072]. - -Is there an adblocker?:: - There is a host-based adblocker which takes /etc/hosts-like lists. A "real" - adblocker has a - https://www.reddit.com/r/programming/comments/25j41u/adblock_pluss_effect_on_firefoxs_memory_usage/chhpomw[big - impact] on browsing speed and - https://blog.mozilla.org/nnethercote/2014/05/14/adblock-pluss-effect-on-firefoxs-memory-usage/[RAM - usage], so implementing support for AdBlockPlus-like lists is currently not - a priority. - -How can I get No-Script-like behavior?:: - To disable JavaScript by default: -+ ----- -:set content.javascript.enabled false ----- -+ -The basic command for enabling JavaScript for the current host is `tsh`. -This will allow JavaScript execution for the current session. -Use `S` instead of `s` to make the exception permanent. -With `H` instead of `h`, subdomains are included. -With `u` instead of `h`, only the current URL is whitelisted (not the whole host). - -How do I play Youtube videos with mpv?:: - You can easily add a key binding to play youtube videos inside a real video - player - optionally even with hinting for links: -+ ----- -:bind m spawn mpv {url} -:bind M hint links spawn mpv {hint-url} ----- -+ -Note that you might need an additional package (e.g. -https://www.archlinux.org/packages/community/any/youtube-dl/[youtube-dl] on -Archlinux) to play web videos with mpv. -+ -There is a very useful script for mpv, which emulates "unique application" -functionality. This way you can add links to the mpv playlist instead of -playing them all at once. -+ -You can find the script here: https://github.com/mpv-player/mpv/blob/master/TOOLS/umpv -+ -It also works nicely with rapid hints: -+ ----- -:bind m spawn umpv {url} -:bind M hint links spawn umpv {hint-url} -:bind ;M hint --rapid links spawn umpv {hint-url} ----- - -How do I use qutebrowser with mutt?:: - For security reasons, local files without `.html` extensions aren't - rendered as HTML, see - https://bugs.chromium.org/p/chromium/issues/detail?id=777737[this Chromium issue] - for details. You can do this in your `mailcap` file to get a proper - extension: -+ ----- - text/html; qutebrowser %s; nametemplate=%s.html ----- - -What is the difference between bookmarks and quickmarks?:: - Bookmarks will always use the title of the website as their name, but with quickmarks - you can set your own title. -+ -For example, if you bookmark multiple food recipe websites and use `:open`, -you have to type the title or address of the website. -+ -When using quickmark, you can give them all names, like -`foodrecipes1`, `foodrecipes2` and so on. When you type -`:open foodrecipes`, you will see a list of all the food recipe sites, -without having to remember the exact website title or address. - -How do I use spell checking?:: - Configuring spell checking in qutebrowser depends on the backend in use - (see https://github.com/qutebrowser/qutebrowser/issues/700[#700] for - a more detailed discussion). -+ -For QtWebKit: - -. Install https://github.com/QupZilla/qtwebkit-plugins[qtwebkit-plugins]. - . Note: with QtWebKit reloaded you may experience some issues. See - https://github.com/QupZilla/qtwebkit-plugins/issues/10[#10]. -. The dictionary to use is taken from the `DICTIONARY` environment variable. - The default is `en_US`. For example to use Dutch spell check set `DICTIONARY` - to `nl_NL`; you can't use multiple dictionaries or change them at runtime at - the moment. - (also see the README file for `qtwebkit-plugins`). -. Remember to install the hunspell dictionaries if you don't have them already - (most distros should have packages for this). - -+ -For QtWebEngine: - -. Make sure your versions of PyQt and Qt are 5.8 or higher. -. Use `dictcli.py` script to install dictionaries. - Run the script with `-h` for the parameter description. -. Set `spellcheck.languages` to the desired list of languages, e.g.: - `:set spellcheck.languages "['en-US', 'pl-PL']"` - -How do I use Tor with qutebrowser?:: - Start tor on your machine, and do `:set content.proxy socks://localhost:9050/` - in qutebrowser. Note this won't give you the same amount of fingerprinting - protection that the Tor Browser does, but it's useful to be able to access - `.onion` sites. - -Why does J move to the next (right) tab, and K to the previous (left) one?:: - One reason is because https://bitbucket.org/portix/dwb[dwb] did it that way, - and qutebrowser's keybindings are designed to be compatible with dwb's. - The rationale behind it is that J is "down" in vim, and K is "up", which - corresponds nicely to "next"/"previous". It also makes much more sense with - vertical tabs (e.g. `:set tabs.position left`). - -What's the difference between insert and passthrough mode?:: - They are quite similar, but insert mode has some bindings (like `Ctrl-e` to - open an editor) while passthrough mode only has escape bound. It might also - be useful to rebind escape to something else in passthrough mode only, to be - able to send an escape keypress to the website. - -Why does it take longer to open a URL in qutebrowser than in chromium?:: - When opening a URL in an existing instance, the normal qutebrowser - Python script is started and a few PyQt libraries need to be - loaded until it is detected that there is an instance running - to which the URL is then passed. This takes some time. - One workaround is to use this - https://github.com/qutebrowser/qutebrowser/blob/master/scripts/open_url_in_instance.sh[script] - and place it in your $PATH with the name "qutebrowser". This - script passes the URL via an unix socket to qutebrowser (if its - running already) using socat which is much faster and starts a new - qutebrowser if it is not running already. Also check if you want - to use webengine as backend in line 17 and change it to your - needs. - -How do I make qutebrowser use greasemonkey scripts?:: - There is currently no UI elements to handle managing greasemonkey scripts. - All management of what scripts are installed or disabled is done in the - filesystem by you. qutebrowser reads all files that have an extension of - `.js` from the `<data>/greasemonkey/` folder and attempts to load them. - Where `<data>` is the qutebrowser data directory shown in the `Paths` - section of the page displayed by `:version`. If you want to disable a - script just rename it, for example, to have `.disabled` on the end, after - the `.js` extension. To reload scripts from that directory run the command - `:greasemonkey-reload`. -+ -Troubleshooting: to check that your script is being loaded when -`:greasemonkey-reload` runs you can start qutebrowser with the arguments -`--debug --logfilter greasemonkey,js` and check the messages on the -program's standard output for errors parsing or loading your script. -You may also see javascript errors if your script is expecting an environment -that we fail to provide. -+ -Note that there are some missing features which you may run into: - -. Some scripts expect `GM_xmlhttpRequest` to ignore Cross Origin Resource - Sharing restrictions, this is currently not supported, so scripts making - requests to third party sites will often fail to function correctly. -. If your backend is a QtWebEngine version 5.8, 5.9 or 5.10 then regular - expressions are not supported in `@include` or `@exclude` rules. If your - script uses them you can re-write them to use glob expressions or convert - them to `@match` rules. - See https://wiki.greasespot.net/Metadata_Block[the wiki] for more info. -. Any greasemonkey API function to do with adding UI elements is not currently - supported. That means context menu extentensions and background pages. - -How do I change the `WM_CLASS` used by qutebrowser windows?:: - Qt only supports setting `WM_CLASS` globally, which you can do by starting - with `--qt-arg name foo`. Note that all windows are part of the same - qutebrowser instance (unless you use `--temp-basedir` or `--basedir`), so - they all will share the same `WM_CLASS`. - -== Troubleshooting - -Unable to view flash content.:: - If you have flash installed for on your system, it's necessary to enable plugins - to use the flash plugin. Using the command `:set content.plugins true` - in qutebrowser will enable plugins. Packages for flash should - be provided for your platform or it can be obtained from - https://get.adobe.com/flashplayer/[Adobe]. - -Experiencing freezing on sites like duckduckgo and youtube.:: - This issue could be caused by stale plugin files installed by `mozplugger` - if mozplugger was subsequently removed. - Try exiting qutebrowser and removing `~/.mozilla/plugins/mozplugger*.so`. - See https://github.com/qutebrowser/qutebrowser/issues/357[Issue #357] - for more details. - -When using QtWebEngine, qutebrowser reports "Render Process Crashed" and the console prints a traceback on Gentoo Linux or another Source-Based Distro:: - As stated in https://gcc.gnu.org/gcc-6/changes.html[GCC's Website] GCC 6 has introduced some optimizations that could break non-conforming codebases, like QtWebEngine. + - As a workaround, you can disable the nullpointer check optimization by adding the -fno-delete-null-pointer-checks flag while compiling. + - On gentoo, you just need to add it into your make.conf, like this: + - - CFLAGS="... -fno-delete-null-pointer-checks" - CXXFLAGS="... -fno-delete-null-pointer-checks" -+ -And then re-emerging qtwebengine with: + - - emerge -1 qtwebengine - -Unable to view DRM content (Netflix, Spotify, etc.).:: - You will need to install `widevine` and set `qt.args` to point to it. - Qt 5.9 currently only supports widevine up to Chrome version 61. -+ -On Arch, simply install `qt5-webengine-widevine` from the AUR and run: -+ ----- -:set qt.args '["ppapi-widevine-path=/usr/lib/qt/plugins/ppapi/libwidevinecdmadapter.so"]' -:restart ----- -+ -For other distributions, download the chromium tarball and widevine-cdm zip from -https://aur.archlinux.org/packages/qt5-webengine-widevine/[the AUR page], -extract `libwidevinecdmadapter.so` and `libwidevinecdm.so` files, respectively, -and move them to the `ppapi` plugin directory in your Qt library directory (create it if it does not exist). -+ -Lastly, set your `qt.args` to point to that directory and restart qutebrowser: -+ ----- -:set qt.args '["ppapi-widevine-path=/usr/lib64/qt5/plugins/ppapi/libwidevinecdmadapter.so"]' -:restart ----- - -Unable to use `spawn` on MacOS.:: -When running qutebrowser from the prebuilt binary (`qutebrowser.app`) it *will -not* read any files that would alter your `$PATH` (e.g. `.profile`, `.bashrc`, -etc). This is not a bug, just that `.profile` is not propogated to GUI -applications in MacOS. -+ -See https://github.com/qutebrowser/qutebrowser/issues/4273[Issue #4273] for -details and potential workarounds. - -My issue is not listed.:: - If you experience any segfaults or crashes, you can report the issue in - https://github.com/qutebrowser/qutebrowser/issues[the issue tracker] or - using the `:report` command. - If you are reporting a segfault, make sure you read the - link:stacktrace{outfilesuffix}[guide] on how to report them with all needed - information. diff --git a/qutebrowser/api/cmdutils.py b/qutebrowser/api/cmdutils.py index f6a6f6da9..cd43079ad 100644 --- a/qutebrowser/api/cmdutils.py +++ b/qutebrowser/api/cmdutils.py @@ -17,9 +17,7 @@ # You should have received a copy of the GNU General Public License # along with qutebrowser. If not, see <http://www.gnu.org/licenses/>. -""" -qutebrowser has the concept of functions which are exposed to the user as -commands. +"""qutebrowser has the concept of functions, exposed to the user as commands. Creating a new command is straightforward:: @@ -43,7 +41,8 @@ The type can be overridden using Python's function annotations:: Possible values: -- A callable (``int``, ``float``, etc.): Gets called to validate/convert the value. +- A callable (``int``, ``float``, etc.): Gets called to validate/convert the + value. - A python enum type: All members of the enum are possible values. - A ``typing.Union`` of multiple types above: Any of these types are valid values, e.g., ``typing.Union[str, int]``. @@ -159,40 +158,43 @@ class argument: # noqa: N801,N806 pylint: disable=invalid-name """Decorator to customize an argument. - You can customize how an argument is handled using the ``@cmdutils.argument`` - decorator *after* ``@cmdutils.register``. This can, for example, be used to - customize the flag an argument should get:: + You can customize how an argument is handled using the + ``@cmdutils.argument`` decorator *after* ``@cmdutils.register``. This can, + for example, be used to customize the flag an argument should get:: @cmdutils.register(...) @cmdutils.argument('bar', flag='c') def foo(bar): ... - For a ``str`` argument, you can restrict the allowed strings using ``choices``:: + For a ``str`` argument, you can restrict the allowed strings using + ``choices``:: @cmdutils.register(...) @cmdutils.argument('bar', choices=['val1', 'val2']) def foo(bar: str): ... - For ``typing.Union`` types, the given ``choices`` are only checked if other types - (like ``int``) don't match. + For ``typing.Union`` types, the given ``choices`` are only checked if other + types (like ``int``) don't match. The following arguments are supported for ``@cmdutils.argument``: - ``flag``: Customize the short flag (``-x``) the argument will get. - ``value``: Tell qutebrowser to fill the argument with special values: - * ``value=cmdutils.Value.count``: The ``count`` given by the user to the command. + * ``value=cmdutils.Value.count``: The ``count`` given by the user to the + command. * ``value=cmdutils.Value.win_id``: The window ID of the current window. - * ``value=cmdutils.Value.cur_tab``: The tab object which is currently focused. + * ``value=cmdutils.Value.cur_tab``: The tab object which is currently + focused. - - ``completion``: A completion function to use when completing arguments for - the given command. + - ``completion``: A completion function to use when completing arguments + for the given command. - ``choices``: The allowed string choices for the argument. - The name of an argument will always be the parameter name, with any trailing - underscores stripped and underscores replaced by dashes. + The name of an argument will always be the parameter name, with any + trailing underscores stripped and underscores replaced by dashes. """ def __init__(self, argname: str, **kwargs: typing.Any) -> None: diff --git a/qutebrowser/keyinput/modeman.py b/qutebrowser/keyinput/modeman.py index c06700b6c..edb443eec 100644 --- a/qutebrowser/keyinput/modeman.py +++ b/qutebrowser/keyinput/modeman.py @@ -64,7 +64,7 @@ class NotInModeError(Exception): def init(win_id, parent): """Initialize the mode manager and the keyparsers for the given win_id.""" - KM = usertypes.KeyMode # noqa: N801,N806 pylint: disable=invalid-name + KM = usertypes.KeyMode # noqa: N806 modeman = ModeManager(win_id, parent) objreg.register('mode-manager', modeman, scope='window', window=win_id) keyparsers = { |