From 60e8abaa89ada2e026e77e07bc20c3353c4c5986 Mon Sep 17 00:00:00 2001 From: Florian Bruhin Date: Tue, 8 May 2018 14:57:56 +0200 Subject: Improve configuration docs (cherry picked from commit 20efaeff197f1cb0d8b5957e0cf61cb1759f321b) --- doc/help/configuring.asciidoc | 87 +++++++++++++++++++++++++++---------------- 1 file changed, 54 insertions(+), 33 deletions(-) diff --git a/doc/help/configuring.asciidoc b/doc/help/configuring.asciidoc index 3c686d15a..714996db2 100644 --- a/doc/help/configuring.asciidoc +++ b/doc/help/configuring.asciidoc @@ -3,44 +3,28 @@ Configuring qutebrowser IMPORTANT: qutebrowser's configuration system was completely rewritten in September 2017. This information is not applicable to older releases, and older -information elsewhere might be outdated. **If you had an old configuration -around and upgraded, this page will automatically open once**. To view it at a -later time, use the `:help` command. +information elsewhere might be outdated. -Migrating older configurations ------------------------------- - -qutebrowser does no automatic migration for the new configuration. However, -there's a special link:qute://configdiff/old[configdiff] page -(`qute://configdiff/old`) in qutebrowser, which will show you the changes you -did in your old configuration, compared to the old defaults. +qutebrowser's config files +-------------------------- -Other changes in default settings: +qutebrowser releases before v1.0.0 had a `qutebrowser.conf` and `keys.conf` +file. Those are not used anymore since that release - see +<> for information on how to +migrate to the new config. -- In v1.1.x and newer, `` and `` navigate through command history - if no text was entered yet. - With v1.0.x, they always navigate through command history instead of selecting - completion items. Use ``/`` to cycle through the completion - instead. - You can get back the old behavior by doing: -+ ----- -:bind -m command completion-item-focus prev -:bind -m command completion-item-focus next ----- -+ -or always navigate through command history with -+ ----- -:bind -m command command-history-prev -:bind -m command command-history-next ----- +When using `:set` and `:bind`, changes are saved to an `autoconfig.yml` file +automatically. If you don't want to have a config file which is curated by +hand, you can simply use those - see +<> for details. -- The default for `completion.web_history_max_items` is now set to `-1`, showing - an unlimited number of items in the completion for `:open` as the new - sqlite-based completion is much faster. If the `:open` completion is too slow - on your machine, set an appropriate limit again. +For more advanced configuration, you can write a `config.py` file - see +<>. As soon as a `config.py` +exists, the `autoconfig.yml` file **is not read anymore** by default. You need +to <> if you want settings done via +`:set`/`:bind` to still persist. +[[autoconfig]] Configuring qutebrowser via the user interface ---------------------------------------------- @@ -88,6 +72,7 @@ link:commands.html#config-clear[`:config-clear`] to reset the entire configurati and link:commands.html#config-cycle[`:config-cycle`] to cycle a setting between different values. +[[configpy]] Configuring qutebrowser via config.py ------------------------------------- @@ -239,6 +224,7 @@ config.bind(',v', 'spawn mpv {url}') To suppress loading of any default keybindings, you can set `c.bindings.default = {}`. +[[configpy-autoconfig]] Loading `autoconfig.yml` ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -429,3 +415,38 @@ from qutebrowser.config.config import ConfigContainer # noqa: F401 config = config # type: ConfigAPI # noqa: F821 pylint: disable=E0602,C0103 c = c # type: ConfigContainer # noqa: F821 pylint: disable=E0602,C0103 ---- + +[[migrating]] +Migrating older configurations +------------------------------ + +qutebrowser does no automatic migration for the new configuration. However, +there's a special link:qute://configdiff/old[configdiff] page +(`qute://configdiff/old`) in qutebrowser, which will show you the changes you +did in your old configuration, compared to the old defaults. + +Other changes in default settings: + +- In v1.1.x and newer, `` and `` navigate through command history + if no text was entered yet. + With v1.0.x, they always navigate through command history instead of selecting + completion items. Use ``/`` to cycle through the completion + instead. + You can get back the old behavior by doing: ++ +---- +:bind -m command completion-item-focus prev +:bind -m command completion-item-focus next +---- ++ +or always navigate through command history with ++ +---- +:bind -m command command-history-prev +:bind -m command command-history-next +---- + +- The default for `completion.web_history_max_items` is now set to `-1`, showing + an unlimited number of items in the completion for `:open` as the new + sqlite-based completion is much faster. If the `:open` completion is too slow + on your machine, set an appropriate limit again. -- cgit v1.2.3-54-g00ecf