From aa8d66f0925d698370f20d3a1b849409a2b141c0 Mon Sep 17 00:00:00 2001 From: Florian Bruhin Date: Sat, 2 Aug 2014 22:54:15 +0200 Subject: [PATCH] Improve settings value documentation. --- qutebrowser/config/configdata.py | 183 +++++++++++++++---------------- qutebrowser/config/conftypes.py | 9 +- 2 files changed, 92 insertions(+), 100 deletions(-) diff --git a/qutebrowser/config/configdata.py b/qutebrowser/config/configdata.py index 198ccf9fd..beec9bdbd 100644 --- a/qutebrowser/config/configdata.py +++ b/qutebrowser/config/configdata.py @@ -64,7 +64,7 @@ FIRST_COMMENT = r""" SECTION_DESC = { - 'general': "General/misc. options.", + 'general': "General/miscellaneous options.", 'ui': "General options related to the user interface.", 'input': "Options related to input modes.", 'network': "Settings related to the network.", @@ -113,7 +113,8 @@ SECTION_DESC = { "Keybindings for passthrough mode.\n" "Since normal keypresses are passed through, only special keys are " "supported in this mode.\n" - "An useful command to map here is the hidden command leave-mode."), + "Useful hidden commands to map in this section:\n\n" + " * `leave-mode`: Leave the passthrough mode."), 'keybind.command': ( "Keybindings for command mode.\n" "Since normal keypresses are passed through, only special keys are " @@ -161,7 +162,7 @@ SECTION_DESC = { 'fonts': ( "Fonts used for the UI, with optional style/weight/size.\n\n" " * Style: `normal`/`italic`/`oblique`\n" - " * Weight: `normal`, `bold`, 100..900\n" + " * Weight: `normal`, `bold`, `100`..`900`\n" " * Size: _number_ `px`/`pt`\n\n" "Note: The font for hints is a true CSS font, not a Qt-CSS one, " "because of that, a general ``Monospace'' family is enough and we " @@ -173,11 +174,11 @@ DATA = OrderedDict([ ('general', sect.KeyValue( ('ignore-case', SettingValue(types.Bool(), 'true'), - "Whether to do case-insensitive searching."), + "Whether to find text on a page case-insensitively."), ('wrap-search', SettingValue(types.Bool(), 'true'), - "Whether to wrap search to the top when arriving at the end."), + "Whether to wrap finding text to the top when arriving at the end."), ('startpage', SettingValue(types.List(), 'http://www.duckduckgo.com'), @@ -198,37 +199,44 @@ DATA = OrderedDict([ ('editor', SettingValue(types.ShellCommand(placeholder=True), 'gvim -f "{}"'), - "The editor (and arguments) to use for the open-editor binding. " - "Use `{}` for the filename. Gets split via shutils."), + "The editor (and arguments) to use for the `open-editor` command.\n\n" + "Use `{}` for the filename. The value gets split like in a shell, so " + "you can use `\"` or `'` to quote arguments."), ('private-browsing', SettingValue(types.Bool(), 'false'), - "Private browsing prevents WebKit from recording visited pages in " - "the history and storing web page icons."), + "Do not record visited pages in the history or store web page " + "icons."), ('developer-extras', SettingValue(types.Bool(), 'false'), - "Enables extra tools for Web developers (e.g. webinspector)."), + "Enable extra tools for Web developers.\n\n" + "This needs to be enabled for `:inspector` to work and also adds an " + "_Inspect_ entry to the context menu."), ('print-element-backgrounds', SettingValue(types.Bool(), 'true'), - "Specifies whether the background color and images are also drawn " - "when the page is printed."), + "Whether the background color and images are also drawn when the " + "page is printed."), ('xss-auditing', SettingValue(types.Bool(), 'false'), - "Specifies 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."), + "Whether load requests should be monitored for cross-site scripting " + "attempts.\n\n" + "Suspicious scripts will be blocked and reported in the inspector's " + "JavaScript console. Enabling this feature might have an impact on " + "performance."), ('site-specific-quirks', SettingValue(types.Bool(), 'true'), - "This setting enables WebKit's workaround for broken sites."), + "Enable workarounds for broken sites."), ('default-encoding', SettingValue(types.String(none_ok=True), ''), - "Default encoding to use for websites."), + "Default encoding to use for websites.\n\n" + "The encoding must be a string describing an encoding such as " + '_utf-8_, _iso-8859-1_, etc. If left empty a default value will be ' + "used."), )), ('ui', sect.KeyValue( @@ -256,63 +264,31 @@ DATA = OrderedDict([ ('zoom-text-only', SettingValue(types.Bool(), 'false'), - "Specifies whether the zoom factor on a frame applies only to the " - "text or to all content."), + "Whether the zoom factor on a frame applies only to the text or to " + "all content."), ('frame-flattening', SettingValue(types.Bool(), 'false'), - "With this setting each subframe is expanded to its contents. This " - "will flatten all the frames to become one scrollable " - "page."), - - ('frame-flattening', - SettingValue(types.Bool(), 'false'), - "With this setting each subframe is expanded to its contents. This " - "will flatten all the frames to become one scrollable " - "page."), + "Whether to expand each subframe to its contents.\n\n" + "This will flatten all the frames to become one scrollable page."), ('user-stylesheet', SettingValue(types.WebSettingsFile(), ''), - "User stylesheet to set."), - - ('user-stylesheet', - SettingValue(types.WebSettingsFile(), ''), - "User stylesheet to set."), + "User stylesheet to use."), ('css-media-type', SettingValue(types.String(none_ok=True), ''), "Set the CSS media type."), - - ('css-media-type', - SettingValue(types.String(none_ok=True), ''), - "Set the CSS media type."), - - #('accelerated-compositing', - # SettingValue(types.Bool(), 'true'), - # "This feature, when used in conjunction with QGraphicsWebView, " - # "accelerates animations of web content. CSS animations of the " - # "transform and opacity properties will be rendered by composing the " - # "cached content of the animated elements."), - - #('tiled-backing-store', - # SettingValue(types.Bool(), 'false'), - # "This setting enables the tiled backing store feature for a " - # "QGraphicsWebView. With the tiled backing store enabled, the web " - # "page contents in and around the current visible area is " - # "speculatively cached to bitmap tiles. The tiles are automatically " - # "kept in sync with the web page as it changes. Enabling tiling can " - # "significantly speed up painting heavy operations like scrolling. " - # "Enabling the feature increases memory consuption."), )), ('network', sect.KeyValue( ('do-not-track', SettingValue(types.Bool(), 'true'), - "Value to send in the DNT header."), + "Value to send in the `DNT` header."), ('accept-language', SettingValue(types.String(none_ok=True), 'en-US,en'), - "Value to send in the accept-language header."), + "Value to send in the `accept-language` header."), ('user-agent', SettingValue(types.String(none_ok=True), ''), @@ -320,7 +296,9 @@ DATA = OrderedDict([ ('proxy', SettingValue(types.Proxy(), 'system'), - "The proxy to use."), + "The proxy to use.\n\n" + "In addition to the listed values, you can use a `socks://...` or " + "`http://...` URL."), ('ssl-strict', SettingValue(types.Bool(), 'true'), @@ -328,14 +306,13 @@ DATA = OrderedDict([ ('dns-prefetch', SettingValue(types.Bool(), 'true'), - "Specifies whether QtWebkit will try to pre-fetch DNS entries to " - "speed up browsing."), + "Whether to try to pre-fetch DNS entries to speed up browsing."), )), ('completion', sect.KeyValue( ('show', SettingValue(types.Bool(), 'true'), - "Whether to show the autocompletion window or not."), + "Whether to show the autocompletion window."), ('height', SettingValue(types.PercOrInt(minperc=0, maxperc=100, minint=1), @@ -345,8 +322,8 @@ DATA = OrderedDict([ ('history-length', SettingValue(types.Int(minval=-1), '100'), - "How many commands to save in the history. 0: no history / -1: " - "unlimited"), + "How many commands to save in the history.\n\n" + "0: no history / -1: unlimited"), ('quick-complete', SettingValue(types.Bool(), 'true'), @@ -384,15 +361,18 @@ DATA = OrderedDict([ ('spatial-navigation', SettingValue(types.Bool(), 'false'), - "Enables or disables the Spatial Navigation feature, which 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."), + "Enables or disables the Spatial Navigation feature\n\n" + "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."), ('links-included-in-focus-chain', SettingValue(types.Bool(), 'true'), - "Specifies whether hyperlinks should be included in the keyboard " - "focus chain."), + "Whether hyperlinks should be included in the keyboard focus " + "chain."), )), ('tabbar', sect.KeyValue( @@ -448,14 +428,26 @@ DATA = OrderedDict([ ('maximum-pages-in-cache', SettingValue(types.Int(none_ok=True, minval=0, maxval=MAXVALS['int']), ''), - "Sets the maximum number of pages to hold in the memory page cache."), + "The maximum number of pages to hold in the memory page cache.\n\n" + "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.\n\n" + "For more information about the feature, please refer to: " + "http://webkit.org/blog/427/webkit-page-cache-i-the-basics/"), ('object-cache-capacities', SettingValue(types.WebKitBytesList(length=3, maxsize=MAXVALS['int']), ''), - "Specifies the capacities for the memory cache for dead objects " - "such as stylesheets or scripts. Three values are expected: " - "cacheMinDeadCapacity, cacheMaxDead, totalCapacity."), + "The capacities for the memory cache for dead objects such as " + "stylesheets or scripts. Syntax: cacheMinDeadCapacity, cacheMaxDead, " + "totalCapacity.\n\n" + "The _cacheMinDeadCapacity_ specifies the minimum number of bytes " + "that dead objects should consume when the cache is under " + "pressure.\n\n" + "_cacheMaxDead_ is the maximum number of bytes that dead objects " + "should consume when the cache is *not* under pressure.\n\n" + "_totalCapacity_ specifies the maximum number of bytes " + "that the cache should consume *overall*."), ('offline-storage-default-quota', SettingValue(types.WebKitBytes(maxsize=MAXVALS['int64']), ''), @@ -467,37 +459,38 @@ DATA = OrderedDict([ ('offline-storage-database', SettingValue(types.Bool(), 'true'), - "Specifies whether support for the HTML 5 offline storage feature is " - "enabled or not."), + "Whether support for the HTML 5 offline storage feature is enabled."), ('offline-web-application-storage', SettingValue(types.Bool(), 'true'), - "Specifies whether support for the HTML 5 web application cache " - "feature is enabled or not."), + "Whether support for the HTML 5 web application cache feature is " + "enabled.\n\n" + "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.\n\n" + "The feature is described in details at: " + "http://dev.w3.org/html5/spec/Overview.html#appcache"), ('local-storage', SettingValue(types.Bool(), 'true'), - "Specifies whether support for the HTML 5 local storage feature is " - "enabled or not."), + "Whether support for the HTML 5 local storage feature is enabled."), )), ('permissions', sect.KeyValue( ('allow-images', SettingValue(types.Bool(), 'true'), - "Specifies whether images are automatically loaded in web pages."), + "Whether images are automatically loaded in web pages."), ('allow-javascript', SettingValue(types.Bool(), 'true'), "Enables or disables the running of JavaScript programs."), - #('allow-java', - # SettingValue(types.Bool(), 'true'), - # "Enables or disables Java applets. Currently Java applets are " - # "not supported"), - ('allow-plugins', SettingValue(types.Bool(), 'false'), - "Enables or disables plugins in Web pages."), + "Enables or disables plugins in Web pages.\n\n" + 'Qt plugins with a mimetype such as "application/x-qt-plugin" are ' + "not affected by this setting."), ('allow-javascript', SettingValue(types.Bool(), 'true'), @@ -514,26 +507,25 @@ DATA = OrderedDict([ ('javascript-can-open-windows', SettingValue(types.Bool(), 'false'), - "Specifies whether JavaScript programs can open new windows."), + "Whether JavaScript programs can open new windows."), ('javascript-can-close-windows', SettingValue(types.Bool(), 'false'), - "Specifies whether JavaScript programs can close windows."), + "Whether JavaScript programs can close windows."), ('javascript-can-access-clipboard', SettingValue(types.Bool(), 'false'), - "Specifies whether JavaScript programs can read or write to the " - "clipboard."), + "Whether JavaScript programs can read or write to the clipboard."), ('local-content-can-access-remote-urls', SettingValue(types.Bool(), 'false'), - "Specifies whether locally loaded documents are allowed to access " - "remote urls."), + "Whether locally loaded documents are allowed to access remote " + "urls."), ('local-content-can-access-file-urls', SettingValue(types.Bool(), 'true'), - "Specifies whether locally loaded documents are allowed to access " - "other local urls."), + "Whether locally loaded documents are allowed to access other local " + "urls."), ('cookies-accept', SettingValue(types.AcceptCookies(), 'default'), @@ -542,7 +534,6 @@ DATA = OrderedDict([ ('cookies-store', SettingValue(types.Bool(), 'true'), "Whether to store cookies."), - )), ('hints', sect.KeyValue( @@ -771,7 +762,7 @@ DATA = OrderedDict([ ('completion.bg', SettingValue(types.QssColor(), '#333333'), - "Text color of the completion widget."), + "Background color of the completion widget."), ('completion.item.bg', SettingValue(types.QssColor(), '${completion.bg}'), diff --git a/qutebrowser/config/conftypes.py b/qutebrowser/config/conftypes.py index 0b850d958..916cfb100 100644 --- a/qutebrowser/config/conftypes.py +++ b/qutebrowser/config/conftypes.py @@ -455,7 +455,7 @@ class ColorSystem(BaseType): valid_values = ValidValues(('rgb', "Interpolate in the RGB color system."), ('hsv', "Interpolate in the HSV color system."), - ('hsl', "Interpolate in the HSV color system.")) + ('hsl', "Interpolate in the HSL color system.")) def validate(self, value): super().validate(value.lower()) @@ -742,7 +742,8 @@ class HintMode(BaseType): """Base class for the hints -> mode setting.""" valid_values = ValidValues(('number', "Use numeric hints."), - ('letter', "Use the chars in hints -> chars.")) + ('letter', "Use the chars in the hints -> chars " + "setting.")) class Proxy(BaseType): @@ -899,7 +900,7 @@ class LastClose(BaseType): """Behaviour when the last tab is closed.""" valid_values = ValidValues(('ignore', "Don't do anything."), - ('blank', "Load about:blank."), + ('blank', "Load a blank page."), ('quit', "Quit qutebrowser.")) @@ -907,7 +908,7 @@ class AcceptCookies(BaseType): """Whether to accept a cookie.""" - valid_values = ValidValues(('default', "Default QtWebKit behaviour"), + valid_values = ValidValues(('default', "Default QtWebKit behaviour."), ('never', "Don't accept cookies at all."))