From 413c7ec1ac35237d7d58b06f8937aab1c2fe51de Mon Sep 17 00:00:00 2001 From: Florian Bruhin Date: Fri, 15 Sep 2017 15:36:19 +0200 Subject: [PATCH] Add config type docstrings to settings.asciidoc --- doc/help/settings.asciidoc | 1033 ++++++++++++++++++++++------- qutebrowser/config/configtypes.py | 45 +- qutebrowser/utils/docutils.py | 2 +- scripts/dev/src2asciidoc.py | 42 +- 4 files changed, 863 insertions(+), 259 deletions(-) diff --git a/doc/help/settings.asciidoc b/doc/help/settings.asciidoc index 3bb3fd1b7..32e787439 100644 --- a/doc/help/settings.asciidoc +++ b/doc/help/settings.asciidoc @@ -2,7 +2,9 @@ // It is autogenerated by running: // $ python3 scripts/dev/src2asciidoc.py -= Settings += Setting reference + +== All settings [options="header",width="75%",cols="25%,75%"] |============== @@ -250,9 +252,11 @@ |============== [[aliases]] -== aliases +=== aliases Aliases for commands. +Type: <> + Default: - +pass:[q]+: +pass:[quit]+ @@ -260,9 +264,11 @@ Default: - +pass:[wq]+: +pass:[quit --save]+ [[auto_save.config]] -== auto_save.config +=== auto_save.config Save the config automatically on quit. +Type: <> + Valid values: * +true+ @@ -271,15 +277,19 @@ Valid values: Default: +pass:[true]+ [[auto_save.interval]] -== auto_save.interval +=== auto_save.interval How often (in milliseconds) to auto-save config/cookies/etc. +Type: <> + Default: +pass:[15000]+ [[auto_save.session]] -== auto_save.session +=== auto_save.session Always restore open sites when qutebrowser is reopened. +Type: <> + Valid values: * +true+ @@ -288,7 +298,7 @@ Valid values: Default: empty [[bindings.commands]] -== bindings.commands +=== bindings.commands Keybindings mapping keys to commands in different modes. This setting is a dictionary containing mode names and dictionaries mapping keys to commands: `{mode: {key: command}}` @@ -340,14 +350,18 @@ The following modes are available: * register: Entered when qutebrowser is waiting for a register name/key for commands like `:set-mark`. +Type: <> + Default: empty [[bindings.default]] -== bindings.default +=== bindings.default Default keybindings. If you want to add bindings, modify `bindings.commands` instead. The main purpose of this setting is that you can set it to an empty dictionary if you want to load no default keybindings at all. If you want to preserve default bindings (and get new bindings when there is an update), add new bindings to `bindings.commands` (or use `:bind`) and leave this setting alone. +Type: <> + Default: - +pass:[caret]+: @@ -600,11 +614,13 @@ Default: * +pass:[<Escape>]+: +pass:[leave-mode]+ [[bindings.key_mappings]] -== bindings.key_mappings +=== bindings.key_mappings This setting can be used to map keys to other keys. When the key used as dictionary-key is pressed, the binding for the key used as dictionary-value is invoked instead. This is useful for global remappings of keys, for example to map Ctrl-[ to Escape. +Type: <> + Default: - +pass:[<Ctrl-6>]+: +pass:[<Ctrl-^>]+ @@ -617,135 +633,179 @@ Default: - +pass:[<Shift-Return>]+: +pass:[<Return>]+ [[colors.completion.category.bg]] -== colors.completion.category.bg +=== colors.completion.category.bg Background color of the completion widget category headers. +Type: <> + Default: +pass:[qlineargradient(x1:0, y1:0, x2:0, y2:1, stop:0 #888888, stop:1 #505050)]+ [[colors.completion.category.border.bottom]] -== colors.completion.category.border.bottom +=== colors.completion.category.border.bottom Bottom border color of the completion widget category headers. +Type: <> + Default: +pass:[black]+ [[colors.completion.category.border.top]] -== colors.completion.category.border.top +=== colors.completion.category.border.top Top border color of the completion widget category headers. +Type: <> + Default: +pass:[black]+ [[colors.completion.category.fg]] -== colors.completion.category.fg +=== colors.completion.category.fg Foreground color of completion widget category headers. +Type: <> + Default: +pass:[white]+ [[colors.completion.even.bg]] -== colors.completion.even.bg +=== colors.completion.even.bg Background color of the completion widget for even rows. +Type: <> + Default: +pass:[#333333]+ [[colors.completion.fg]] -== colors.completion.fg +=== colors.completion.fg Text color of the completion widget. +Type: <> + Default: +pass:[white]+ [[colors.completion.item.selected.bg]] -== colors.completion.item.selected.bg +=== colors.completion.item.selected.bg Background color of the selected completion item. +Type: <> + Default: +pass:[#e8c000]+ [[colors.completion.item.selected.border.bottom]] -== colors.completion.item.selected.border.bottom +=== colors.completion.item.selected.border.bottom Bottom border color of the selected completion item. +Type: <> + Default: +pass:[#bbbb00]+ [[colors.completion.item.selected.border.top]] -== colors.completion.item.selected.border.top +=== colors.completion.item.selected.border.top Top border color of the completion widget category headers. +Type: <> + Default: +pass:[#bbbb00]+ [[colors.completion.item.selected.fg]] -== colors.completion.item.selected.fg +=== colors.completion.item.selected.fg Foreground color of the selected completion item. +Type: <> + Default: +pass:[black]+ [[colors.completion.match.fg]] -== colors.completion.match.fg +=== colors.completion.match.fg Foreground color of the matched text in the completion. +Type: <> + Default: +pass:[#ff4444]+ [[colors.completion.odd.bg]] -== colors.completion.odd.bg +=== colors.completion.odd.bg Background color of the completion widget for odd rows. +Type: <> + Default: +pass:[#444444]+ [[colors.completion.scrollbar.bg]] -== colors.completion.scrollbar.bg +=== colors.completion.scrollbar.bg Color of the scrollbar in completion view +Type: <> + Default: +pass:[#333333]+ [[colors.completion.scrollbar.fg]] -== colors.completion.scrollbar.fg +=== colors.completion.scrollbar.fg Color of the scrollbar handle in completion view. +Type: <> + Default: +pass:[white]+ [[colors.downloads.bar.bg]] -== colors.downloads.bar.bg +=== colors.downloads.bar.bg Background color for the download bar. +Type: <> + Default: +pass:[black]+ [[colors.downloads.error.bg]] -== colors.downloads.error.bg +=== colors.downloads.error.bg Background color for downloads with errors. +Type: <> + Default: +pass:[red]+ [[colors.downloads.error.fg]] -== colors.downloads.error.fg +=== colors.downloads.error.fg Foreground color for downloads with errors. +Type: <> + Default: +pass:[white]+ [[colors.downloads.start.bg]] -== colors.downloads.start.bg +=== colors.downloads.start.bg Color gradient start for download backgrounds. +Type: <> + Default: +pass:[#0000aa]+ [[colors.downloads.start.fg]] -== colors.downloads.start.fg +=== colors.downloads.start.fg Color gradient start for download text. +Type: <> + Default: +pass:[white]+ [[colors.downloads.stop.bg]] -== colors.downloads.stop.bg +=== colors.downloads.stop.bg Color gradient stop for download backgrounds. +Type: <> + Default: +pass:[#00aa00]+ [[colors.downloads.stop.fg]] -== colors.downloads.stop.fg +=== colors.downloads.stop.fg Color gradient end for download text. +Type: <> + Default: +pass:[white]+ [[colors.downloads.system.bg]] -== colors.downloads.system.bg +=== colors.downloads.system.bg Color gradient interpolation system for download backgrounds. +Type: <> + Valid values: * +rgb+: Interpolate in the RGB color system. @@ -756,9 +816,11 @@ Valid values: Default: +pass:[rgb]+ [[colors.downloads.system.fg]] -== colors.downloads.system.fg +=== colors.downloads.system.fg Color gradient interpolation system for download text. +Type: <> + Valid values: * +rgb+: Interpolate in the RGB color system. @@ -769,280 +831,372 @@ Valid values: Default: +pass:[rgb]+ [[colors.hints.bg]] -== colors.hints.bg +=== colors.hints.bg Background color for hints. Note that you can use a `rgba(...)` value for transparency. +Type: <> + Default: +pass:[qlineargradient(x1:0, y1:0, x2:0, y2:1, stop:0 rgba(255, 247, 133, 0.8), stop:1 rgba(255, 197, 66, 0.8))]+ [[colors.hints.fg]] -== colors.hints.fg +=== colors.hints.fg Font color for hints. +Type: <> + Default: +pass:[black]+ [[colors.hints.match.fg]] -== colors.hints.match.fg +=== colors.hints.match.fg Font color for the matched part of hints. +Type: <> + Default: +pass:[green]+ [[colors.keyhint.bg]] -== colors.keyhint.bg +=== colors.keyhint.bg Background color of the keyhint widget. +Type: <> + Default: +pass:[rgba(0, 0, 0, 80%)]+ [[colors.keyhint.fg]] -== colors.keyhint.fg +=== colors.keyhint.fg Text color for the keyhint widget. +Type: <> + Default: +pass:[#FFFFFF]+ [[colors.keyhint.suffix.fg]] -== colors.keyhint.suffix.fg +=== colors.keyhint.suffix.fg Highlight color for keys to complete the current keychain. +Type: <> + Default: +pass:[#FFFF00]+ [[colors.messages.error.bg]] -== colors.messages.error.bg +=== colors.messages.error.bg Background color of an error message. +Type: <> + Default: +pass:[red]+ [[colors.messages.error.border]] -== colors.messages.error.border +=== colors.messages.error.border Border color of an error message. +Type: <> + Default: +pass:[#bb0000]+ [[colors.messages.error.fg]] -== colors.messages.error.fg +=== colors.messages.error.fg Foreground color of an error message. +Type: <> + Default: +pass:[white]+ [[colors.messages.info.bg]] -== colors.messages.info.bg +=== colors.messages.info.bg Background color of an info message. +Type: <> + Default: +pass:[black]+ [[colors.messages.info.border]] -== colors.messages.info.border +=== colors.messages.info.border Border color of an info message. +Type: <> + Default: +pass:[#333333]+ [[colors.messages.info.fg]] -== colors.messages.info.fg +=== colors.messages.info.fg Foreground color an info message. +Type: <> + Default: +pass:[white]+ [[colors.messages.warning.bg]] -== colors.messages.warning.bg +=== colors.messages.warning.bg Background color of a warning message. +Type: <> + Default: +pass:[darkorange]+ [[colors.messages.warning.border]] -== colors.messages.warning.border +=== colors.messages.warning.border Border color of an error message. +Type: <> + Default: +pass:[#d47300]+ [[colors.messages.warning.fg]] -== colors.messages.warning.fg +=== colors.messages.warning.fg Foreground color a warning message. +Type: <> + Default: +pass:[white]+ [[colors.prompts.bg]] -== colors.prompts.bg +=== colors.prompts.bg Background color for prompts. +Type: <> + Default: +pass:[darkblue]+ [[colors.prompts.fg]] -== colors.prompts.fg +=== colors.prompts.fg Foreground color for prompts. +Type: <> + Default: +pass:[white]+ [[colors.prompts.selected.bg]] -== colors.prompts.selected.bg +=== colors.prompts.selected.bg Background color for the selected item in filename prompts. +Type: <> + Default: +pass:[#308cc6]+ [[colors.statusbar.caret.bg]] -== colors.statusbar.caret.bg +=== colors.statusbar.caret.bg Background color of the statusbar in caret mode. +Type: <> + Default: +pass:[purple]+ [[colors.statusbar.caret.fg]] -== colors.statusbar.caret.fg +=== colors.statusbar.caret.fg Foreground color of the statusbar in caret mode. +Type: <> + Default: +pass:[white]+ [[colors.statusbar.caret.selection.bg]] -== colors.statusbar.caret.selection.bg +=== colors.statusbar.caret.selection.bg Background color of the statusbar in caret mode with a selection. +Type: <> + Default: +pass:[#a12dff]+ [[colors.statusbar.caret.selection.fg]] -== colors.statusbar.caret.selection.fg +=== colors.statusbar.caret.selection.fg Foreground color of the statusbar in caret mode with a selection. +Type: <> + Default: +pass:[white]+ [[colors.statusbar.command.bg]] -== colors.statusbar.command.bg +=== colors.statusbar.command.bg Background color of the statusbar in command mode. +Type: <> + Default: +pass:[black]+ [[colors.statusbar.command.fg]] -== colors.statusbar.command.fg +=== colors.statusbar.command.fg Foreground color of the statusbar in command mode. +Type: <> + Default: +pass:[white]+ [[colors.statusbar.command.private.bg]] -== colors.statusbar.command.private.bg +=== colors.statusbar.command.private.bg Background color of the statusbar in private browsing + command mode. +Type: <> + Default: +pass:[grey]+ [[colors.statusbar.command.private.fg]] -== colors.statusbar.command.private.fg +=== colors.statusbar.command.private.fg Foreground color of the statusbar in private browsing + command mode. +Type: <> + Default: +pass:[white]+ [[colors.statusbar.insert.bg]] -== colors.statusbar.insert.bg +=== colors.statusbar.insert.bg Background color of the statusbar in insert mode. +Type: <> + Default: +pass:[darkgreen]+ [[colors.statusbar.insert.fg]] -== colors.statusbar.insert.fg +=== colors.statusbar.insert.fg Foreground color of the statusbar in insert mode. +Type: <> + Default: +pass:[white]+ [[colors.statusbar.normal.bg]] -== colors.statusbar.normal.bg +=== colors.statusbar.normal.bg Background color of the statusbar. +Type: <> + Default: +pass:[black]+ [[colors.statusbar.normal.fg]] -== colors.statusbar.normal.fg +=== colors.statusbar.normal.fg Foreground color of the statusbar. +Type: <> + Default: +pass:[white]+ [[colors.statusbar.private.bg]] -== colors.statusbar.private.bg +=== colors.statusbar.private.bg Background color of the statusbar in private browsing mode. +Type: <> + Default: +pass:[#666666]+ [[colors.statusbar.private.fg]] -== colors.statusbar.private.fg +=== colors.statusbar.private.fg Foreground color of the statusbar in private browsing mode. +Type: <> + Default: +pass:[white]+ [[colors.statusbar.progress.bg]] -== colors.statusbar.progress.bg +=== colors.statusbar.progress.bg Background color of the progress bar. +Type: <> + Default: +pass:[white]+ [[colors.statusbar.url.error.fg]] -== colors.statusbar.url.error.fg +=== colors.statusbar.url.error.fg Foreground color of the URL in the statusbar on error. +Type: <> + Default: +pass:[orange]+ [[colors.statusbar.url.fg]] -== colors.statusbar.url.fg +=== colors.statusbar.url.fg Default foreground color of the URL in the statusbar. +Type: <> + Default: +pass:[white]+ [[colors.statusbar.url.hover.fg]] -== colors.statusbar.url.hover.fg +=== colors.statusbar.url.hover.fg Foreground color of the URL in the statusbar for hovered links. +Type: <> + Default: +pass:[aqua]+ [[colors.statusbar.url.success.http.fg]] -== colors.statusbar.url.success.http.fg +=== colors.statusbar.url.success.http.fg Foreground color of the URL in the statusbar on successful load (http). +Type: <> + Default: +pass:[white]+ [[colors.statusbar.url.success.https.fg]] -== colors.statusbar.url.success.https.fg +=== colors.statusbar.url.success.https.fg Foreground color of the URL in the statusbar on successful load (https). +Type: <> + Default: +pass:[lime]+ [[colors.statusbar.url.warn.fg]] -== colors.statusbar.url.warn.fg +=== colors.statusbar.url.warn.fg Foreground color of the URL in the statusbar when there's a warning. +Type: <> + Default: +pass:[yellow]+ [[colors.tabs.bar.bg]] -== colors.tabs.bar.bg +=== colors.tabs.bar.bg Background color of the tab bar. +Type: <> + Default: +pass:[#555555]+ [[colors.tabs.even.bg]] -== colors.tabs.even.bg +=== colors.tabs.even.bg Background color of unselected even tabs. +Type: <> + Default: +pass:[darkgrey]+ [[colors.tabs.even.fg]] -== colors.tabs.even.fg +=== colors.tabs.even.fg Foreground color of unselected even tabs. +Type: <> + Default: +pass:[white]+ [[colors.tabs.indicator.error]] -== colors.tabs.indicator.error +=== colors.tabs.indicator.error Color for the tab indicator on errors. +Type: <> + Default: +pass:[#ff0000]+ [[colors.tabs.indicator.start]] -== colors.tabs.indicator.start +=== colors.tabs.indicator.start Color gradient start for the tab indicator. +Type: <> + Default: +pass:[#0000aa]+ [[colors.tabs.indicator.stop]] -== colors.tabs.indicator.stop +=== colors.tabs.indicator.stop Color gradient end for the tab indicator. +Type: <> + Default: +pass:[#00aa00]+ [[colors.tabs.indicator.system]] -== colors.tabs.indicator.system +=== colors.tabs.indicator.system Color gradient interpolation system for the tab indicator. +Type: <> + Valid values: * +rgb+: Interpolate in the RGB color system. @@ -1053,64 +1207,84 @@ Valid values: Default: +pass:[rgb]+ [[colors.tabs.odd.bg]] -== colors.tabs.odd.bg +=== colors.tabs.odd.bg Background color of unselected odd tabs. +Type: <> + Default: +pass:[grey]+ [[colors.tabs.odd.fg]] -== colors.tabs.odd.fg +=== colors.tabs.odd.fg Foreground color of unselected odd tabs. +Type: <> + Default: +pass:[white]+ [[colors.tabs.selected.even.bg]] -== colors.tabs.selected.even.bg +=== colors.tabs.selected.even.bg Background color of selected even tabs. +Type: <> + Default: +pass:[black]+ [[colors.tabs.selected.even.fg]] -== colors.tabs.selected.even.fg +=== colors.tabs.selected.even.fg Foreground color of selected even tabs. +Type: <> + Default: +pass:[white]+ [[colors.tabs.selected.odd.bg]] -== colors.tabs.selected.odd.bg +=== colors.tabs.selected.odd.bg Background color of selected odd tabs. +Type: <> + Default: +pass:[black]+ [[colors.tabs.selected.odd.fg]] -== colors.tabs.selected.odd.fg +=== colors.tabs.selected.odd.fg Foreground color of selected odd tabs. +Type: <> + Default: +pass:[white]+ [[colors.webpage.bg]] -== colors.webpage.bg +=== colors.webpage.bg Background color for webpages if unset (or empty to use the theme's color) +Type: <> + Default: +pass:[white]+ [[completion.cmd_history_max_items]] -== completion.cmd_history_max_items +=== completion.cmd_history_max_items How many commands to save in the command history. 0: no history / -1: unlimited +Type: <> + Default: +pass:[100]+ [[completion.height]] -== completion.height +=== completion.height The height of the completion, in px or as percentage of the window. +Type: <> + Default: +pass:[50%]+ [[completion.quick]] -== completion.quick +=== completion.quick Move on to the next part when there's only one possible completion left. +Type: <> + Valid values: * +true+ @@ -1119,21 +1293,27 @@ Valid values: Default: +pass:[true]+ [[completion.scrollbar.padding]] -== completion.scrollbar.padding +=== completion.scrollbar.padding Padding of scrollbar handle in the completion window (in px). +Type: <> + Default: +pass:[2]+ [[completion.scrollbar.width]] -== completion.scrollbar.width +=== completion.scrollbar.width Width of the scrollbar in the completion window (in px). +Type: <> + Default: +pass:[12]+ [[completion.show]] -== completion.show +=== completion.show When to show the autocompletion window. +Type: <> + Valid values: * +always+: Whenever a completion is available. @@ -1143,9 +1323,11 @@ Valid values: Default: +pass:[always]+ [[completion.shrink]] -== completion.shrink +=== completion.shrink Shrink the completion to be smaller than the configured size if there are no scrollbars. +Type: <> + Valid values: * +true+ @@ -1154,22 +1336,28 @@ Valid values: Default: empty [[completion.timestamp_format]] -== completion.timestamp_format +=== completion.timestamp_format How to format timestamps (e.g. for the history completion). +Type: <> + Default: +pass:[%Y-%m-%d]+ [[completion.web_history_max_items]] -== completion.web_history_max_items +=== completion.web_history_max_items How many URLs to show in the web history. 0: no history / -1: unlimited +Type: <> + Default: +pass:[-1]+ [[confirm_quit]] -== confirm_quit +=== confirm_quit Whether quitting the application requires a confirmation. +Type: <> + Valid values: * +always+: Always show a confirmation. @@ -1182,10 +1370,12 @@ Default: - +pass:[never]+ [[content.cache.appcache]] -== content.cache.appcache +=== content.cache.appcache Whether support for the HTML 5 web application cache feature is enabled. An application cache acts like an HTTP cache in some sense. For documents that use the application cache via JavaScript, the loader engine will first ask the application cache for the contents, before hitting the network. +Type: <> + Valid values: * +true+ @@ -1196,25 +1386,31 @@ Default: +pass:[true]+ This setting is only available with the QtWebKit backend. [[content.cache.maximum_pages]] -== content.cache.maximum_pages +=== content.cache.maximum_pages The maximum number of pages to hold in the global memory page cache. The Page Cache allows for a nicer user experience when navigating forth or back to pages in the forward/back history, by pausing and resuming up to _n_ pages. For more information about the feature, please refer to: http://webkit.org/blog/427/webkit-page-cache-i-the-basics/ +Type: <> + Default: empty This setting is only available with the QtWebKit backend. [[content.cache.size]] -== content.cache.size +=== content.cache.size Size of the HTTP network cache. Null to use the default value. +Type: <> + Default: empty [[content.cookies.accept]] -== content.cookies.accept +=== content.cookies.accept Control which cookies to accept. +Type: <> + Valid values: * +all+: Accept all cookies. @@ -1227,10 +1423,12 @@ Default: +pass:[no-3rdparty]+ This setting is only available with the QtWebKit backend. [[content.cookies.store]] -== content.cookies.store +=== content.cookies.store Store cookies. Note this option needs a restart with QtWebEngine on Qt < 5.9. +Type: <> + Valid values: * +true+ @@ -1239,17 +1437,21 @@ Valid values: Default: +pass:[true]+ [[content.default_encoding]] -== content.default_encoding +=== content.default_encoding Default encoding to use for websites. The encoding must be a string describing an encoding such as _utf-8_, _iso-8859-1_, etc. +Type: <> + Default: +pass:[iso-8859-1]+ [[content.developer_extras]] -== content.developer_extras +=== content.developer_extras Enable extra tools for Web developers. This needs to be enabled for `:inspector` to work and also adds an _Inspect_ entry to the context menu. For QtWebEngine, see `--enable-webengine-inspector` in `qutebrowser --help` instead. +Type: <> + Valid values: * +true+ @@ -1260,9 +1462,11 @@ Default: empty This setting is only available with the QtWebKit backend. [[content.dns_prefetch]] -== content.dns_prefetch +=== content.dns_prefetch Try to pre-fetch DNS entries to speed up browsing. +Type: <> + Valid values: * +true+ @@ -1273,10 +1477,12 @@ Default: +pass:[true]+ This setting is only available with the QtWebKit backend. [[content.frame_flattening]] -== content.frame_flattening +=== content.frame_flattening Expand each subframe to its contents. This will flatten all the frames to become one scrollable page. +Type: <> + Valid values: * +true+ @@ -1287,9 +1493,11 @@ Default: empty This setting is only available with the QtWebKit backend. [[content.geolocation]] -== content.geolocation +=== content.geolocation Allow websites to request geolocations. +Type: <> + Valid values: * +true+ @@ -1299,22 +1507,28 @@ Valid values: Default: +pass:[ask]+ [[content.headers.accept_language]] -== content.headers.accept_language +=== content.headers.accept_language Value to send in the `Accept-Language` header. +Type: <> + Default: +pass:[en-US,en]+ [[content.headers.custom]] -== content.headers.custom +=== content.headers.custom Set custom headers for qutebrowser HTTP requests. +Type: <> + Default: empty [[content.headers.do_not_track]] -== content.headers.do_not_track +=== content.headers.do_not_track Value to send in the `DNT` header. When this is set to true, qutebrowser asks websites to not track your identity. If set to null, the DNT header is not sent at all. +Type: <> + Valid values: * +true+ @@ -1323,10 +1537,12 @@ Valid values: Default: +pass:[true]+ [[content.headers.referer]] -== content.headers.referer +=== content.headers.referer Send the Referer header. The Referer header tells websites from which website you were coming from when visting them. +Type: <> + Valid values: * +always+: Always send the Referer. @@ -1338,15 +1554,19 @@ Default: +pass:[same-domain]+ This setting is only available with the QtWebKit backend. [[content.headers.user_agent]] -== content.headers.user_agent +=== content.headers.user_agent User agent to send. Unset to send the default. +Type: <> + Default: empty [[content.host_blocking.enabled]] -== content.host_blocking.enabled +=== content.host_blocking.enabled Whether host blocking is enabled. +Type: <> + Valid values: * +true+ @@ -1355,7 +1575,7 @@ Valid values: Default: +pass:[true]+ [[content.host_blocking.lists]] -== content.host_blocking.lists +=== content.host_blocking.lists List of URLs of lists which contain hosts to block. The file can be in one of the following formats: @@ -1366,6 +1586,8 @@ The file can be in one of the following formats: `hosts` (with any extension). +Type: <> + Default: - +pass:[https://www.malwaredomainlist.com/hostslist/hosts.txt]+ @@ -1375,19 +1597,23 @@ Default: - +pass:[https://pgl.yoyo.org/adservers/serverlist.php?hostformat=hosts&mimetype=plaintext]+ [[content.host_blocking.whitelist]] -== content.host_blocking.whitelist +=== content.host_blocking.whitelist List of domains that should always be loaded, despite being ad-blocked. Domains may contain * and ? wildcards and are otherwise required to exactly match the requested domain. Local domains are always exempt from hostblocking. +Type: <> + Default: - +pass:[piwik.org]+ [[content.hyperlink_auditing]] -== content.hyperlink_auditing +=== content.hyperlink_auditing Enable or disable hyperlink auditing (``). +Type: <> + Valid values: * +true+ @@ -1396,9 +1622,11 @@ Valid values: Default: empty [[content.images]] -== content.images +=== content.images Whether images are automatically loaded in web pages. +Type: <> + Valid values: * +true+ @@ -1407,9 +1635,11 @@ Valid values: Default: +pass:[true]+ [[content.javascript.alert]] -== content.javascript.alert +=== content.javascript.alert Show javascript alerts. +Type: <> + Valid values: * +true+ @@ -1418,10 +1648,12 @@ Valid values: Default: +pass:[true]+ [[content.javascript.can_access_clipboard]] -== content.javascript.can_access_clipboard +=== content.javascript.can_access_clipboard Whether JavaScript can read from or write to the clipboard. With QtWebEngine, writing the clipboard as response to a user interaction is always allowed. +Type: <> + Valid values: * +true+ @@ -1430,9 +1662,11 @@ Valid values: Default: empty [[content.javascript.can_close_tabs]] -== content.javascript.can_close_tabs +=== content.javascript.can_close_tabs Whether JavaScript can close tabs. +Type: <> + Valid values: * +true+ @@ -1443,9 +1677,11 @@ Default: empty This setting is only available with the QtWebKit backend. [[content.javascript.can_open_tabs_automatically]] -== content.javascript.can_open_tabs_automatically +=== content.javascript.can_open_tabs_automatically Whether JavaScript can open new tabs without user interaction. +Type: <> + Valid values: * +true+ @@ -1454,9 +1690,11 @@ Valid values: Default: empty [[content.javascript.enabled]] -== content.javascript.enabled +=== content.javascript.enabled Enables or disables JavaScript. +Type: <> + Valid values: * +true+ @@ -1465,10 +1703,12 @@ Valid values: Default: +pass:[true]+ [[content.javascript.log]] -== content.javascript.log +=== content.javascript.log Log levels to use for JavaScript console logging messages. On QtWebKit, the "unknown" setting is always used. +Type: <> + Default: - +pass:[error]+: +pass:[debug]+ @@ -1477,9 +1717,11 @@ Default: - +pass:[warning]+: +pass:[debug]+ [[content.javascript.modal_dialog]] -== content.javascript.modal_dialog +=== content.javascript.modal_dialog Use the standard JavaScript modal dialog for `alert()` and `confirm()` +Type: <> + Valid values: * +true+ @@ -1488,9 +1730,11 @@ Valid values: Default: empty [[content.javascript.prompt]] -== content.javascript.prompt +=== content.javascript.prompt Show javascript prompts. +Type: <> + Valid values: * +true+ @@ -1499,9 +1743,11 @@ Valid values: Default: +pass:[true]+ [[content.local_content_can_access_file_urls]] -== content.local_content_can_access_file_urls +=== content.local_content_can_access_file_urls Whether locally loaded documents are allowed to access other local urls. +Type: <> + Valid values: * +true+ @@ -1510,9 +1756,11 @@ Valid values: Default: +pass:[true]+ [[content.local_content_can_access_remote_urls]] -== content.local_content_can_access_remote_urls +=== content.local_content_can_access_remote_urls Whether locally loaded documents are allowed to access remote urls. +Type: <> + Valid values: * +true+ @@ -1521,9 +1769,11 @@ Valid values: Default: empty [[content.local_storage]] -== content.local_storage +=== content.local_storage Whether support for HTML 5 local storage and Web SQL is enabled. +Type: <> + Valid values: * +true+ @@ -1532,9 +1782,11 @@ Valid values: Default: +pass:[true]+ [[content.media_capture]] -== content.media_capture +=== content.media_capture Allow websites to record audio/video. +Type: <> + Valid values: * +true+ @@ -1546,16 +1798,20 @@ Default: +pass:[ask]+ This setting is only available with the QtWebEngine backend. [[content.netrc_file]] -== content.netrc_file +=== content.netrc_file Location of a netrc-file for HTTP authentication. If unset, `~/.netrc` is used. +Type: <> + Default: empty [[content.notifications]] -== content.notifications +=== content.notifications Allow websites to show notifications. +Type: <> + Valid values: * +true+ @@ -1565,10 +1821,12 @@ Valid values: Default: +pass:[ask]+ [[content.pdfjs]] -== content.pdfjs +=== content.pdfjs Enable pdf.js to view PDF files in the browser. Note that the files can still be downloaded by clicking the download button in the pdf.js viewer. +Type: <> + Valid values: * +true+ @@ -1579,9 +1837,11 @@ Default: empty This setting is only available with the QtWebKit backend. [[content.plugins]] -== content.plugins +=== content.plugins Enables or disables plugins in Web pages. +Type: <> + Valid values: * +true+ @@ -1590,9 +1850,11 @@ Valid values: Default: empty [[content.print_element_backgrounds]] -== content.print_element_backgrounds +=== content.print_element_backgrounds Whether the background color and images are also drawn when the page is printed. +Type: <> + Valid values: * +true+ @@ -1603,9 +1865,11 @@ Default: +pass:[true]+ On QtWebEngine, this setting requires Qt 5.8 or newer. [[content.private_browsing]] -== content.private_browsing +=== content.private_browsing Open new windows in private browsing mode which does not record visited pages. +Type: <> + Valid values: * +true+ @@ -1614,10 +1878,12 @@ Valid values: Default: empty [[content.proxy]] -== content.proxy +=== content.proxy The proxy to use. In addition to the listed values, you can use a `socks://...` or `http://...` URL. +Type: <> + Valid values: * +system+: Use the system wide proxy. @@ -1626,9 +1892,11 @@ Valid values: Default: +pass:[system]+ [[content.proxy_dns_requests]] -== content.proxy_dns_requests +=== content.proxy_dns_requests Send DNS requests over the configured proxy. +Type: <> + Valid values: * +true+ @@ -1639,9 +1907,11 @@ Default: +pass:[true]+ This setting is only available with the QtWebKit backend. [[content.ssl_strict]] -== content.ssl_strict +=== content.ssl_strict Validate SSL handshakes. +Type: <> + Valid values: * +true+ @@ -1651,15 +1921,19 @@ Valid values: Default: +pass:[ask]+ [[content.user_stylesheets]] -== content.user_stylesheets +=== content.user_stylesheets A list of user stylesheet filenames to use. +Type: <> + Default: empty [[content.webgl]] -== content.webgl +=== content.webgl Enables or disables WebGL. +Type: <> + Valid values: * +true+ @@ -1668,10 +1942,12 @@ Valid values: Default: +pass:[true]+ [[content.xss_auditing]] -== content.xss_auditing +=== content.xss_auditing Whether load requests should be monitored for cross-site scripting attempts. Suspicious scripts will be blocked and reported in the inspector\'s JavaScript console. Enabling this feature might have an impact on performance. +Type: <> + Valid values: * +true+ @@ -1680,17 +1956,21 @@ Valid values: Default: empty [[downloads.location.directory]] -== downloads.location.directory +=== downloads.location.directory The directory to save downloads to. If unset, a sensible os-specific default is used. +Type: <> + Default: empty [[downloads.location.prompt]] -== downloads.location.prompt +=== downloads.location.prompt Prompt the user for the download location. If set to false, `downloads.location.directory` will be used. +Type: <> + Valid values: * +true+ @@ -1699,9 +1979,11 @@ Valid values: Default: +pass:[true]+ [[downloads.location.remember]] -== downloads.location.remember +=== downloads.location.remember Remember the last used download directory. +Type: <> + Valid values: * +true+ @@ -1710,9 +1992,11 @@ Valid values: Default: +pass:[true]+ [[downloads.location.suggestion]] -== downloads.location.suggestion +=== downloads.location.suggestion What to display in the download filename input. +Type: <> + Valid values: * +path+: Show only the download path. @@ -1722,17 +2006,21 @@ Valid values: Default: +pass:[path]+ [[downloads.open_dispatcher]] -== downloads.open_dispatcher +=== downloads.open_dispatcher The default program used to open downloads. If null, the default internal handler is used. Any `{}` in the string will be expanded to the filename, else the filename will be appended. +Type: <> + Default: empty [[downloads.position]] -== downloads.position +=== downloads.position Where to show the downloaded files. +Type: <> + Valid values: * +top+ @@ -1741,17 +2029,21 @@ Valid values: Default: +pass:[top]+ [[downloads.remove_finished]] -== downloads.remove_finished +=== downloads.remove_finished Number of milliseconds to wait before removing finished downloads. If set to -1, downloads are never removed. +Type: <> + Default: +pass:[-1]+ [[editor.command]] -== editor.command +=== editor.command The editor (and arguments) to use for the `open-editor` command. `{}` gets replaced by the filename of the file to be edited. +Type: <> + Default: - +pass:[gvim]+ @@ -1759,154 +2051,204 @@ Default: - +pass:[{}]+ [[editor.encoding]] -== editor.encoding +=== editor.encoding Encoding to use for the editor. +Type: <> + Default: +pass:[utf-8]+ [[fonts.completion.category]] -== fonts.completion.category +=== fonts.completion.category Font used in the completion categories. +Type: <> + Default: +pass:[bold 8pt monospace]+ [[fonts.completion.entry]] -== fonts.completion.entry +=== fonts.completion.entry Font used in the completion widget. +Type: <> + Default: +pass:[8pt monospace]+ [[fonts.debug_console]] -== fonts.debug_console +=== fonts.debug_console Font used for the debugging console. +Type: <> + Default: +pass:[8pt monospace]+ [[fonts.downloads]] -== fonts.downloads +=== fonts.downloads Font used for the downloadbar. +Type: <> + Default: +pass:[8pt monospace]+ [[fonts.hints]] -== fonts.hints +=== fonts.hints Font used for the hints. +Type: <> + Default: +pass:[bold 13px monospace]+ [[fonts.keyhint]] -== fonts.keyhint +=== fonts.keyhint Font used in the keyhint widget. +Type: <> + Default: +pass:[8pt monospace]+ [[fonts.messages.error]] -== fonts.messages.error +=== fonts.messages.error Font used for error messages. +Type: <> + Default: +pass:[8pt monospace]+ [[fonts.messages.info]] -== fonts.messages.info +=== fonts.messages.info Font used for info messages. +Type: <> + Default: +pass:[8pt monospace]+ [[fonts.messages.warning]] -== fonts.messages.warning +=== fonts.messages.warning Font used for warning messages. +Type: <> + Default: +pass:[8pt monospace]+ [[fonts.monospace]] -== fonts.monospace +=== fonts.monospace Default monospace fonts. Whenever "monospace" is used in a font setting, it\'s replaced with the fonts listed here. +Type: <> + Default: +pass:["xos4 Terminus", Terminus, Monospace, "DejaVu Sans Mono", Monaco, "Bitstream Vera Sans Mono", "Andale Mono", "Courier New", Courier, "Liberation Mono", monospace, Fixed, Consolas, Terminal]+ [[fonts.prompts]] -== fonts.prompts +=== fonts.prompts Font used for prompts. +Type: <> + Default: +pass:[8pt sans-serif]+ [[fonts.statusbar]] -== fonts.statusbar +=== fonts.statusbar Font used in the statusbar. +Type: <> + Default: +pass:[8pt monospace]+ [[fonts.tabs]] -== fonts.tabs +=== fonts.tabs Font used in the tab bar. +Type: <> + Default: +pass:[8pt monospace]+ [[fonts.web.family.cursive]] -== fonts.web.family.cursive +=== fonts.web.family.cursive Font family for cursive fonts. +Type: <> + Default: empty [[fonts.web.family.fantasy]] -== fonts.web.family.fantasy +=== fonts.web.family.fantasy Font family for fantasy fonts. +Type: <> + Default: empty [[fonts.web.family.fixed]] -== fonts.web.family.fixed +=== fonts.web.family.fixed Font family for fixed fonts. +Type: <> + Default: empty [[fonts.web.family.sans_serif]] -== fonts.web.family.sans_serif +=== fonts.web.family.sans_serif Font family for sans-serif fonts. +Type: <> + Default: empty [[fonts.web.family.serif]] -== fonts.web.family.serif +=== fonts.web.family.serif Font family for serif fonts. +Type: <> + Default: empty [[fonts.web.family.standard]] -== fonts.web.family.standard +=== fonts.web.family.standard Font family for standard fonts. +Type: <> + Default: empty [[fonts.web.size.default]] -== fonts.web.size.default +=== fonts.web.size.default The default font size for regular text. +Type: <> + Default: +pass:[16]+ [[fonts.web.size.default_fixed]] -== fonts.web.size.default_fixed +=== fonts.web.size.default_fixed The default font size for fixed-pitch text. +Type: <> + Default: +pass:[13]+ [[fonts.web.size.minimum]] -== fonts.web.size.minimum +=== fonts.web.size.minimum The hard minimum font size. +Type: <> + Default: empty [[fonts.web.size.minimum_logical]] -== fonts.web.size.minimum_logical +=== fonts.web.size.minimum_logical The minimum logical font size that is applied when zooming out. +Type: <> + Default: +pass:[6]+ [[hints.auto_follow]] -== hints.auto_follow +=== hints.auto_follow Controls when a hint can be automatically followed without pressing Enter. +Type: <> + Valid values: * +always+: Auto-follow whenever there is only a single hint on a page. @@ -1917,33 +2259,43 @@ Valid values: Default: +pass:[unique-match]+ [[hints.auto_follow_timeout]] -== hints.auto_follow_timeout +=== hints.auto_follow_timeout A timeout (in milliseconds) to ignore normal-mode key bindings after a successful auto-follow. +Type: <> + Default: empty [[hints.border]] -== hints.border +=== hints.border CSS border value for hints. +Type: <> + Default: +pass:[1px solid #E3BE23]+ [[hints.chars]] -== hints.chars +=== hints.chars Chars used for hint strings. +Type: <> + Default: +pass:[asdfghjkl]+ [[hints.dictionary]] -== hints.dictionary +=== hints.dictionary The dictionary file to be used by the word hints. +Type: <> + Default: +pass:[/usr/share/dict/words]+ [[hints.find_implementation]] -== hints.find_implementation +=== hints.find_implementation Which implementation to use to find elements to hint. +Type: <> + Valid values: * +javascript+: Better but slower @@ -1954,9 +2306,11 @@ Default: +pass:[python]+ This setting is only available with the QtWebKit backend. [[hints.hide_unmatched_rapid_hints]] -== hints.hide_unmatched_rapid_hints +=== hints.hide_unmatched_rapid_hints Hide unmatched hints in rapid mode. +Type: <> + Valid values: * +true+ @@ -1965,15 +2319,19 @@ Valid values: Default: +pass:[true]+ [[hints.min_chars]] -== hints.min_chars +=== hints.min_chars Minimum number of chars used for hint strings. +Type: <> + Default: +pass:[1]+ [[hints.mode]] -== hints.mode +=== hints.mode Mode to use for hints. +Type: <> + Valid values: * +number+: Use numeric hints. (In this mode you can also type letters from the hinted element to filter and reduce the number of elements that are hinted.) @@ -1983,9 +2341,11 @@ Valid values: Default: +pass:[letter]+ [[hints.next_regexes]] -== hints.next_regexes +=== hints.next_regexes A comma-separated list of regexes to use for 'next' links. +Type: <> + Default: - +pass:[\bnext\b]+ @@ -1996,9 +2356,11 @@ Default: - +pass:[\bcontinue\b]+ [[hints.prev_regexes]] -== hints.prev_regexes +=== hints.prev_regexes A comma-separated list of regexes to use for 'prev' links. +Type: <> + Default: - +pass:[\bprev(ious)?\b]+ @@ -2008,10 +2370,12 @@ Default: - +pass:[\b(<<|«)\b]+ [[hints.scatter]] -== hints.scatter +=== hints.scatter Scatter hint key chains (like Vimium) or not (like dwb). Ignored for number hints. +Type: <> + Valid values: * +true+ @@ -2020,9 +2384,11 @@ Valid values: Default: +pass:[true]+ [[hints.uppercase]] -== hints.uppercase +=== hints.uppercase Make chars in hint strings uppercase. +Type: <> + Valid values: * +true+ @@ -2031,16 +2397,20 @@ Valid values: Default: empty [[history_gap_interval]] -== history_gap_interval +=== history_gap_interval The maximum time in minutes between two history items for them to be considered being from the same browsing session. Items with less time between them are grouped when being displayed in `:history`. Use -1 to disable separation. +Type: <> + Default: +pass:[30]+ [[ignore_case]] -== ignore_case +=== ignore_case Find text on a page case-insensitively. +Type: <> + Valid values: * +always+: Search case-insensitively @@ -2050,9 +2420,11 @@ Valid values: Default: +pass:[smart]+ [[input.forward_unbound_keys]] -== input.forward_unbound_keys +=== input.forward_unbound_keys Forward unbound keys to the webview in normal mode. +Type: <> + Valid values: * +all+: Forward all unbound keys. @@ -2062,9 +2434,11 @@ Valid values: Default: +pass:[auto]+ [[input.insert_mode.auto_leave]] -== input.insert_mode.auto_leave +=== input.insert_mode.auto_leave Leave insert mode if a non-editable element is clicked. +Type: <> + Valid values: * +true+ @@ -2073,9 +2447,11 @@ Valid values: Default: +pass:[true]+ [[input.insert_mode.auto_load]] -== input.insert_mode.auto_load +=== input.insert_mode.auto_load Automatically enter insert mode if an editable element is focused after loading the page. +Type: <> + Valid values: * +true+ @@ -2084,9 +2460,11 @@ Valid values: Default: empty [[input.insert_mode.plugins]] -== input.insert_mode.plugins +=== input.insert_mode.plugins Switch to insert mode when clicking flash and other plugins. +Type: <> + Valid values: * +true+ @@ -2095,9 +2473,11 @@ Valid values: Default: empty [[input.links_included_in_focus_chain]] -== input.links_included_in_focus_chain +=== input.links_included_in_focus_chain Include hyperlinks in the keyboard focus chain when tabbing. +Type: <> + Valid values: * +true+ @@ -2106,17 +2486,21 @@ Valid values: Default: +pass:[true]+ [[input.partial_timeout]] -== input.partial_timeout +=== input.partial_timeout Timeout (in milliseconds) for partially typed key bindings. If the current input forms only partial matches, the keystring will be cleared after this time. +Type: <> + Default: +pass:[5000]+ [[input.rocker_gestures]] -== input.rocker_gestures +=== input.rocker_gestures Enable Opera-like mouse rocker gestures. This disables the context menu. +Type: <> + Valid values: * +true+ @@ -2125,10 +2509,12 @@ Valid values: Default: empty [[input.spatial_navigation]] -== input.spatial_navigation +=== input.spatial_navigation Enable Spatial Navigation. Spatial navigation consists in the ability to navigate between focusable elements in a Web page, such as hyperlinks and form controls, by using Left, Right, Up and Down arrow keys. For example, if a user presses the Right key, heuristics determine whether there is an element he might be trying to reach towards the right and which element he probably wants. +Type: <> + Valid values: * +true+ @@ -2137,29 +2523,37 @@ Valid values: Default: empty [[keyhint.blacklist]] -== keyhint.blacklist +=== keyhint.blacklist Keychains that shouldn\'t be shown in the keyhint dialog. Globs are supported, so `;*` will blacklist all keychains starting with `;`. Use `*` to disable keyhints. +Type: <> + Default: empty [[keyhint.delay]] -== keyhint.delay +=== keyhint.delay Time from pressing a key to seeing the keyhint dialog (ms). +Type: <> + Default: +pass:[500]+ [[messages.timeout]] -== messages.timeout +=== messages.timeout Time (in ms) to show messages in the statusbar for. Set to 0 to never clear messages. +Type: <> + Default: +pass:[2000]+ [[messages.unfocused]] -== messages.unfocused +=== messages.unfocused Show messages in unfocused windows. +Type: <> + Valid values: * +true+ @@ -2168,11 +2562,13 @@ Valid values: Default: empty [[new_instance_open_target]] -== new_instance_open_target +=== new_instance_open_target How to open links in an existing instance if a new one is launched. This happens when e.g. opening a link from a terminal. See `new_instance_open_target_window` to customize in which window the link is opened in. +Type: <> + Valid values: * +tab+: Open a new tab in the existing window and activate the window. @@ -2184,10 +2580,12 @@ Valid values: Default: +pass:[tab]+ [[new_instance_open_target_window]] -== new_instance_open_target_window +=== new_instance_open_target_window Which window to choose when opening links as new tabs. When `new_instance_open_target` is not set to `window`, this is ignored. +Type: <> + Valid values: * +first-opened+: Open new tabs in the first (oldest) opened window. @@ -2198,9 +2596,11 @@ Valid values: Default: +pass:[last-focused]+ [[prompt.filebrowser]] -== prompt.filebrowser +=== prompt.filebrowser Show a filebrowser in upload/download prompts. +Type: <> + Valid values: * +true+ @@ -2209,15 +2609,19 @@ Valid values: Default: +pass:[true]+ [[prompt.radius]] -== prompt.radius +=== prompt.radius The rounding radius for the edges of prompts. +Type: <> + Default: +pass:[8]+ [[scrolling.bar]] -== scrolling.bar +=== scrolling.bar Show a scrollbar. +Type: <> + Valid values: * +true+ @@ -2226,10 +2630,12 @@ Valid values: Default: empty [[scrolling.smooth]] -== scrolling.smooth +=== scrolling.smooth Enable smooth scrolling for web pages. Note smooth scrolling does not work with the `:scroll-px` command. +Type: <> + Valid values: * +true+ @@ -2238,16 +2644,20 @@ Valid values: Default: empty [[session_default_name]] -== session_default_name +=== session_default_name The name of the session to save by default. If this is set to null, the session which was last loaded is saved. +Type: <> + Default: empty [[statusbar.hide]] -== statusbar.hide +=== statusbar.hide Hide the statusbar unless a message is shown. +Type: <> + Valid values: * +true+ @@ -2256,9 +2666,11 @@ Valid values: Default: empty [[statusbar.padding]] -== statusbar.padding +=== statusbar.padding Padding for the statusbar. +Type: <> + Default: - +pass:[bottom]+: +pass:[1]+ @@ -2267,9 +2679,11 @@ Default: - +pass:[top]+: +pass:[1]+ [[statusbar.position]] -== statusbar.position +=== statusbar.position The position of the status bar. +Type: <> + Valid values: * +top+ @@ -2278,9 +2692,11 @@ Valid values: Default: +pass:[bottom]+ [[tabs.background]] -== tabs.background +=== tabs.background Open new tabs (middleclick/ctrl+click) in the background. +Type: <> + Valid values: * +true+ @@ -2289,9 +2705,11 @@ Valid values: Default: empty [[tabs.close_mouse_button]] -== tabs.close_mouse_button +=== tabs.close_mouse_button On which mouse button to close tabs. +Type: <> + Valid values: * +right+: Close tabs on right-click. @@ -2301,16 +2719,20 @@ Valid values: Default: +pass:[middle]+ [[tabs.favicons.scale]] -== tabs.favicons.scale +=== tabs.favicons.scale Scaling for favicons in the tab bar. The tab size is unchanged, so big favicons also require extra `tabs.padding`. +Type: <> + Default: +pass:[1.0]+ [[tabs.favicons.show]] -== tabs.favicons.show +=== tabs.favicons.show Show favicons in the tab bar. +Type: <> + Valid values: * +true+ @@ -2319,9 +2741,11 @@ Valid values: Default: +pass:[true]+ [[tabs.indicator_padding]] -== tabs.indicator_padding +=== tabs.indicator_padding Padding for tab indicators +Type: <> + Default: - +pass:[bottom]+: +pass:[2]+ @@ -2330,9 +2754,11 @@ Default: - +pass:[top]+: +pass:[2]+ [[tabs.last_close]] -== tabs.last_close +=== tabs.last_close Behavior when the last tab is closed. +Type: <> + Valid values: * +ignore+: Don't do anything. @@ -2344,9 +2770,11 @@ Valid values: Default: +pass:[ignore]+ [[tabs.mousewheel_switching]] -== tabs.mousewheel_switching +=== tabs.mousewheel_switching Switch between tabs using the mouse wheel. +Type: <> + Valid values: * +true+ @@ -2355,9 +2783,11 @@ Valid values: Default: +pass:[true]+ [[tabs.new_position.related]] -== tabs.new_position.related +=== tabs.new_position.related How new tabs opened from another tab are positioned. +Type: <> + Valid values: * +prev+: Before the current tab. @@ -2368,9 +2798,11 @@ Valid values: Default: +pass:[next]+ [[tabs.new_position.unrelated]] -== tabs.new_position.unrelated +=== tabs.new_position.unrelated How new tabs which aren't opened from another tab are positioned. +Type: <> + Valid values: * +prev+: Before the current tab. @@ -2381,9 +2813,11 @@ Valid values: Default: +pass:[last]+ [[tabs.padding]] -== tabs.padding +=== tabs.padding Padding around text for tabs +Type: <> + Default: - +pass:[bottom]+: empty @@ -2392,9 +2826,11 @@ Default: - +pass:[top]+: empty [[tabs.position]] -== tabs.position +=== tabs.position The position of the tab bar. +Type: <> + Valid values: * +top+ @@ -2405,9 +2841,11 @@ Valid values: Default: +pass:[top]+ [[tabs.select_on_remove]] -== tabs.select_on_remove +=== tabs.select_on_remove Which tab to select when the focused tab is removed. +Type: <> + Valid values: * +prev+: Select the tab which came before the closed one (left in horizontal, above in vertical). @@ -2417,9 +2855,11 @@ Valid values: Default: +pass:[next]+ [[tabs.show]] -== tabs.show +=== tabs.show When to show the tab bar. +Type: <> + Valid values: * +always+: Always show the tab bar. @@ -2430,15 +2870,19 @@ Valid values: Default: +pass:[always]+ [[tabs.show_switching_delay]] -== tabs.show_switching_delay +=== tabs.show_switching_delay Time to show the tab bar before hiding it when tabs.show is set to 'switching'. +Type: <> + Default: +pass:[800]+ [[tabs.tabs_are_windows]] -== tabs.tabs_are_windows +=== tabs.tabs_are_windows Open a new window for every tab. +Type: <> + Valid values: * +true+ @@ -2447,9 +2891,11 @@ Valid values: Default: empty [[tabs.title.alignment]] -== tabs.title.alignment +=== tabs.title.alignment Alignment of the text inside of tabs. +Type: <> + Valid values: * +left+ @@ -2459,7 +2905,7 @@ Valid values: Default: +pass:[left]+ [[tabs.title.format]] -== tabs.title.format +=== tabs.title.format The format to use for the tab title. The following placeholders are defined: @@ -2475,36 +2921,48 @@ The following placeholders are defined: * `{private}` : Indicates when private mode is enabled. +Type: <> + Default: +pass:[{index}: {title}]+ [[tabs.title.format_pinned]] -== tabs.title.format_pinned +=== tabs.title.format_pinned The format to use for the tab title for pinned tabs. The same placeholders like for `tabs.title.format` are defined. +Type: <> + Default: +pass:[{index}]+ [[tabs.width.bar]] -== tabs.width.bar +=== tabs.width.bar The width of the tab bar if it's vertical, in px or as percentage of the window. +Type: <> + Default: +pass:[20%]+ [[tabs.width.indicator]] -== tabs.width.indicator +=== tabs.width.indicator Width of the progress indicator (0 to disable). +Type: <> + Default: +pass:[3]+ [[tabs.width.pinned]] -== tabs.width.pinned +=== tabs.width.pinned The width for pinned tabs with a horizontal tabbar, in px. +Type: <> + Default: +pass:[43]+ [[tabs.wrap]] -== tabs.wrap +=== tabs.wrap Whether to wrap when changing tabs. +Type: <> + Valid values: * +true+ @@ -2513,9 +2971,11 @@ Valid values: Default: +pass:[true]+ [[url.auto_search]] -== url.auto_search +=== url.auto_search Whether to start a search when something else than a URL is entered. +Type: <> + Valid values: * +naive+: Use simple/naive check. @@ -2525,16 +2985,20 @@ Valid values: Default: +pass:[naive]+ [[url.default_page]] -== url.default_page +=== url.default_page The page to open if :open -t/-b/-w is used without URL. Use `about:blank` for a blank page. +Type: <> + Default: +pass:[https://start.duckduckgo.com/]+ [[url.incdec_segments]] -== url.incdec_segments +=== url.incdec_segments The URL segments where `:navigate increment/decrement` will search for a number. +Type: <> + Valid values: * +host+ @@ -2548,26 +3012,32 @@ Default: - +pass:[query]+ [[url.searchengines]] -== url.searchengines +=== url.searchengines Definitions of search engines which can be used via the address bar. The searchengine named `DEFAULT` is used when `url.auto_search` is turned on and something else than a URL was entered to be opened. Other search engines can be used by prepending the search engine name to the search term, e.g. `:open google qutebrowser`. The string `{}` will be replaced by the search term, use `{{` and `}}` for literal `{`/`}` signs. +Type: <> + Default: - +pass:[DEFAULT]+: +pass:[https://duckduckgo.com/?q={}]+ [[url.start_pages]] -== url.start_pages +=== url.start_pages The page(s) to open at the start. +Type: <> + Default: - +pass:[https://start.duckduckgo.com]+ [[url.yank_ignored_parameters]] -== url.yank_ignored_parameters +=== url.yank_ignored_parameters The URL parameters to strip with `:yank url`. +Type: <> + Default: - +pass:[ref]+ @@ -2578,9 +3048,11 @@ Default: - +pass:[utm_content]+ [[window.hide_wayland_decoration]] -== window.hide_wayland_decoration +=== window.hide_wayland_decoration Hide the window decoration when using wayland (requires restart) +Type: <> + Valid values: * +true+ @@ -2589,7 +3061,7 @@ Valid values: Default: empty [[window.title_format]] -== window.title_format +=== window.title_format The format to use for the window title. The following placeholders are defined: @@ -2604,18 +3076,24 @@ The following placeholders are defined: * `{private}` : Indicates when private mode is enabled. +Type: <> + Default: +pass:[{perc}{title}{title_sep}qutebrowser]+ [[zoom.default]] -== zoom.default +=== zoom.default The default zoom level. +Type: <> + Default: +pass:[100%]+ [[zoom.levels]] -== zoom.levels +=== zoom.levels The available zoom levels. +Type: <> + Default: - +pass:[25%]+ @@ -2636,15 +3114,19 @@ Default: - +pass:[500%]+ [[zoom.mouse_divider]] -== zoom.mouse_divider +=== zoom.mouse_divider How much to divide the mouse wheel movements to translate them into zoom increments. +Type: <> + Default: +pass:[512]+ [[zoom.text_only]] -== zoom.text_only +=== zoom.text_only Whether the zoom factor on a frame applies only to the text or to all content. +Type: <> + Valid values: * +true+ @@ -2653,3 +3135,72 @@ Valid values: Default: empty This setting is only available with the QtWebKit backend. + +== Setting types +[[types]] +[options="header",width="75%",cols="25%,75%"] +|============== +|Type|Description +|Bool|A boolean setting, either `true` or `false`. + +When setting from a string, `1`, `yes`, `on` and `true` count as true, while `0`, `no`, `off` and `false` count as false (case-insensitive). +|BoolAsk|Like `Bool`, but `ask` is allowed as additional value. +|ColorSystem|The color system to use for color interpolation. +|Command|Base class for a command value with arguments. +|ConfirmQuit|Whether to display a confirmation when the window is closed. +|Dict|A dictionary of values. + +When setting from a string, pass a json-like dict, e.g. `{"key", "value"}`. +|Directory|A directory on the local filesystem. +|Encoding|Setting for a python encoding. +|File|A file on the local filesystem. +|FlagList|A list of flags. + +Lists with duplicate flags are invalid. Each item is checked against the valid values of the setting. +|Float|Base class for a float setting. +|Font|A font family, with optional style/weight/size. + +* Style: `normal`/`italic`/`oblique` * Weight: `normal`, `bold`, `100`..`900` * Size: _number_ `px`/`pt` +|FontFamily|A Qt font family. +|FormatString|A string with placeholders. +|FuzzyUrl|A URL which gets interpreted as search if needed. +|Int|Base class for an integer setting. +|Key|A name of a key. +|List|A list of values. + +When setting from a string, pass a json-like list, e.g. `["one", "two"]`. +|NewTabPosition|How new tabs are positioned. +|Padding|Setting for paddings around elements. +|Perc|A percentage. +|PercOrInt|Percentage or integer. +|Position|The position of the tab bar. +|Proxy|A proxy URL, or `system`/`none`. +|QssColor|A color value supporting gradients. + +A value can be in one of the following formats: * `#RGB`/`#RRGGBB`/`#RRRGGGBBB`/`#RRRRGGGGBBBB` * An SVG color name as specified in http://www.w3.org/TR/SVG/types.html#ColorKeywords[the W3C specification]. * transparent (no color) * `rgb(r, g, b)` / `rgba(r, g, b, a)` (values 0-255 or percentages) * `hsv(h, s, v)` / `hsva(h, s, v, a)` (values 0-255, hue 0-359) * A gradient as explained in http://doc.qt.io/qt-5/stylesheet-reference.html#list-of-property-types[the Qt documentation] under ``Gradient'' +|QtColor|A color value. + +A value can be in one of the following formats: * `#RGB`/`#RRGGBB`/`#RRRGGGBBB`/`#RRRRGGGGBBBB` * An SVG color name as specified in http://www.w3.org/TR/SVG/types.html#ColorKeywords[the W3C specification]. * transparent (no color) +|QtFont|A font family, with optional style/weight/size. + +* Style: `normal`/`italic`/`oblique` * Weight: `normal`, `bold`, `100`..`900` * Size: _number_ `px`/`pt` +|Regex|A regular expression. + +When setting from `config.py`, both a string or a `re.compile(...)` object are valid. +|SearchEngineUrl|A search engine URL. +|SelectOnRemove|Which tab to select when the focused tab is removed. +|SessionName|The name of a session. +|ShellCommand|A shell command as a list. + +See the documentation for `List`. +|String|A string value. + +See the setting's valid values for more information on allowed values. +|TextAlignment|Alignment of text. +|TimestampTemplate|An strftime-like template for timestamps. + +See https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior for reference. +|UniqueCharString|A string which may not contain duplicate chars. +|Url|A URL as a string. +|VerticalPosition|The position of the download bar. +|============== diff --git a/qutebrowser/config/configtypes.py b/qutebrowser/config/configtypes.py index 115051466..32da0c704 100644 --- a/qutebrowser/config/configtypes.py +++ b/qutebrowser/config/configtypes.py @@ -42,8 +42,6 @@ Config types can do different conversations: This also validates whether the object is actually correct (type/value). """ -# FIXME:conf show the type docstrings in the documentation - import re import html import codecs @@ -311,7 +309,9 @@ class MappingType(BaseType): class String(BaseType): - """Base class for a string setting (case-insensitive). + """A string value. + + See the setting's valid values for more information on allowed values. Attributes: minlen: Minimum length (inclusive). @@ -404,7 +404,10 @@ class UniqueCharString(String): class List(BaseType): - """Base class for a (string-)list setting.""" + """A list of values. + + When setting from a string, pass a json-like list, e.g. `["one", "two"]`. + """ _show_valtype = True @@ -474,10 +477,10 @@ class List(BaseType): class FlagList(List): - """Base class for a list setting that contains one or more flags. + """A list of flags. - Lists with duplicate flags are invalid and each item is checked against - self.valid_values (if not empty). + Lists with duplicate flags are invalid. Each item is checked against + the valid values of the setting. """ combinable_values = None @@ -521,7 +524,11 @@ class FlagList(List): class Bool(BaseType): - """Base class for a boolean setting.""" + """A boolean setting, either `true` or `false`. + + When setting from a string, `1`, `yes`, `on` and `true` count as true, while + `0`, `no`, `off` and `false` count as false (case-insensitive). + """ def __init__(self, none_ok=False): super().__init__(none_ok) @@ -552,7 +559,7 @@ class Bool(BaseType): class BoolAsk(Bool): - """A yes/no/ask question.""" + """Like `Bool`, but `ask` is allowed as additional value.""" def __init__(self, none_ok=False): super().__init__(none_ok) @@ -950,6 +957,8 @@ class QtFont(Font): """A Font which gets converted to a QFont.""" + __doc__ = Font.__doc__ # for src2asciidoc.py + def to_py(self, value): self._basic_py_validation(value, str) if not value: @@ -1011,6 +1020,9 @@ class Regex(BaseType): """A regular expression. + When setting from `config.py`, both a string or a `re.compile(...)` object + are valid. + Attributes: flags: The flags to be used when a string is passed. _regex_type: The Python type of a regex object. @@ -1077,7 +1089,10 @@ class Regex(BaseType): class Dict(BaseType): - """A dictionary of values.""" + """A dictionary of values. + + When setting from a string, pass a json-like dict, e.g. `{"key", "value"}`. + """ def __init__(self, keytype, valtype, *, fixed_keys=None, required_keys=None, none_ok=False): @@ -1214,7 +1229,7 @@ class Directory(BaseType): class FormatString(BaseType): - """A string with '{foo}'-placeholders.""" + """A string with placeholders.""" def __init__(self, fields, none_ok=False): super().__init__(none_ok) @@ -1240,6 +1255,8 @@ class ShellCommand(List): """A shell command as a list. + See the documentation for `List`. + Attributes: placeholder: If there should be a placeholder. """ @@ -1261,7 +1278,7 @@ class ShellCommand(List): class Proxy(BaseType): - """A proxy URL or special value.""" + """A proxy URL, or `system`/`none`.""" def __init__(self, none_ok=False): super().__init__(none_ok) @@ -1332,7 +1349,7 @@ class SearchEngineUrl(BaseType): class FuzzyUrl(BaseType): - """A single URL.""" + """A URL which gets interpreted as search if needed.""" def to_py(self, value): from qutebrowser.utils import urlutils @@ -1426,7 +1443,7 @@ class VerticalPosition(String): class Url(BaseType): - """A URL.""" + """A URL as a string.""" def to_py(self, value): self._basic_py_validation(value, str) diff --git a/qutebrowser/utils/docutils.py b/qutebrowser/utils/docutils.py index 1a3b4312d..1991068f9 100644 --- a/qutebrowser/utils/docutils.py +++ b/qutebrowser/utils/docutils.py @@ -142,7 +142,7 @@ class DocstringParser: """Parse the long description in the docstring.""" if line.startswith('Args:'): self._state = self.State.arg_start - elif line.strip() == '//': + elif line.strip() == '//' or line.startswith('Attributes:'): self._state = self.State.desc_hidden elif line.strip(): self._long_desc_parts.append(line.strip()) diff --git a/scripts/dev/src2asciidoc.py b/scripts/dev/src2asciidoc.py index 8804b5c0d..9bfd346b2 100755 --- a/scripts/dev/src2asciidoc.py +++ b/scripts/dev/src2asciidoc.py @@ -37,7 +37,7 @@ import qutebrowser.app from scripts import asciidoc2html, utils from qutebrowser import qutebrowser, commands from qutebrowser.commands import cmdutils, argparser -from qutebrowser.config import configdata +from qutebrowser.config import configdata, configtypes from qutebrowser.utils import docutils, usertypes FILE_HEADER = """ @@ -153,6 +153,36 @@ def _get_setting_quickref(): return '\n'.join(out) +def _get_configtypes(): + """Get configtypes classes to document.""" + predicate = lambda e: (inspect.isclass(e) and + e not in [configtypes.BaseType, + configtypes.MappingType, + # pylint: disable=protected-access + configtypes._Numeric] and + issubclass(e, configtypes.BaseType)) + yield from inspect.getmembers(configtypes, predicate) + + +def _get_setting_types_quickref(): + """Generate the setting types quick reference.""" + out = [] + out.append('[[types]]') + out.append('[options="header",width="75%",cols="25%,75%"]') + out.append('|==============') + out.append('|Type|Description') + + for name, typ in _get_configtypes(): + parser = docutils.DocstringParser(typ) + desc = parser.short_desc + if parser.long_desc: + desc += '\n\n' + parser.long_desc + out.append('|{}|{}'.format(name, desc)) + + out.append('|==============') + return '\n'.join(out) + + def _get_command_doc(name, cmd): """Generate the documentation for a command.""" output = ['[[{}]]'.format(name)] @@ -383,9 +413,12 @@ def _generate_setting_option(f, opt): """Generate documentation for a single section.""" f.write("\n") f.write('[[{}]]'.format(opt.name) + "\n") - f.write("== {}".format(opt.name) + "\n") + f.write("=== {}".format(opt.name) + "\n") f.write(opt.description + "\n") f.write("\n") + f.write('Type: <>\n'.format( + typ=opt.typ.__class__.__name__)) + f.write("\n") valid_values = opt.typ.get_valid_values() if valid_values is not None: @@ -408,10 +441,13 @@ def generate_settings(filename): configdata.init() with _open_file(filename) as f: f.write(FILE_HEADER) - f.write("= Settings\n") + f.write("= Setting reference\n\n") + f.write("== All settings\n") f.write(_get_setting_quickref() + "\n") for opt in sorted(configdata.DATA.values()): _generate_setting_option(f, opt) + f.write("\n== Setting types\n") + f.write(_get_setting_types_quickref() + "\n") def _format_block(filename, what, data):