From 8a61bd635aaa17ee50118bafaa67b2134e695e09 Mon Sep 17 00:00:00 2001 From: Florian Bruhin Date: Wed, 8 Sep 2021 16:18:28 +0200 Subject: Improve docs for URL patterns Closes #6454, see #5069 --- doc/help/commands.asciidoc | 6 +- doc/help/configuring.asciidoc | 24 ++++++-- doc/help/settings.asciidoc | 108 +++++++++++++++++------------------ qutebrowser/config/configcommands.py | 6 +- scripts/dev/src2asciidoc.py | 2 +- 5 files changed, 80 insertions(+), 66 deletions(-) diff --git a/doc/help/commands.asciidoc b/doc/help/commands.asciidoc index 49b17c3df..f55cd7afc 100644 --- a/doc/help/commands.asciidoc +++ b/doc/help/commands.asciidoc @@ -294,7 +294,7 @@ Cycle an option between multiple values. * +'values'+: The values to cycle through. ==== optional arguments -* +*-u*+, +*--pattern*+: The URL pattern to use. +* +*-u*+, +*--pattern*+: The link:configuring{outfilesuffix}#patterns[URL pattern] to use. * +*-t*+, +*--temp*+: Set value temporarily until qutebrowser is closed. * +*-p*+, +*--print*+: Print the value after setting. @@ -391,7 +391,7 @@ This sets an option back to its default and removes it from autoconfig.yml. * +'option'+: The name of the option. ==== optional arguments -* +*-u*+, +*--pattern*+: The URL pattern to use. +* +*-u*+, +*--pattern*+: The link:configuring{outfilesuffix}#patterns[URL pattern] to use. * +*-t*+, +*--temp*+: Set value temporarily until qutebrowser is closed. [[config-write-py]] @@ -1285,7 +1285,7 @@ If the option name ends with '?' or no value is provided, the value of the optio ==== optional arguments * +*-t*+, +*--temp*+: Set value temporarily until qutebrowser is closed. * +*-p*+, +*--print*+: Print the value after setting. -* +*-u*+, +*--pattern*+: The URL pattern to use. +* +*-u*+, +*--pattern*+: The link:configuring{outfilesuffix}#patterns[URL pattern] to use. [[set-cmd-text]] === set-cmd-text diff --git a/doc/help/configuring.asciidoc b/doc/help/configuring.asciidoc index ec6ffbcb1..728942ab1 100644 --- a/doc/help/configuring.asciidoc +++ b/doc/help/configuring.asciidoc @@ -22,6 +22,19 @@ exists, the `autoconfig.yml` file **is not read anymore** by default. You need to <> if you want settings changed via `:set`/`:bind` to persist between restarts. +[[patterns]] +URL pattern support +------------------- + +Many settings are customizable depending on the page being visited by using URL +patterns. The link:settings{outfilesuffix}[settings documentation] marks such +settings with "This setting supports URL patterns. + +The syntax is based on Chromium's +https://developer.chrome.com/docs/extensions/mv3/match_patterns/[URL pattern syntax]. +As an extension, the scheme and path can be left off as a short-hand syntax, so +`example.com` is equivalent to `*://example.com/*`. + [[autoconfig]] Configuring qutebrowser via the user interface ---------------------------------------------- @@ -45,9 +58,10 @@ customizable. Using the link:commands{outfilesuffix}#set[`:set`] command and command completion, you can quickly set settings interactively, for example `:set tabs.position left`. -Some settings are also customizable for a given -https://developer.chrome.com/apps/match_patterns[URL pattern] by doing e.g. -`:set --pattern=*://example.com/ content.images false`. +<> can be used via ` +`:set --pattern *://example.com/* content.images false`, or with shorthand +syntax for both argument and pattern, `:set -u example.com content.images +false`. To get more help about a setting, use e.g. `:help tabs.position`. @@ -160,8 +174,8 @@ color = config.get('colors.completion.fg') Per-domain settings ~~~~~~~~~~~~~~~~~~~ -Using `config.set`, some settings are also customizable for a given -https://developer.chrome.com/apps/match_patterns[URL pattern]: +Using `config.set` instead of the `c.` shorthand, many settings are also +customizable for a given <>. [source,python] ---- diff --git a/doc/help/settings.asciidoc b/doc/help/settings.asciidoc index 1b11710f5..18dfebc5d 100644 --- a/doc/help/settings.asciidoc +++ b/doc/help/settings.asciidoc @@ -1959,7 +1959,7 @@ Default: === content.autoplay Automatically start playing `