From 0c01d9b61a0405f03dfdca88c6d1385f7528dcd4 Mon Sep 17 00:00:00 2001
From: Marcel Schilling <marcel.schilling@mdc-berlin.de>
Date: Mon, 30 Oct 2017 13:34:58 +0100
Subject: [PATCH 01/21] fixed typos in configdata descriptions

---
 qutebrowser/config/configdata.yml | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/qutebrowser/config/configdata.yml b/qutebrowser/config/configdata.yml
index 0f2a439d3..2b66c3512 100644
--- a/qutebrowser/config/configdata.yml
+++ b/qutebrowser/config/configdata.yml
@@ -106,7 +106,7 @@ backend:
     only supports the fork.
 
     QtWebEngine is Qt's official successor to QtWebKit. It's slightly more
-    resource hungry that QtWebKit and has a couple of missing features in
+    resource hungry than QtWebKit and has a couple of missing features in
     qutebrowser, but is generally the preferred choice.
 
     This setting requires a restart.
@@ -658,7 +658,7 @@ completion.scrollbar.padding:
   type:
     name: Int
     minval: 0
-  desc: Padding of scrollbar handle in the completion window (in px).
+  desc: Padding of the scrollbar handle in the completion window (in px).
 
 completion.timestamp_format:
   type:
@@ -1371,11 +1371,11 @@ url.searchengines:
   desc: >-
     Definitions of search engines which can be used via the address bar.
 
-    Maps a searchengine name (such as `DEFAULT`, or `ddg`) to a URL with a `{}`
+    Maps a search engine name (such as `DEFAULT`, or `ddg`) to a URL with a `{}`
     placeholder. The placeholder will be replaced by the search term, use `{{`
     and `}}` for literal `{`/`}` signs.
 
-    The searchengine named `DEFAULT` is used when `url.auto_search` is turned on
+    The search engine 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`.
@@ -1549,12 +1549,12 @@ colors.completion.match.fg:
 colors.completion.scrollbar.fg:
   default: white
   type: QssColor
-  desc: Color of the scrollbar handle in completion view.
+  desc: Color of the scrollbar handle in the completion view.
 
 colors.completion.scrollbar.bg:
   default: '#333333'
   type: QssColor
-  desc: Color of the scrollbar in completion view
+  desc: Color of the scrollbar in the completion view
 
 colors.downloads.bar.bg:
   default: black
@@ -1653,7 +1653,7 @@ colors.messages.error.border:
 colors.messages.warning.fg:
   default: white
   type: QssColor
-  desc: Foreground color a warning message.
+  desc: Foreground color of a warning message.
 
 colors.messages.warning.bg:
   default: darkorange
@@ -1668,7 +1668,7 @@ colors.messages.warning.border:
 colors.messages.info.fg:
   default: white
   type: QssColor
-  desc: Foreground color an info message.
+  desc: Foreground color of an info message.
 
 colors.messages.info.bg:
   default: black

From a55d12bf708a9178e81f42948229eeee2da5735e Mon Sep 17 00:00:00 2001
From: Marcel Schilling <marcel.schilling@mdc-berlin.de>
Date: Mon, 30 Oct 2017 13:42:03 +0100
Subject: [PATCH 02/21] add missing periods (.) to configdata descriptions

 * includes `valid_value` descriptions in addition to `desc` fields
---
 qutebrowser/config/configdata.yml | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/qutebrowser/config/configdata.yml b/qutebrowser/config/configdata.yml
index 2b66c3512..e85b4428f 100644
--- a/qutebrowser/config/configdata.yml
+++ b/qutebrowser/config/configdata.yml
@@ -37,9 +37,9 @@ ignore_case:
   type:
     name: String
     valid_values:
-      - always: Search case-insensitively
-      - never: Search case-sensitively
-      - smart: Search case-sensitively if there are capital chars
+      - always: Search case-insensitively.
+      - never: Search case-sensitively.
+      - smart: Search case-sensitively if there are capital chars.
   default: smart
   desc: Find text on a page case-insensitively.
 
@@ -92,8 +92,8 @@ backend:
   type:
     name: String
     valid_values:
-      - webengine: Use QtWebEngine (based on Chromium)
-      - webkit: Use QtWebKit (based on WebKit, similar to Safari)
+      - webengine: Use QtWebEngine (based on Chromium).
+      - webkit: Use QtWebKit (based on WebKit, similar to Safari).
   default: webengine
   desc: >-
     The backend to use to display websites.
@@ -483,7 +483,7 @@ content.javascript.log:
 content.javascript.modal_dialog:
   type: Bool
   default: false
-  desc: Use the standard JavaScript modal dialog for `alert()` and `confirm()`
+  desc: Use the standard JavaScript modal dialog for `alert()` and `confirm()`.
 
 content.javascript.prompt:
   default: true
@@ -1182,7 +1182,7 @@ tabs.indicator_padding:
     left: 0
     right: 4
   type: Padding
-  desc: Padding for tab indicators
+  desc: Padding for tab indicators.
 
 tabs.last_close:
   default: ignore
@@ -1218,7 +1218,7 @@ tabs.padding:
     left: 5
     right: 5
   type: Padding
-  desc: Padding around text for tabs
+  desc: Padding around text for tabs.
 
 tabs.position:
   default: top
@@ -1406,7 +1406,7 @@ url.yank_ignored_parameters:
 window.hide_wayland_decoration:
   type: Bool
   default: false
-  desc: Hide the window decoration when using wayland (requires restart)
+  desc: Hide the window decoration when using wayland (requires restart).
 
 window.title_format:
   type:
@@ -1554,7 +1554,7 @@ colors.completion.scrollbar.fg:
 colors.completion.scrollbar.bg:
   default: '#333333'
   type: QssColor
-  desc: Color of the scrollbar in the completion view
+  desc: Color of the scrollbar in the completion view.
 
 colors.downloads.bar.bg:
   default: black
@@ -1885,7 +1885,7 @@ colors.webpage.bg:
   type:
     name: QtColor
     none_ok: true
-  desc: "Background color for webpages if unset (or empty to use the theme's color)"
+  desc: "Background color for webpages if unset (or empty to use the theme's color)."
 
 ## fonts
 

From 31e7d8dd3f86a1f2972a7ab2d4537a551d201bfc Mon Sep 17 00:00:00 2001
From: Marcel Schilling <marcel.schilling@mdc-berlin.de>
Date: Mon, 30 Oct 2017 13:50:57 +0100
Subject: [PATCH 03/21] fix capitalization in configdata descriptions

 * url -> URL
 * os -> OS
 * Page Cache -> page cache
 * Spatial Navigation -> spatial navigation
---
 qutebrowser/config/configdata.yml | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/qutebrowser/config/configdata.yml b/qutebrowser/config/configdata.yml
index e85b4428f..168fcfb26 100644
--- a/qutebrowser/config/configdata.yml
+++ b/qutebrowser/config/configdata.yml
@@ -196,7 +196,7 @@ content.cache.maximum_pages:
   desc: >-
     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
+    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/
@@ -493,12 +493,12 @@ content.javascript.prompt:
 content.local_content_can_access_remote_urls:
   default: false
   type: Bool
-  desc: Whether locally loaded documents are allowed to access remote urls.
+  desc: Whether locally loaded documents are allowed to access remote URLs.
 
 content.local_content_can_access_file_urls:
   default: true
   type: Bool
-  desc: Whether locally loaded documents are allowed to access other local urls.
+  desc: Whether locally loaded documents are allowed to access other local URLs.
 
 content.local_storage:
   default: true
@@ -707,7 +707,7 @@ downloads.location.directory:
   desc: >-
     The directory to save downloads to.
 
-    If unset, a sensible os-specific default is used.
+    If unset, a sensible OS-specific default is used.
 
 downloads.location.prompt:
   default: true
@@ -967,7 +967,7 @@ input.spatial_navigation:
   default: false
   type: Bool
   desc: >-
-    Enable 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
@@ -1287,7 +1287,7 @@ tabs.title.format:
     * `{host}`: The host of the current web page.
     * `{backend}`: Either ''webkit'' or ''webengine''
     * `{private}` : Indicates when private mode is enabled.
-    * `{current_url}` : The url of the current web page.
+    * `{current_url}` : The URL of the current web page.
 
 tabs.title.format_pinned:
   default: '{index}'
@@ -1436,7 +1436,7 @@ window.title_format:
     * `{host}`: The host of the current web page.
     * `{backend}`: Either ''webkit'' or ''webengine''
     * `{private}` : Indicates when private mode is enabled.
-    * `{current_url}` : The url of the current web page.
+    * `{current_url}` : The URL of the current web page.
 
 ## zoom
 

From 99ad1547bc27bd99ef588fed9f900f19f00f41a1 Mon Sep 17 00:00:00 2001
From: Marcel Schilling <marcel.schilling@mdc-berlin.de>
Date: Mon, 30 Oct 2017 14:08:51 +0100
Subject: [PATCH 04/21] break long lines in configdata YAML file

 * max. 79 chars (as per PEP8)
 * two long lines remain (as I didn't know how to safely break them):

>    389      - "http://malwaredomains.lehigh.edu/files/justdomains.zip"
> -> 390      - "https://pgl.yoyo.org/adservers/serverlist.php?hostformat=hosts&mimetype=plaintext"
>    391    type:
> --
>   2222        Sh: open qute://history
> ->2223        xx: config-cycle statusbar.hide ;; config-cycle tabs.show always switching
>   2224        xt: config-cycle tabs.show always switching
---
 qutebrowser/config/configdata.yml | 190 ++++++++++++++++--------------
 1 file changed, 102 insertions(+), 88 deletions(-)

diff --git a/qutebrowser/config/configdata.yml b/qutebrowser/config/configdata.yml
index 168fcfb26..f68cfb921 100644
--- a/qutebrowser/config/configdata.yml
+++ b/qutebrowser/config/configdata.yml
@@ -30,8 +30,8 @@ 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.
+    Items with less time between them are grouped when being displayed in
+    `:history`. Use -1 to disable separation.
 
 ignore_case:
   type:
@@ -50,8 +50,8 @@ new_instance_open_target:
       - tab: Open a new tab in the existing window and activate the window.
       - tab-bg: Open a new background tab in the existing window and activate
           the window.
-      - tab-silent: Open a new tab in the existing window without activating the
-          window.
+      - tab-silent: Open a new tab in the existing window without activating
+          the window.
       - tab-bg-silent: Open a new background tab in the existing window without
           activating the window.
       - window: Open in a new window.
@@ -196,10 +196,12 @@ content.cache.maximum_pages:
   desc: >-
     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.
+    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/
+    For more information about the feature, please refer to:
+    http://webkit.org/blog/427/webkit-page-cache-i-the-basics/
 
 content.cache.appcache:
   default: true
@@ -208,9 +210,9 @@ content.cache.appcache:
   desc: >-
     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.
+    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.
 
 content.cookies.accept:
   default: no-3rdparty
@@ -220,8 +222,8 @@ content.cookies.accept:
     valid_values:
       - all: "Accept all cookies."
       - no-3rdparty: "Accept cookies from the same origin only."
-      - no-unknown-3rdparty: "Accept cookies from the same origin only, unless a
-          cookie is already set for the domain."
+      - no-unknown-3rdparty: "Accept cookies from the same origin only, unless
+          a cookie is already set for the domain."
       - never: "Don't accept cookies at all."
   desc: Control which cookies to accept.
 
@@ -249,8 +251,8 @@ content.developer_extras:
   desc: >-
     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
+    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.
 
 content.dns_prefetch:
@@ -312,8 +314,8 @@ content.headers.referer:
       - always: "Always send the Referer."
       - never: "Never send the Referer. This is not recommended, as some sites
           may break."
-      - same-domain: "Only send the Referer for the same domain. This will still
-          protect your privacy, but shouldn't break any sites."
+      - same-domain: "Only send the Referer for the same domain. This will
+          still protect your privacy, but shouldn't break any sites."
   backend: QtWebKit
   desc: >-
     Send the Referer header.
@@ -327,7 +329,8 @@ content.headers.user_agent:
     name: String
     none_ok: true
     completions:
-      # To update the following list of user agents, run the script 'ua_fetch.py'
+      # To update the following list of user agents, run the script
+      # 'ua_fetch.py'
       # Vim-protip: Place your cursor below this comment and run
       # :r!python scripts/dev/ua_fetch.py
       - - "Mozilla/5.0 (Windows NT 6.3; WOW64; rv:53.0) Gecko/20100101
@@ -336,8 +339,8 @@ content.headers.user_agent:
       - - "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:53.0) Gecko/20100101
           Firefox/53.0"
         - Firefox 53.0 Linux
-      - - "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.12; rv:53.0) Gecko/20100101
-          Firefox/53.0"
+      - - "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.12; rv:53.0)
+          Gecko/20100101 Firefox/53.0"
         - Firefox 53.0 MacOSX
 
       - - "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_5) AppleWebKit/603.2.4
@@ -364,10 +367,11 @@ content.headers.user_agent:
         - wget 1.16.1
       - - "curl/7.40.0"
         - curl 7.40.0
-      - - "Mozilla/5.0 (Linux; U; Android 7.1.2) AppleWebKit/534.30 (KHTML, like
-          Gecko) Version/4.0 Mobile Safari/534.30"
+      - - "Mozilla/5.0 (Linux; U; Android 7.1.2) AppleWebKit/534.30 (KHTML,
+          like Gecko) Version/4.0 Mobile Safari/534.30"
         - Mobile Generic Android
-      - - "Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; rv:11.0) like Gecko"
+      - - "Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; rv:11.0) like
+          Gecko"
         - IE 11.0 for Desktop Win7 64-bit
 
   desc: User agent to send. Unset to send the default.
@@ -395,8 +399,8 @@ content.host_blocking.lists:
 
     - An `/etc/hosts`-like file
     - One host per line
-    - A zip-file of any of the above, with either only one file, or a file named
-      `hosts` (with any extension).
+    - A zip-file of any of the above, with either only one file, or a file
+      named `hosts` (with any extension).
 
 content.host_blocking.whitelist:
   default:
@@ -408,8 +412,8 @@ content.host_blocking.whitelist:
   desc: >-
     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.
+    Domains may contain * and ? wildcards and are otherwise required to exactly
+    match the requested domain.
 
     Local domains are always exempt from hostblocking.
 
@@ -434,8 +438,8 @@ content.javascript.can_access_clipboard:
   desc: >-
     Whether JavaScript can read from or write to the clipboard.
 
-    With QtWebEngine, writing the clipboard as response to a user interaction is
-    always allowed.
+    With QtWebEngine, writing the clipboard as response to a user interaction
+    is always allowed.
 
 content.javascript.can_close_tabs:
   default: false
@@ -475,8 +479,8 @@ content.javascript.log:
     Log levels to use for JavaScript console logging messages.
 
     When a JavaScript message with the level given in the dictionary key is
-    logged, the corresponding dictionary value selects the qutebrowser logger to
-    use.
+    logged, the corresponding dictionary value selects the qutebrowser logger
+    to use.
 
     On QtWebKit, the "unknown" setting is always used.
 
@@ -498,7 +502,8 @@ content.local_content_can_access_remote_urls:
 content.local_content_can_access_file_urls:
   default: true
   type: Bool
-  desc: Whether locally loaded documents are allowed to access other local URLs.
+  desc: Whether locally loaded documents are allowed to access other local
+    URLs.
 
 content.local_storage:
   default: true
@@ -534,8 +539,8 @@ content.pdfjs:
   desc: >-
     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.
+    Note that the files can still be downloaded by clicking the download button
+    in the pdf.js viewer.
 
 content.plugins:
   default: false
@@ -564,8 +569,8 @@ content.proxy:
   desc: >-
     The proxy to use.
 
-    In addition to the listed values, you can use a `socks://...` or `http://...`
-    URL.
+    In addition to the listed values, you can use a `socks://...` or
+    `http://...` URL.
 
 content.proxy_dns_requests:
   default: true
@@ -595,7 +600,8 @@ content.xss_auditing:
   type: Bool
   default: false
   desc: >-
-    Whether load requests should be monitored for cross-site scripting attempts.
+    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
@@ -797,10 +803,11 @@ hints.auto_follow:
     name: String
     valid_values:
       - always: "Auto-follow whenever there is only a single hint on a page."
-      - unique-match: "Auto-follow whenever there is a unique non-empty match in
-          either the hint string (word mode) or filter (number mode)."
-      - full-match: "Follow the hint when the user typed the whole hint (letter,
-          word or number mode) or the element's text (only in number mode)."
+      - unique-match: "Auto-follow whenever there is a unique non-empty match
+          in either the hint string (word mode) or filter (number mode)."
+      - full-match: "Follow the hint when the user typed the whole hint
+          (letter, word or number mode) or the element's text (only in number
+          mode)."
       - never: "The user will always need to press Enter to follow a hint."
   desc: Controls when a hint can be automatically followed without pressing
     Enter.
@@ -952,8 +959,8 @@ input.partial_timeout:
   desc: >-
     Timeout (in milliseconds) for partially typed key bindings.
 
-    If the current input forms only partial matches, the keystring will be cleared
-    after this time.
+    If the current input forms only partial matches, the keystring will be
+    cleared after this time.
 
 input.rocker_gestures:
   default: false
@@ -969,11 +976,11 @@ input.spatial_navigation:
   desc: >-
     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.
+    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.
 
 ## keyhint
 
@@ -987,8 +994,8 @@ keyhint.blacklist:
   desc: >-
     Keychains that shouldn't be shown in the keyhint dialog.
 
-    Globs are supported, so `;*` will blacklist all keychains starting with `;`.
-    Use `*` to disable keyhints.
+    Globs are supported, so `;*` will blacklist all keychains starting with
+    `;`. Use `*` to disable keyhints.
 
 keyhint.radius:
   type:
@@ -1168,7 +1175,8 @@ tabs.favicons.scale:
   desc: >-
     Scaling for favicons in the tab bar.
 
-    The tab size is unchanged, so big favicons also require extra `tabs.padding`.
+    The tab size is unchanged, so big favicons also require extra
+    `tabs.padding`.
 
 tabs.favicons.show:
   default: true
@@ -1305,8 +1313,8 @@ tabs.title.format_pinned:
       - private
       - current_url
     none_ok: true
-  desc: The format to use for the tab title for pinned tabs. The same placeholders
-    like for `tabs.title.format` are defined.
+  desc: The format to use for the tab title for pinned tabs. The same
+    placeholders like for `tabs.title.format` are defined.
 
 tabs.width.bar:
   default: 20%
@@ -1315,7 +1323,8 @@ tabs.width.bar:
     minperc: 0
     maxperc: 100
     minint: 1
-  desc: "The width of the tab bar if it's vertical, in px or as percentage of the window."
+  desc: "The width of the tab bar if it's vertical, in px or as percentage of
+    the window."
 
 tabs.width.indicator:
   default: 3
@@ -1357,8 +1366,8 @@ url.incdec_segments:
     name: FlagList
     valid_values: [host, path, query, anchor]
   default: [path, query]
-  desc: The URL segments where `:navigate increment/decrement` will search for a
-    number.
+  desc: The URL segments where `:navigate increment/decrement` will search for
+    a number.
 
 url.searchengines:
   default:
@@ -1371,14 +1380,14 @@ url.searchengines:
   desc: >-
     Definitions of search engines which can be used via the address bar.
 
-    Maps a search engine name (such as `DEFAULT`, or `ddg`) to a URL with a `{}`
-    placeholder. The placeholder will be replaced by the search term, use `{{`
-    and `}}` for literal `{`/`}` signs.
+    Maps a search engine name (such as `DEFAULT`, or `ddg`) to a URL with a
+    `{}` placeholder. The placeholder will be replaced by the search term, use
+    `{{` and `}}` for literal `{`/`}` signs.
 
-    The search engine 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 search engine 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`.
 
 url.start_pages:
   type:
@@ -1475,7 +1484,8 @@ zoom.mouse_divider:
   type:
     name: Int
     minval: 0
-  desc: How much to divide the mouse wheel movements to translate them into zoom increments.
+  desc: How much to divide the mouse wheel movements to translate them into
+    zoom increments.
 
 zoom.text_only:
   type: Bool
@@ -1507,7 +1517,8 @@ colors.completion.category.fg:
   desc: Foreground color of completion widget category headers.
 
 colors.completion.category.bg:
-  default: 'qlineargradient(x1:0, y1:0, x2:0, y2:1, stop:0 #888888, stop:1 #505050)'
+  default: 'qlineargradient(x1:0, y1:0, x2:0, y2:1, stop:0 #888888,
+    stop:1 #505050)'
   type: QssColor
   desc: Background color of the completion widget category headers.
 
@@ -1607,8 +1618,8 @@ colors.hints.fg:
   desc: Font color for hints.
 
 colors.hints.bg:
-  default: 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))
+  default: 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))
   type: QssColor
   desc: >-
     Background color for hints.
@@ -1808,7 +1819,8 @@ colors.statusbar.url.success.http.fg:
 colors.statusbar.url.success.https.fg:
   default: lime
   type: QssColor
-  desc: Foreground color of the URL in the statusbar on successful load (https).
+  desc: Foreground color of the URL in the statusbar on successful load
+    (https).
 
 colors.statusbar.url.warn.fg:
   default: yellow
@@ -1885,14 +1897,15 @@ colors.webpage.bg:
   type:
     name: QtColor
     none_ok: true
-  desc: "Background color for webpages if unset (or empty to use the theme's color)."
+  desc: "Background color for webpages if unset (or empty to use the theme's
+    color)."
 
 ## fonts
 
 fonts.monospace:
-  default: '"xos4 Terminus", Terminus, Monospace, "DejaVu Sans Mono", Monaco, "Bitstream
-    Vera Sans Mono", "Andale Mono", "Courier New", Courier, "Liberation Mono", monospace,
-    Fixed, Consolas, Terminal'
+  default: '"xos4 Terminus", Terminus, Monospace, "DejaVu Sans Mono", Monaco,
+    "Bitstream Vera Sans Mono", "Andale Mono", "Courier New", Courier,
+    "Liberation Mono", monospace, Fixed, Consolas, Terminal'
   type: Font
   desc: >-
     Default monospace fonts.
@@ -2062,8 +2075,8 @@ bindings.key_mappings:
   desc: >-
     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.
+    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.
@@ -2336,12 +2349,12 @@ 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.
+    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), use `config.bind()` in `config.py` or the `:bind` command, and
-    leave this setting alone.
+    If you want to preserve default bindings (and get new bindings when there
+    is an update), use `config.bind()` in `config.py` or the `:bind` command,
+    and leave this setting alone.
 
 bindings.commands:
   default: {}
@@ -2374,7 +2387,8 @@ bindings.commands:
     setting instead.
 
     For special keys (can't be part of a keychain), enclose them in `<`...`>`.
-    For modifiers, you can use either `-` or `+` as delimiters, and these names:
+    For modifiers, you can use either `-` or `+` as delimiters, and these
+    names:
 
       * Control: `Control`, `Ctrl`
 
@@ -2404,17 +2418,17 @@ bindings.commands:
 
     * insert: Entered when an input field is focused on a website, or by
       pressing `i` in normal mode. Passes through almost all keypresses to the
-      website, but has some bindings like `<Ctrl-e>` to open an external editor.
-      Note that single keys can't be bound in this mode.
+      website, but has some bindings like `<Ctrl-e>` to open an external
+      editor. Note that single keys can't be bound in this mode.
 
     * hint: Entered when `f` is pressed to select links with the keyboard. Note
       that single keys can't be bound in this mode.
 
     * passthrough: Similar to insert mode, but passes through all keypresses
-      except `<Escape>` to leave the mode. It might be useful to bind `<Escape>`
-      to some other key in this mode if you want to be able to send an Escape
-      key to the website as well. Note that single keys can't be bound in this
-      mode.
+      except `<Escape>` to leave the mode. It might be useful to bind
+      `<Escape>` to some other key in this mode if you want to be able to send
+      an Escape key to the website as well. Note that single keys can't be
+      bound in this mode.
 
     * command: Entered when pressing the `:` key in order to enter a command.
       Note that single keys can't be bound in this mode.
@@ -2422,9 +2436,9 @@ bindings.commands:
     * prompt: Entered when there's a prompt to display, like for download
       locations or when invoked from JavaScript.
       +
-      You can bind normal keys in this mode, but they will be only active when a
-      yes/no-prompt is asked. For other prompt modes, you can only bind special
-      keys.
+      You can bind normal keys in this mode, but they will be only active when
+      a yes/no-prompt is asked. For other prompt modes, you can only bind
+      special keys.
 
     * caret: Entered when pressing the `v` mode, used to select text using the
       keyboard.

From 7672fb52419550d147c6a0588e684cd7592fff6c Mon Sep 17 00:00:00 2001
From: Marcel Schilling <marcel.schilling@mdc-berlin.de>
Date: Mon, 30 Oct 2017 15:29:40 +0100
Subject: [PATCH 05/21] avoid abbreviations in configdata description

 * chars -> characters
 * px -> pixels
 * ms -> milliseconds
 * regexes -> regular expressions

 * includes `valid_value` descriptions in addition to `desc` fields

ms_fix
---
 qutebrowser/config/configdata.yml | 31 ++++++++++++++++---------------
 1 file changed, 16 insertions(+), 15 deletions(-)

diff --git a/qutebrowser/config/configdata.yml b/qutebrowser/config/configdata.yml
index f68cfb921..a9629fdb7 100644
--- a/qutebrowser/config/configdata.yml
+++ b/qutebrowser/config/configdata.yml
@@ -39,7 +39,7 @@ ignore_case:
     valid_values:
       - always: Search case-insensitively.
       - never: Search case-sensitively.
-      - smart: Search case-sensitively if there are capital chars.
+      - smart: Search case-sensitively if there are capital characters.
   default: smart
   desc: Find text on a page case-insensitively.
 
@@ -628,7 +628,7 @@ completion.height:
     maxperc: 100
     minint: 1
   default: 50%
-  desc: The height of the completion, in px or as percentage of the window.
+  desc: The height of the completion, in pixels or as percentage of the window.
 
 completion.quick:
   default: true
@@ -657,14 +657,14 @@ completion.scrollbar.width:
   type:
     name: Int
     minval: 0
-  desc: Width of the scrollbar in the completion window (in px).
+  desc: Width of the scrollbar in the completion window (in pixels).
 
 completion.scrollbar.padding:
   default: 2
   type:
     name: Int
     minval: 0
-  desc: Padding of the scrollbar handle in the completion window (in px).
+  desc: Padding of the scrollbar handle in the completion window (in pixels).
 
 completion.timestamp_format:
   type:
@@ -689,7 +689,8 @@ completion.delay:
   type:
     name: Int
     minval: 0
-  desc: Delay in ms before updating completions after typing a character.
+  desc: Delay in milliseconds before updating completions after typing a
+    character.
 
 completion.min_chars:
   default: 1
@@ -832,7 +833,7 @@ hints.chars:
       - ['asdfghjkl', "Home row"]
       - ['aoeuidnths', "Home row (Dvorak)"]
       - ['abcdefghijklmnopqrstuvwxyz', "All letters"]
-  desc: Chars used for hint strings.
+  desc: Characters used for hint strings.
 
 hints.dictionary:
   default: /usr/share/dict/words
@@ -861,7 +862,7 @@ hints.min_chars:
   type:
     name: Int
     minval: 1
-  desc: Minimum number of chars used for hint strings.
+  desc: Minimum number of characters used for hint strings.
 
 hints.mode:
   default: letter
@@ -871,7 +872,7 @@ hints.mode:
       - 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.)
-      - letter: Use the chars in the `hints.chars` setting.
+      - letter: Use the characters in the `hints.chars` setting.
       - word: Use hints words based on the html elements and the extra words.
   desc: Mode to use for hints.
 
@@ -888,7 +889,7 @@ hints.next_regexes:
     valtype:
       name: Regex
       flags: IGNORECASE
-  desc: A comma-separated list of regexes to use for 'next' links.
+  desc: A comma-separated list of regular expressions to use for 'next' links.
 
 hints.prev_regexes:
   default:
@@ -902,7 +903,7 @@ hints.prev_regexes:
     valtype:
       name: Regex
       flags: IGNORECASE
-  desc: A comma-separated list of regexes to use for 'prev' links.
+  desc: A comma-separated list of regular expressions to use for 'prev' links.
 
 hints.scatter:
   default: true
@@ -915,7 +916,7 @@ hints.scatter:
 hints.uppercase:
   default: false
   type: Bool
-  desc: Make chars in hint strings uppercase.
+  desc: Make characters in hint strings uppercase.
 
 ## input
 
@@ -1011,7 +1012,7 @@ keyhint.delay:
     name: Int
     minval: 0
   default: 500
-  desc: Time from pressing a key to seeing the keyhint dialog (ms).
+  desc: Time from pressing a key to seeing the keyhint dialog (milliseconds).
 
 ## messages
 
@@ -1021,7 +1022,7 @@ messages.timeout:
     minval: 0
   default: 2000
   desc: >-
-    Time (in ms) to show messages in the statusbar for.
+    Time (in milliseconds) to show messages in the statusbar for.
 
     Set to 0 to never clear messages.
 
@@ -1323,8 +1324,8 @@ tabs.width.bar:
     minperc: 0
     maxperc: 100
     minint: 1
-  desc: "The width of the tab bar if it's vertical, in px or as percentage of
-    the window."
+  desc: "The width of the tab bar if it's vertical, in pixels or as percentage
+    of the window."
 
 tabs.width.indicator:
   default: 3

From e126faf8c1c7bf7547577db8e7fa46e06978858a Mon Sep 17 00:00:00 2001
From: Marcel Schilling <marcel.schilling@mdc-berlin.de>
Date: Wed, 1 Nov 2017 09:17:13 +0100
Subject: [PATCH 06/21] prefer 'duration' in configdata descriptions

---
 qutebrowser/config/configdata.yml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/qutebrowser/config/configdata.yml b/qutebrowser/config/configdata.yml
index a9629fdb7..9f52137a7 100644
--- a/qutebrowser/config/configdata.yml
+++ b/qutebrowser/config/configdata.yml
@@ -763,7 +763,7 @@ downloads.remove_finished:
     name: Int
     minval: -1
   desc: >-
-    Number of milliseconds to wait before removing finished downloads.
+    Duration in milliseconds to wait before removing finished downloads.
 
     If set to -1, downloads are never removed.
 
@@ -816,7 +816,7 @@ hints.auto_follow:
 hints.auto_follow_timeout:
   default: 0
   type: Int
-  desc: A timeout (in milliseconds) to ignore normal-mode key bindings after a
+  desc: Duration (in milliseconds) to ignore normal-mode key bindings after a
     successful auto-follow.
 
 hints.border:
@@ -1022,7 +1022,7 @@ messages.timeout:
     minval: 0
   default: 2000
   desc: >-
-    Time (in milliseconds) to show messages in the statusbar for.
+    Duration (in milliseconds) to show messages in the statusbar for.
 
     Set to 0 to never clear messages.
 
@@ -1253,7 +1253,7 @@ tabs.show:
 tabs.show_switching_delay:
   default: 800
   type: Int
-  desc: "Time to show the tab bar before hiding it when tabs.show is set to
+  desc: "Duration to show the tab bar before hiding it when tabs.show is set to
     'switching'."
 
 tabs.tabs_are_windows:

From fd52409d0cf9c2c8dc4a67f7e7f26bc3c1d0cae8 Mon Sep 17 00:00:00 2001
From: Marcel Schilling <marcel.schilling@mdc-berlin.de>
Date: Mon, 30 Oct 2017 15:56:09 +0100
Subject: [PATCH 07/21] standardize units in configdata descriptions

 * encapsulate units in parentheses: ('(in <unit>)')
 * move units right behind the corresponding noun
---
 qutebrowser/config/configdata.yml | 20 +++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

diff --git a/qutebrowser/config/configdata.yml b/qutebrowser/config/configdata.yml
index 9f52137a7..7c761b01a 100644
--- a/qutebrowser/config/configdata.yml
+++ b/qutebrowser/config/configdata.yml
@@ -27,7 +27,7 @@ history_gap_interval:
   type: Int
   default: 30
   desc: >-
-    The maximum time in minutes between two history items for them to be
+    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
@@ -628,7 +628,8 @@ completion.height:
     maxperc: 100
     minint: 1
   default: 50%
-  desc: The height of the completion, in pixels or as percentage of the window.
+  desc: The height (in pixels or as percentage of the window) of the
+    completion.
 
 completion.quick:
   default: true
@@ -657,14 +658,14 @@ completion.scrollbar.width:
   type:
     name: Int
     minval: 0
-  desc: Width of the scrollbar in the completion window (in pixels).
+  desc: Width (in pixels) of the scrollbar in the completion window.
 
 completion.scrollbar.padding:
   default: 2
   type:
     name: Int
     minval: 0
-  desc: Padding of the scrollbar handle in the completion window (in pixels).
+  desc: Padding (in pixels) of the scrollbar handle in the completion window.
 
 completion.timestamp_format:
   type:
@@ -689,7 +690,7 @@ completion.delay:
   type:
     name: Int
     minval: 0
-  desc: Delay in milliseconds before updating completions after typing a
+  desc: Delay (in milliseconds) before updating completions after typing a
     character.
 
 completion.min_chars:
@@ -763,7 +764,7 @@ downloads.remove_finished:
     name: Int
     minval: -1
   desc: >-
-    Duration in milliseconds to wait before removing finished downloads.
+    Duration (in milliseconds) to wait before removing finished downloads.
 
     If set to -1, downloads are never removed.
 
@@ -1012,7 +1013,8 @@ keyhint.delay:
     name: Int
     minval: 0
   default: 500
-  desc: Time from pressing a key to seeing the keyhint dialog (milliseconds).
+  desc: Time (in milliseconds) from pressing a key to seeing the keyhint
+    dialog.
 
 ## messages
 
@@ -1324,8 +1326,8 @@ tabs.width.bar:
     minperc: 0
     maxperc: 100
     minint: 1
-  desc: "The width of the tab bar if it's vertical, in pixels or as percentage
-    of the window."
+  desc: "The width (in pixels or as percentage of the window) of the tab bar if
+    it's vertical."
 
 tabs.width.indicator:
   default: 3

From fe8b9519c898c2f56b062a5b40e8e6ea29d233c5 Mon Sep 17 00:00:00 2001
From: Marcel Schilling <marcel.schilling@mdc-berlin.de>
Date: Mon, 30 Oct 2017 16:13:41 +0100
Subject: [PATCH 08/21] avoid redundancy in configdata descriptions

 * drop phrases referring to the settings themselves:
   * 'set ...'
   * 'control ...'
   * 'definitons of ...'
---
 qutebrowser/config/configdata.yml | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/qutebrowser/config/configdata.yml b/qutebrowser/config/configdata.yml
index 7c761b01a..a8522c533 100644
--- a/qutebrowser/config/configdata.yml
+++ b/qutebrowser/config/configdata.yml
@@ -225,7 +225,7 @@ content.cookies.accept:
       - no-unknown-3rdparty: "Accept cookies from the same origin only, unless
           a cookie is already set for the domain."
       - never: "Don't accept cookies at all."
-  desc: Control which cookies to accept.
+  desc: Which cookies to accept.
 
 content.cookies.store:
   default: true
@@ -293,7 +293,7 @@ content.headers.custom:
       name: String
       encoding: ascii
     none_ok: true
-  desc: Set custom headers for qutebrowser HTTP requests.
+  desc: Custom headers for qutebrowser HTTP requests.
 
 content.headers.do_not_track:
   type:
@@ -811,8 +811,7 @@ hints.auto_follow:
           (letter, word or number mode) or the element's text (only in number
           mode)."
       - never: "The user will always need to press Enter to follow a hint."
-  desc: Controls when a hint can be automatically followed without pressing
-    Enter.
+  desc: When a hint can be automatically followed without pressing Enter.
 
 hints.auto_follow_timeout:
   default: 0
@@ -1381,7 +1380,7 @@ url.searchengines:
     keytype: String
     valtype: SearchEngineUrl
   desc: >-
-    Definitions of search engines which can be used via the address bar.
+    Search engines which can be used via the address bar.
 
     Maps a search engine name (such as `DEFAULT`, or `ddg`) to a URL with a
     `{}` placeholder. The placeholder will be replaced by the search term, use

From e744a7c25a1ca2fd9585f8f842de7b751de3a768 Mon Sep 17 00:00:00 2001
From: Marcel Schilling <marcel.schilling@mdc-berlin.de>
Date: Mon, 30 Oct 2017 16:33:35 +0100
Subject: [PATCH 09/21] avoid code duplication in configdata descriptions

 * available placeholders are defined for tabs.title.format
 * tabs.title.format_pinned refers to that definition
 * window.title.format repeats the identical(!) definition
 * this replaces the repetion by another reference
---
 qutebrowser/config/configdata.yml | 15 ++-------------
 1 file changed, 2 insertions(+), 13 deletions(-)

diff --git a/qutebrowser/config/configdata.yml b/qutebrowser/config/configdata.yml
index a8522c533..461ecb424 100644
--- a/qutebrowser/config/configdata.yml
+++ b/qutebrowser/config/configdata.yml
@@ -1435,19 +1435,8 @@ window.title_format:
       - current_url
   default: '{perc}{title}{title_sep}qutebrowser'
   desc: |
-    The format to use for the window title.
-    The following placeholders are defined:
-
-    * `{perc}`: The percentage as a string like `[10%]`.
-    * `{perc_raw}`: The raw percentage, e.g. `10`
-    * `{title}`: The title of the current web page
-    * `{title_sep}`: The string ` - ` if a title is set, empty otherwise.
-    * `{id}`: The internal window ID of this window.
-    * `{scroll_pos}`: The page scroll position.
-    * `{host}`: The host of the current web page.
-    * `{backend}`: Either ''webkit'' or ''webengine''
-    * `{private}` : Indicates when private mode is enabled.
-    * `{current_url}` : The URL of the current web page.
+    The format to use for the window title. The same placeholders like for
+    `tabs.title.format` are defined.
 
 ## zoom
 

From 56671e578707f05c8e580705ef4eab61c0069e93 Mon Sep 17 00:00:00 2001
From: Marcel Schilling <marcel.schilling@mdc-berlin.de>
Date: Mon, 30 Oct 2017 16:42:33 +0100
Subject: [PATCH 10/21] avoid articles in configdata descriptions

 * includes `valid_value` descriptions in addition to `desc` fields
---
 qutebrowser/config/configdata.yml | 83 +++++++++++++++----------------
 1 file changed, 41 insertions(+), 42 deletions(-)

diff --git a/qutebrowser/config/configdata.yml b/qutebrowser/config/configdata.yml
index 461ecb424..3a84042b9 100644
--- a/qutebrowser/config/configdata.yml
+++ b/qutebrowser/config/configdata.yml
@@ -27,7 +27,7 @@ history_gap_interval:
   type: Int
   default: 30
   desc: >-
-    The maximum time (in minutes) between two history items for them to be
+    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
@@ -84,7 +84,7 @@ session_default_name:
     none_ok: true
   default: null
   desc: >-
-    The name of the session to save by default.
+    Name of the session to save by default.
 
     If this is set to null, the session which was last loaded is saved.
 
@@ -96,7 +96,7 @@ backend:
       - webkit: Use QtWebKit (based on WebKit, similar to Safari).
   default: webengine
   desc: >-
-    The backend to use to display websites.
+    Backend to use to display websites.
 
     qutebrowser supports two different web rendering engines / backends,
     QtWebKit and QtWebEngine.
@@ -194,7 +194,7 @@ content.cache.maximum_pages:
     maxval: maxint
   backend: QtWebKit
   desc: >-
-    The maximum number of pages to hold in the global memory page cache.
+    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
@@ -567,7 +567,7 @@ content.proxy:
   default: system
   type: Proxy
   desc: >-
-    The proxy to use.
+    Proxy to use.
 
     In addition to the listed values, you can use a `socks://...` or
     `http://...` URL.
@@ -589,7 +589,7 @@ content.user_stylesheets:
     valtype: File
     none_ok: True
   default: []
-  desc: A list of user stylesheet filenames to use.
+  desc: List of user stylesheet filenames to use.
 
 content.webgl:
   default: true
@@ -628,8 +628,7 @@ completion.height:
     maxperc: 100
     minint: 1
   default: 50%
-  desc: The height (in pixels or as percentage of the window) of the
-    completion.
+  desc: Height (in pixels or as percentage of the window) of the completion.
 
 completion.quick:
   default: true
@@ -713,7 +712,7 @@ downloads.location.directory:
     name: Directory
     none_ok: true
   desc: >-
-    The directory to save downloads to.
+    Directory to save downloads to.
 
     If unset, a sensible OS-specific default is used.
 
@@ -746,7 +745,7 @@ downloads.open_dispatcher:
     none_ok: true
   default: null
   desc: >-
-    The default program used to open downloads.
+    Default program used to open downloads.
 
     If null, the default internal handler is used.
 
@@ -776,7 +775,7 @@ editor.command:
     placeholder: true
   default: ["gvim", "-f", "{file}", "-c", "normal {line}G{column0}l"]
   desc: >-
-    The editor (and arguments) to use for the `open-editor` command.
+    Editor (and arguments) to use for the `open-editor` command.
 
     Several placeholders are supported. Placeholders are substituted by the
     respective value when executing the command.
@@ -840,7 +839,7 @@ hints.dictionary:
   type:
     name: File
     required: false
-  desc: The dictionary file to be used by the word hints.
+  desc: Dictionary file to be used by the word hints.
 
 hints.find_implementation:
   default: python
@@ -889,7 +888,7 @@ hints.next_regexes:
     valtype:
       name: Regex
       flags: IGNORECASE
-  desc: A comma-separated list of regular expressions to use for 'next' links.
+  desc: Comma-separated list of regular expressions to use for 'next' links.
 
 hints.prev_regexes:
   default:
@@ -903,7 +902,7 @@ hints.prev_regexes:
     valtype:
       name: Regex
       flags: IGNORECASE
-  desc: A comma-separated list of regular expressions to use for 'prev' links.
+  desc: Comma-separated list of regular expressions to use for 'prev' links.
 
 hints.scatter:
   default: true
@@ -1003,7 +1002,7 @@ keyhint.radius:
     name: Int
     minval: 0
   default: 6
-  desc: The rounding radius for the edges of the keyhint dialog.
+  desc: Rounding radius for the edges of the keyhint dialog.
 
 # emacs: '
 
@@ -1042,7 +1041,7 @@ prompt.radius:
     name: Int
     minval: 0
   default: 8
-  desc: The rounding radius for the edges of prompts.
+  desc: Rounding radius for the edges of prompts.
 
 ## scrolling
 
@@ -1139,7 +1138,7 @@ statusbar.padding:
 statusbar.position:
   type: VerticalPosition
   default: bottom
-  desc: The position of the status bar.
+  desc: Position of the status bar.
 
 ## tabs
 
@@ -1233,7 +1232,7 @@ tabs.padding:
 tabs.position:
   default: top
   type: Position
-  desc: The position of the tab bar.
+  desc: Position of the tab bar.
 
 tabs.select_on_remove:
   default: 'next'
@@ -1284,20 +1283,20 @@ tabs.title.format:
       - current_url
     none_ok: true
   desc: |
-    The format to use for the tab title.
+    Format to use for the tab title.
     The following placeholders are defined:
 
-    * `{perc}`: The percentage as a string like `[10%]`.
-    * `{perc_raw}`: The raw percentage, e.g. `10`
-    * `{title}`: The title of the current web page
+    * `{perc}`: Percentage as a string like `[10%]`.
+    * `{perc_raw}`: Raw percentage, e.g. `10`
+    * `{title}`: Title of the current web page
     * `{title_sep}`: The string ` - ` if a title is set, empty otherwise.
-    * `{index}`: The index of this tab.
-    * `{id}`: The internal tab ID of this tab.
-    * `{scroll_pos}`: The page scroll position.
-    * `{host}`: The host of the current web page.
+    * `{index}`: Index of this tab.
+    * `{id}`: Internal tab ID of this tab.
+    * `{scroll_pos}`: Page scroll position.
+    * `{host}`: Host of the current web page.
     * `{backend}`: Either ''webkit'' or ''webengine''
     * `{private}` : Indicates when private mode is enabled.
-    * `{current_url}` : The URL of the current web page.
+    * `{current_url}` : URL of the current web page.
 
 tabs.title.format_pinned:
   default: '{index}'
@@ -1315,8 +1314,8 @@ tabs.title.format_pinned:
       - private
       - current_url
     none_ok: true
-  desc: The format to use for the tab title for pinned tabs. The same
-    placeholders like for `tabs.title.format` are defined.
+  desc: Format to use for the tab title for pinned tabs. The same placeholders
+    like for `tabs.title.format` are defined.
 
 tabs.width.bar:
   default: 20%
@@ -1325,7 +1324,7 @@ tabs.width.bar:
     minperc: 0
     maxperc: 100
     minint: 1
-  desc: "The width (in pixels or as percentage of the window) of the tab bar if
+  desc: "Width (in pixels or as percentage of the window) of the tab bar if
     it's vertical."
 
 tabs.width.indicator:
@@ -1359,7 +1358,7 @@ url.default_page:
   type: FuzzyUrl
   default: https://start.duckduckgo.com/
   desc: >-
-    The page to open if :open -t/-b/-w is used without URL.
+    Page to open if :open -t/-b/-w is used without URL.
 
     Use `about:blank` for a blank page.
 
@@ -1368,7 +1367,7 @@ url.incdec_segments:
     name: FlagList
     valid_values: [host, path, query, anchor]
   default: [path, query]
-  desc: The URL segments where `:navigate increment/decrement` will search for
+  desc: URL segments where `:navigate increment/decrement` will search for
     a number.
 
 url.searchengines:
@@ -1396,7 +1395,7 @@ url.start_pages:
     name: ListOrValue
     valtype: FuzzyUrl
   default: ["https://start.duckduckgo.com"]
-  desc: The page(s) to open at the start.
+  desc: Page(s) to open at the start.
 
 url.yank_ignored_parameters:
   type:
@@ -1410,7 +1409,7 @@ url.yank_ignored_parameters:
     - utm_campaign
     - utm_term
     - utm_content
-  desc: The URL parameters to strip with `:yank url`.
+  desc: URL parameters to strip with `:yank url`.
 
 ## window
 
@@ -1435,7 +1434,7 @@ window.title_format:
       - current_url
   default: '{perc}{title}{title_sep}qutebrowser'
   desc: |
-    The format to use for the window title. The same placeholders like for
+    Format to use for the window title. The same placeholders like for
     `tabs.title.format` are defined.
 
 ## zoom
@@ -1443,7 +1442,7 @@ window.title_format:
 zoom.default:
   type: Perc
   default: 100%
-  desc: The default zoom level.
+  desc: Default zoom level.
 
 zoom.levels:
   type:
@@ -1468,7 +1467,7 @@ zoom.levels:
     - 300%
     - 400%
     - 500%
-  desc: The available zoom levels.
+  desc: Available zoom levels.
 
 zoom.mouse_divider:
   default: 512
@@ -2019,7 +2018,7 @@ fonts.web.size.default:
     name: Int
     minval: 1
     maxval: maxint
-  desc: The default font size for regular text.
+  desc: Default font size for regular text.
 
 fonts.web.size.default_fixed:
   default: 13
@@ -2027,7 +2026,7 @@ fonts.web.size.default_fixed:
     name: Int
     minval: 1
     maxval: maxint
-  desc: The default font size for fixed-pitch text.
+  desc: Default font size for fixed-pitch text.
 
 fonts.web.size.minimum:
   default: 0
@@ -2035,7 +2034,7 @@ fonts.web.size.minimum:
     name: Int
     minval: 0
     maxval: maxint
-  desc: The hard minimum font size.
+  desc: Hard minimum font size.
 
 fonts.web.size.minimum_logical:
   # This is 0 as default on QtWebKit, and 6 on QtWebEngine - so let's
@@ -2045,7 +2044,7 @@ fonts.web.size.minimum_logical:
     name: Int
     minval: 0
     maxval: maxint
-  desc: The minimum logical font size that is applied when zooming out.
+  desc: Minimum logical font size that is applied when zooming out.
 
 ## keybindings
 
@@ -2404,7 +2403,7 @@ bindings.commands:
     The following modes are available:
 
 
-    * normal: The default mode, where most commands are invoked.
+    * normal: Default mode, where most commands are invoked.
 
 
     * insert: Entered when an input field is focused on a website, or by

From b187a83d59e8c0003966e61c19196a66ff4aa736 Mon Sep 17 00:00:00 2001
From: Marcel Schilling <marcel.schilling@mdc-berlin.de>
Date: Mon, 30 Oct 2017 17:05:33 +0100
Subject: [PATCH 11/21] avoid spaces before colons in confidata YAML file

 * '  desc : [...]' -> '  desc: [...]'
space ----^      no space ----^
---
 qutebrowser/config/configdata.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/qutebrowser/config/configdata.yml b/qutebrowser/config/configdata.yml
index 3a84042b9..fadc8c5ab 100644
--- a/qutebrowser/config/configdata.yml
+++ b/qutebrowser/config/configdata.yml
@@ -794,7 +794,7 @@ editor.command:
 editor.encoding:
   type: Encoding
   default: utf-8
-  desc : Encoding to use for the editor.
+  desc: Encoding to use for the editor.
 
 ## hints
 

From f76af6c9493087427f5a716c99597e63dd61906b Mon Sep 17 00:00:00 2001
From: Marcel Schilling <marcel.schilling@mdc-berlin.de>
Date: Mon, 30 Oct 2017 17:10:19 +0100
Subject: [PATCH 12/21] define type before desc in configdata YAML file

---
 qutebrowser/config/configdata.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/qutebrowser/config/configdata.yml b/qutebrowser/config/configdata.yml
index fadc8c5ab..f9b525adb 100644
--- a/qutebrowser/config/configdata.yml
+++ b/qutebrowser/config/configdata.yml
@@ -1181,8 +1181,8 @@ tabs.favicons.scale:
 
 tabs.favicons.show:
   default: true
-  desc: Show favicons in the tab bar.
   type: Bool
+  desc: Show favicons in the tab bar.
 
 tabs.indicator_padding:
   default:
@@ -1798,8 +1798,8 @@ colors.statusbar.url.error.fg:
 
 colors.statusbar.url.hover.fg:
   default: aqua
-  desc: Foreground color of the URL in the statusbar for hovered links.
   type: QssColor
+  desc: Foreground color of the URL in the statusbar for hovered links.
 
 colors.statusbar.url.success.http.fg:
   default: white

From 494aceec451e307b0227b0fdd0f86d419dbc11d1 Mon Sep 17 00:00:00 2001
From: Marcel Schilling <marcel.schilling@mdc-berlin.de>
Date: Mon, 30 Oct 2017 17:14:13 +0100
Subject: [PATCH 13/21] use imperative mood for bools in configdata
 descriptions

 * considers ConfirmQuit and BoolAsk in addition to Bool
---
 qutebrowser/config/configdata.yml | 40 ++++++++++++++-----------------
 1 file changed, 18 insertions(+), 22 deletions(-)

diff --git a/qutebrowser/config/configdata.yml b/qutebrowser/config/configdata.yml
index f9b525adb..396692e78 100644
--- a/qutebrowser/config/configdata.yml
+++ b/qutebrowser/config/configdata.yml
@@ -21,7 +21,7 @@ aliases:
 confirm_quit:
   type: ConfirmQuit
   default: [never]
-  desc: Whether quitting the application requires a confirmation.
+  desc: Require a confirmation before quitting the application.
 
 history_gap_interval:
   type: Int
@@ -208,7 +208,7 @@ content.cache.appcache:
   type: Bool
   backend: QtWebKit
   desc: >-
-    Whether support for the HTML 5 web application cache feature is enabled.
+    Enable support for the HTML 5 web application cache feature.
 
     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
@@ -379,7 +379,7 @@ content.headers.user_agent:
 content.host_blocking.enabled:
   default: true
   type: Bool
-  desc: Whether host blocking is enabled.
+  desc: Enable host blocking.
 
 content.host_blocking.lists:
   default:
@@ -425,7 +425,7 @@ content.hyperlink_auditing:
 content.images:
   default: true
   type: Bool
-  desc: Whether images are automatically loaded in web pages.
+  desc: Load images automatically in web pages.
 
 content.javascript.alert:
   default: true
@@ -436,7 +436,7 @@ content.javascript.can_access_clipboard:
   default: false
   type: Bool
   desc: >-
-    Whether JavaScript can read from or write to the clipboard.
+    Allow JavaScript to read from or write to the clipboard.
 
     With QtWebEngine, writing the clipboard as response to a user interaction
     is always allowed.
@@ -445,17 +445,17 @@ content.javascript.can_close_tabs:
   default: false
   type: Bool
   backend: QtWebKit
-  desc: Whether JavaScript can close tabs.
+  desc: Allow JavaScript to close tabs.
 
 content.javascript.can_open_tabs_automatically:
   default: false
   type: Bool
-  desc: Whether JavaScript can open new tabs without user interaction.
+  desc: Allow JavaScript to open new tabs without user interaction.
 
 content.javascript.enabled:
   default: true
   type: Bool
-  desc: Enables or disables JavaScript.
+  desc: Enable or disable JavaScript.
 
 content.javascript.log:
   type:
@@ -497,18 +497,17 @@ content.javascript.prompt:
 content.local_content_can_access_remote_urls:
   default: false
   type: Bool
-  desc: Whether locally loaded documents are allowed to access remote URLs.
+  desc: Allow locally loaded documents to access remote URLs.
 
 content.local_content_can_access_file_urls:
   default: true
   type: Bool
-  desc: Whether locally loaded documents are allowed to access other local
-    URLs.
+  desc: Allow locally loaded documents to access other local URLs.
 
 content.local_storage:
   default: true
   type: Bool
-  desc: Whether support for HTML 5 local storage and Web SQL is enabled.
+  desc: Enable support for HTML 5 local storage and Web SQL.
 
 content.media_capture:
   default: ask
@@ -545,7 +544,7 @@ content.pdfjs:
 content.plugins:
   default: false
   type: Bool
-  desc: Enables or disables plugins in Web pages.
+  desc: Enable or disable plugins in Web pages.
 
 content.print_element_backgrounds:
   type: Bool
@@ -554,8 +553,7 @@ content.print_element_backgrounds:
     QtWebKit: true
     QtWebEngine: Qt 5.8
   desc: >-
-    Whether the background color and images are also drawn when the page is
-    printed.
+    Draw the background color and images also when the page is printed.
 
 content.private_browsing:
   type: Bool
@@ -594,14 +592,13 @@ content.user_stylesheets:
 content.webgl:
   default: true
   type: Bool
-  desc: Enables or disables WebGL.
+  desc: Enable or disable WebGL.
 
 content.xss_auditing:
   type: Bool
   default: false
   desc: >-
-    Whether load requests should be monitored for cross-site scripting
-    attempts.
+    Monitor load requests 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
@@ -702,7 +699,7 @@ completion.min_chars:
 completion.use_best_match:
   type: Bool
   default: false
-  desc: Whether to execute the best-matching command on a partial match.
+  desc: Execute the best-matching command on a partial match.
 
 ## downloads
 
@@ -1340,7 +1337,7 @@ tabs.width.pinned:
 tabs.wrap:
   default: true
   type: Bool
-  desc: Whether to wrap when changing tabs.
+  desc: Wrap when changing tabs.
 
 ## url
 
@@ -1481,8 +1478,7 @@ zoom.text_only:
   type: Bool
   default: false
   backend: QtWebKit
-  desc: Whether the zoom factor on a frame applies only to the text or to all
-    content.
+  desc: Apply the zoom factor on a frame only to the text or to all content.
 
 ## colors
 

From 0a908206bcd7c96e149153f766cc075450469bf2 Mon Sep 17 00:00:00 2001
From: Marcel Schilling <marcel.schilling@mdc-berlin.de>
Date: Mon, 30 Oct 2017 17:17:17 +0100
Subject: [PATCH 14/21] avoid boolean redundancy in configdata descriptions

 * 'Enable or disable [...]' -> 'Enable [...]'
What else? ---^^^^^^^
---
 qutebrowser/config/configdata.yml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/qutebrowser/config/configdata.yml b/qutebrowser/config/configdata.yml
index 396692e78..c2e6d305b 100644
--- a/qutebrowser/config/configdata.yml
+++ b/qutebrowser/config/configdata.yml
@@ -420,7 +420,7 @@ content.host_blocking.whitelist:
 content.hyperlink_auditing:
   default: false
   type: Bool
-  desc: Enable or disable hyperlink auditing (`<a ping>`).
+  desc: Enable hyperlink auditing (`<a ping>`).
 
 content.images:
   default: true
@@ -455,7 +455,7 @@ content.javascript.can_open_tabs_automatically:
 content.javascript.enabled:
   default: true
   type: Bool
-  desc: Enable or disable JavaScript.
+  desc: Enable JavaScript.
 
 content.javascript.log:
   type:
@@ -544,7 +544,7 @@ content.pdfjs:
 content.plugins:
   default: false
   type: Bool
-  desc: Enable or disable plugins in Web pages.
+  desc: Enable plugins in Web pages.
 
 content.print_element_backgrounds:
   type: Bool
@@ -592,7 +592,7 @@ content.user_stylesheets:
 content.webgl:
   default: true
   type: Bool
-  desc: Enable or disable WebGL.
+  desc: Enable WebGL.
 
 content.xss_auditing:
   type: Bool

From 01b29cd64051d55c73102e8c6062fb743243bbd0 Mon Sep 17 00:00:00 2001
From: Marcel Schilling <marcel.schilling@mdc-berlin.de>
Date: Mon, 30 Oct 2017 17:22:54 +0100
Subject: [PATCH 15/21] use interrogative words for configdata descriptions

 * for selections, use appropriate determiner/pro-adverb/pronoun:
   * 'When to [...].'
   * 'How to [...].'
   * 'Which [...] to [...].'
   * 'What [...] to [...].'
---
 qutebrowser/config/configdata.yml | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/qutebrowser/config/configdata.yml b/qutebrowser/config/configdata.yml
index c2e6d305b..1ee6af6a4 100644
--- a/qutebrowser/config/configdata.yml
+++ b/qutebrowser/config/configdata.yml
@@ -41,7 +41,7 @@ ignore_case:
       - never: Search case-sensitively.
       - smart: Search case-sensitively if there are capital characters.
   default: smart
-  desc: Find text on a page case-insensitively.
+  desc: When to find text on a page case-insensitively.
 
 new_instance_open_target:
   type:
@@ -318,7 +318,7 @@ content.headers.referer:
           still protect your privacy, but shouldn't break any sites."
   backend: QtWebKit
   desc: >-
-    Send the Referer header.
+    When to send the Referer header.
 
     The Referer header tells websites from which website you were coming from
     when visting them.
@@ -924,7 +924,7 @@ input.forward_unbound_keys:
     - all: "Forward all unbound keys."
     - auto: "Forward unbound non-alphanumeric keys."
     - none: "Don't forward any keys."
-  desc: Forward unbound keys to the webview in normal mode.
+  desc: Which unbound keys to forward to the webview in normal mode.
 
 input.insert_mode.auto_load:
   default: false
@@ -1163,7 +1163,7 @@ tabs.close_mouse_button_on_bar:
       - close-current: "Close the current tab."
       - close-last: "Close the last tab."
       - ignore: "Don't do anything."
-  desc: Behavior when the close mouse button is pressed on the tab bar.
+  desc: How to behave when the close mouse button is pressed on the tab bar.
 
 tabs.favicons.scale:
   default: 1.0
@@ -1200,7 +1200,7 @@ tabs.last_close:
       - startpage: "Load the start page."
       - default-page: "Load the default page."
       - close: "Close the window."
-  desc: Behavior when the last tab is closed.
+  desc: How to behave when the last tab is closed.
 
 tabs.mousewheel_switching:
   default: true
@@ -1349,7 +1349,7 @@ url.auto_search:
       - dns: Use DNS requests (might be slow!).
       - never: Never search automatically.
   default: naive
-  desc: Whether to start a search when something else than a URL is entered.
+  desc: What search to start when something else than a URL is entered.
 
 url.default_page:
   type: FuzzyUrl

From a6451c05d75bb85afa62a8c7b26ca8014c6eb7f8 Mon Sep 17 00:00:00 2001
From: Marcel Schilling <marcel.schilling@mdc-berlin.de>
Date: Wed, 1 Nov 2017 09:29:06 +0100
Subject: [PATCH 16/21] add missing units to configdata descriptions

 * fixes #3171
---
 qutebrowser/config/configdata.yml | 27 ++++++++++++++-------------
 1 file changed, 14 insertions(+), 13 deletions(-)

diff --git a/qutebrowser/config/configdata.yml b/qutebrowser/config/configdata.yml
index 1ee6af6a4..2d93f7aef 100644
--- a/qutebrowser/config/configdata.yml
+++ b/qutebrowser/config/configdata.yml
@@ -181,7 +181,8 @@ content.cache.size:
     none_ok: true
     minval: 0
     maxval: maxint64
-  desc: Size of the HTTP network cache. Null to use the default value.
+  desc: Size (in bytes) of the HTTP network cache. Null to use the default
+    value.
 
 # Defaults from QWebSettings::QWebSettings() in
 # qtwebkit/Source/WebKit/qt/Api/qwebsettings.cpp
@@ -999,7 +1000,7 @@ keyhint.radius:
     name: Int
     minval: 0
   default: 6
-  desc: Rounding radius for the edges of the keyhint dialog.
+  desc: Rounding radius (in pixels) for the edges of the keyhint dialog.
 
 # emacs: '
 
@@ -1038,7 +1039,7 @@ prompt.radius:
     name: Int
     minval: 0
   default: 8
-  desc: Rounding radius for the edges of prompts.
+  desc: Rounding radius (in pixels) for the edges of prompts.
 
 ## scrolling
 
@@ -1130,7 +1131,7 @@ statusbar.padding:
     bottom: 1
     left: 0
     right: 0
-  desc: Padding for the statusbar.
+  desc: Padding (in pixels) for the statusbar.
 
 statusbar.position:
   type: VerticalPosition
@@ -1188,7 +1189,7 @@ tabs.indicator_padding:
     left: 0
     right: 4
   type: Padding
-  desc: Padding for tab indicators.
+  desc: Padding (in pixels) for tab indicators.
 
 tabs.last_close:
   default: ignore
@@ -1224,7 +1225,7 @@ tabs.padding:
     left: 5
     right: 5
   type: Padding
-  desc: Padding around text for tabs.
+  desc: Padding (in pixels) around text for tabs.
 
 tabs.position:
   default: top
@@ -1250,8 +1251,8 @@ tabs.show:
 tabs.show_switching_delay:
   default: 800
   type: Int
-  desc: "Duration to show the tab bar before hiding it when tabs.show is set to
-    'switching'."
+  desc: "Duration (in milliseconds) to show the tab bar before hiding it when
+    tabs.show is set to 'switching'."
 
 tabs.tabs_are_windows:
   default: false
@@ -1329,7 +1330,7 @@ tabs.width.indicator:
   type:
     name: Int
     minval: 0
-  desc: Width of the progress indicator (0 to disable).
+  desc: Width (in pixels) of the progress indicator (0 to disable).
 
 tabs.width.pinned:
   deleted: true
@@ -2014,7 +2015,7 @@ fonts.web.size.default:
     name: Int
     minval: 1
     maxval: maxint
-  desc: Default font size for regular text.
+  desc: Default font size (in pixels) for regular text.
 
 fonts.web.size.default_fixed:
   default: 13
@@ -2022,7 +2023,7 @@ fonts.web.size.default_fixed:
     name: Int
     minval: 1
     maxval: maxint
-  desc: Default font size for fixed-pitch text.
+  desc: Default font size (in pixels) for fixed-pitch text.
 
 fonts.web.size.minimum:
   default: 0
@@ -2030,7 +2031,7 @@ fonts.web.size.minimum:
     name: Int
     minval: 0
     maxval: maxint
-  desc: Hard minimum font size.
+  desc: Hard minimum font size (in pixels).
 
 fonts.web.size.minimum_logical:
   # This is 0 as default on QtWebKit, and 6 on QtWebEngine - so let's
@@ -2040,7 +2041,7 @@ fonts.web.size.minimum_logical:
     name: Int
     minval: 0
     maxval: maxint
-  desc: Minimum logical font size that is applied when zooming out.
+  desc: Minimum logical font size (in pixels) that is applied when zooming out.
 
 ## keybindings
 

From aebe4c8f9e2b696aaf73fd7e49b7938f99f36e1e Mon Sep 17 00:00:00 2001
From: Marcel Schilling <marcel.schilling@mdc-berlin.de>
Date: Wed, 1 Nov 2017 09:33:12 +0100
Subject: [PATCH 17/21] assume single user in configdata descriptions

 * 'a user' -> 'the user'
---
 qutebrowser/config/configdata.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/qutebrowser/config/configdata.yml b/qutebrowser/config/configdata.yml
index 2d93f7aef..2c0eef9dc 100644
--- a/qutebrowser/config/configdata.yml
+++ b/qutebrowser/config/configdata.yml
@@ -976,7 +976,7 @@ input.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
+    Left, Right, Up and Down arrow keys. For example, if the 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.
 

From 87ec7a1a0b1f99dd47c4da110205026f32387d7f Mon Sep 17 00:00:00 2001
From: Marcel Schilling <marcel.schilling@mdc-berlin.de>
Date: Thu, 2 Nov 2017 14:18:02 +0100
Subject: [PATCH 18/21] prefer nouns for configdata descriptions

 * reserve interrogative words for selection type options
---
 qutebrowser/config/configdata.yml | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/qutebrowser/config/configdata.yml b/qutebrowser/config/configdata.yml
index 2c0eef9dc..668694127 100644
--- a/qutebrowser/config/configdata.yml
+++ b/qutebrowser/config/configdata.yml
@@ -165,7 +165,8 @@ auto_save.interval:
     minval: 0
     maxval: maxint
   default: 15000
-  desc: How often (in milliseconds) to auto-save config/cookies/etc.
+  desc: Time interval (in milliseconds) between auto-saves of
+    config/cookies/etc.
 
 auto_save.session:
   type: Bool
@@ -615,7 +616,7 @@ completion.cmd_history_max_items:
     name: Int
     minval: -1
   desc: >-
-    How many commands to save in the command history.
+    Number of commands to save in the command history.
 
     0: no history / -1: unlimited
 
@@ -669,7 +670,7 @@ completion.timestamp_format:
     name: TimestampTemplate
     none_ok: true
   default: '%Y-%m-%d'
-  desc: How to format timestamps (e.g. for the history completion).
+  desc: Format of timestamps (e.g. for the history completion).
 
 completion.web_history_max_items:
   default: -1
@@ -678,7 +679,7 @@ completion.web_history_max_items:
     minval: -1
     maxval: maxint64
   desc: >-
-    How many URLs to show in the web history.
+    Number of URLs to show in the web history.
 
     0: no history / -1: unlimited
 
@@ -1211,12 +1212,12 @@ tabs.mousewheel_switching:
 tabs.new_position.related:
   default: next
   type: NewTabPosition
-  desc: How new tabs opened from another tab are positioned.
+  desc: Position of new tabs opened from another tab.
 
 tabs.new_position.unrelated:
   default: last
   type: NewTabPosition
-  desc: "How new tabs which aren't opened from another tab are positioned."
+  desc: "Position of new tabs which aren't opened from another tab."
 
 tabs.padding:
   default:
@@ -1472,8 +1473,7 @@ zoom.mouse_divider:
   type:
     name: Int
     minval: 0
-  desc: How much to divide the mouse wheel movements to translate them into
-    zoom increments.
+  desc: Number of zoom increments to divide the mouse wheel movements to.
 
 zoom.text_only:
   type: Bool

From c6d75092201f3a8be0bfe41db4532eb82ecf9b99 Mon Sep 17 00:00:00 2001
From: Marcel Schilling <marcel.schilling@mdc-berlin.de>
Date: Thu, 2 Nov 2017 14:44:42 +0100
Subject: [PATCH 19/21] rephrase configdata descriptions

 * see discussion of PR #3181
---
 qutebrowser/config/configdata.yml | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/qutebrowser/config/configdata.yml b/qutebrowser/config/configdata.yml
index 668694127..48c7ce294 100644
--- a/qutebrowser/config/configdata.yml
+++ b/qutebrowser/config/configdata.yml
@@ -523,7 +523,7 @@ content.netrc_file:
     name: File
     none_ok: true
   desc: >-
-    Location of a netrc-file for HTTP authentication.
+    Netrc-file for HTTP authentication.
 
     If unset, `~/.netrc` is used.
 
@@ -538,7 +538,7 @@ content.pdfjs:
   type: Bool
   backend: QtWebKit
   desc: >-
-    Enable pdf.js to view PDF files in the browser.
+    Allow 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.
@@ -1110,7 +1110,7 @@ spellcheck.languages:
     none_ok: true
   default: []
   desc: >-
-    Spell checking languages.
+    Languages to use for spell checking.
 
     You can check for available languages and install dictionaries using
     scripts/install_dict.py. Run the script with -h/--help for instructions.
@@ -1154,7 +1154,7 @@ tabs.close_mouse_button:
       - right: "Close tabs on right-click."
       - middle: "Close tabs on middle-click."
       - none: "Don't close tabs using the mouse."
-  desc: On which mouse button to close tabs.
+  desc: Mouse button with which to close tabs.
 
 tabs.close_mouse_button_on_bar:
   default: new-tab
@@ -1173,7 +1173,7 @@ tabs.favicons.scale:
     name: Float
     minval: 0.0
   desc: >-
-    Scaling for favicons in the tab bar.
+    Scaling factor for favicons in the tab bar.
 
     The tab size is unchanged, so big favicons also require extra
     `tabs.padding`.

From af9c94bd231e39fb0f06ce05f9c0454e9bda9bc5 Mon Sep 17 00:00:00 2001
From: Marcel Schilling <marcel.schilling@mdc-berlin.de>
Date: Thu, 2 Nov 2017 14:47:42 +0100
Subject: [PATCH 20/21] add myself as codeowner for configdata YAML file

 * to be notified of changes so I can help maintain consistency
---
 .github/CODEOWNERS | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index 2b8c12de9..a27cc9f1d 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -1,5 +1,6 @@
 qutebrowser/browser/history.py  @rcorre
 qutebrowser/completion/*  @rcorre
+qutebrowser/config/configdata.yml  @mschilli87
 qutebrowser/misc/sql.py  @rcorre
 tests/end2end/features/completion.feature  @rcorre
 tests/end2end/features/test_completion_bdd.py  @rcorre

From 7e07f5c9965e109a87c6661e8eb61a57020efa2c Mon Sep 17 00:00:00 2001
From: Marcel Schilling <marcel.schilling@mdc-berlin.de>
Date: Fri, 3 Nov 2017 08:48:30 +0100
Subject: [PATCH 21/21] standardize placeholders in configdata descriptions

 * Keep descriptions concise.
 * Prefer starting descriptions with a noun.
 * Don't explain that placeholders are placeholders/get replaced.
 * Introduce placeholder list by the following line:
   'The following placeholders are defined:'
 * List placeholders in a markdown-style list:
   '* `{<placeholder>}`: <description>.'
---
 qutebrowser/config/configdata.yml | 18 ++++++------------
 1 file changed, 6 insertions(+), 12 deletions(-)

diff --git a/qutebrowser/config/configdata.yml b/qutebrowser/config/configdata.yml
index 48c7ce294..4a73822e4 100644
--- a/qutebrowser/config/configdata.yml
+++ b/qutebrowser/config/configdata.yml
@@ -775,19 +775,13 @@ editor.command:
   default: ["gvim", "-f", "{file}", "-c", "normal {line}G{column0}l"]
   desc: >-
     Editor (and arguments) to use for the `open-editor` command.
+    The following placeholders are defined:
 
-    Several placeholders are supported. Placeholders are substituted by the
-    respective value when executing the command.
-
-    `{file}` gets replaced by the filename of the file to be edited.
-
-    `{line}` gets replaced by the line in which the caret is found in the text.
-
-    `{column}` gets replaced by the column in which the caret is found in the text.
-
-    `{line0}` same as `{line}`, but starting from index 0.
-
-    `{column0}` same as `{column}`, but starting from index 0.
+    * `{file}`: Filename of the file to be edited.
+    * `{line}`: Line in which the caret is found in the text.
+    * `{column}`: Column in which the caret is found in the text.
+    * `{line0}`: Same as `{line}`, but starting from index 0.
+    * `{column0}`: Same as `{column}`, but starting from index 0.
 
 
 editor.encoding: