Improve some docstrings.

doc/help/commands.asciidoc

@@ -21,7 +21,6 @@
 |<<paste,paste>>|Open a page from the clipboard.
 |<<prev-page,prev-page>>|Open a "previous" link.
 |<<print,print>>|Print the current/[count]th tab.
-|<<q,q>>|Quit qutebrowser.
 |<<quickmark-add,quickmark-add>>|Add a new quickmark.
 |<<quickmark-load,quickmark-load>>|Load a quickmark.
 |<<quickmark-save,quickmark-save>>|Save the current page as a quickmark.
@@ -59,9 +58,9 @@ Syntax: +:bind 'key' 'command' ['mode']+
 Bind a key to a command.
 
 ==== positional arguments
-* +'key'+: The keychain or special key (inside <...>) to bind.
+* +'key'+: The keychain or special key (inside `<...>`) to bind.
 * +'command'+: The command to execute.
-* +'mode'+: A comma-separated list of modes to bind the key in (default: normal mode).
+* +'mode'+: A comma-separated list of modes to bind the key in (default: `normal`).
 
 
 [[cancel-download]]
@@ -78,13 +77,13 @@ Go forward in the history of the current tab.
 
 [[get]]
 === get
-Syntax: +:get 'sectname' 'optname'+
+Syntax: +:get 'section' 'option'+
 
 Get the value from a section/option.
 
 ==== positional arguments
-* +'sectname'+: The section where the option is in.
+* +'section'+: The section where the option is in.
-* +'optname'+: The name of the option.
+* +'option'+: The name of the option.
 
 [[help]]
 === help
@@ -123,10 +122,6 @@ Start hinting.
  - `yank-primary`: Yank the link to the primary selection.
  - `fill`: Fill the commandline with the command given as
  argument.
- - `cmd-tab`: Fill the commandline with `:open -t` and the
- link.
- - `cmd-tag-bg`: Fill the commandline with `:open -b` and
- the link.
  - `rapid`: Open the link in a new tab and stay in hinting mode.
  - `download`: Download the link.
  - `userscript`: Call an userscript with `$QUTE_URL` set to the
@@ -156,13 +151,13 @@ Toggle the web inspector.
 
 [[later]]
 === later
-Syntax: +:later 'ms' 'command' ['command' ...]+
+Syntax: +:later 'ms' 'command'+
 
 Execute a command after some time.
 
 ==== positional arguments
 * +'ms'+: How many milliseconds to wait.
-* +'command'+: The command/args to run.
+* +'command'+: The command to run.
 
 [[next-page]]
 === next-page
@@ -170,33 +165,34 @@ Syntax: +:next-page [*--tab*]+
 
 Open a "next" link.
 
-This tries to automatically click on typical "Next Page" links using some heuristics.
+This tries to automatically click on typical _Next Page_ links using some heuristics.
 
 ==== optional arguments
-* +*-t*+, +*--tab*+: Whether to open a new tab.
+* +*-t*+, +*--tab*+: Open in a new tab.
 
 [[open]]
 === open
-Syntax: +:open [*--bg*] [*--tab*] 'urlstr'+
+Syntax: +:open [*--bg*] [*--tab*] 'url'+
 
 Open a URL in the current/[count]th tab.
 
 ==== positional arguments
-* +'urlstr'+: The URL to open, as string.
+* +'url'+: The URL to open.
 
 ==== optional arguments
-* +*-b*+, +*--bg*+: Whether to open in a background tab.
+* +*-b*+, +*--bg*+: Open in a new background tab.
-* +*-t*+, +*--tab*+: Whether to open in a tab.
+* +*-t*+, +*--tab*+: Open in a new tab.
 
 [[paste]]
 === paste
-Syntax: +:paste [*--sel*] [*--tab*]+
+Syntax: +:paste [*--sel*] [*--tab*] [*--bg*]+
 
 Open a page from the clipboard.
 
 ==== optional arguments
-* +*-s*+, +*--sel*+: True to use primary selection, False to use clipboard
+* +*-s*+, +*--sel*+: Use the primary selection instead of the clipboard.
-* +*-t*+, +*--tab*+: True to open in a new tab.
+* +*-t*+, +*--tab*+: Open in a new tab.
+* +*-b*+, +*--bg*+: Open in a background tab.
 
 [[prev-page]]
 === prev-page
@@ -204,10 +200,10 @@ Syntax: +:prev-page [*--tab*]+
 
 Open a "previous" link.
 
-This tries to automaticall click on typical "Previous Page" links using some heuristics.
+This tries to automatically click on typical _Previous Page_ links using some heuristics.
 
 ==== optional arguments
-* +*-t*+, +*--tab*+: Whether to open a new tab.
+* +*-t*+, +*--tab*+: Open in a new tab.
 
 [[print]]
 === print
@@ -216,22 +212,16 @@ Syntax: +:print [*--preview*]+
 Print the current/[count]th tab.
 
 ==== optional arguments
-* +*-p*+, +*--preview*+: Whether to preview instead of printing.
+* +*-p*+, +*--preview*+: Show preview instead of printing.
-
-[[q]]
-=== q
-Syntax: +:quit+
-
-Quit qutebrowser.
 
 [[quickmark-add]]
 === quickmark-add
-Syntax: +:quickmark-add 'urlstr' 'name'+
+Syntax: +:quickmark-add 'url' 'name'+
 
 Add a new quickmark.
 
 ==== positional arguments
-* +'urlstr'+: The url to add as quickmark, as string.
+* +'url'+: The url to add as quickmark.
 * +'name'+: The name for the new quickmark.
 
 [[quickmark-load]]
@@ -244,8 +234,8 @@ Load a quickmark.
 * +'name'+: The name of the quickmark to load.
 
 ==== optional arguments
-* +*-t*+, +*--tab*+: Whether to load the quickmark in a new tab.
+* +*-t*+, +*--tab*+: Load the quickmark in a new tab.
-* +*-b*+, +*--bg*+: Whether to load the quickmark in the background.
+* +*-b*+, +*--bg*+: Load the quickmark in a new background tab.
 
 [[quickmark-save]]
 === quickmark-save
@@ -283,17 +273,17 @@ Save the config file.
 
 [[set]]
 === set
-Syntax: +:set [*--temp*] 'sectname' 'optname' 'value'+
+Syntax: +:set [*--temp*] 'section' 'option' 'value'+
 
 Set an option.
 
 ==== positional arguments
-* +'sectname'+: The section where the option is in.
+* +'section'+: The section where the option is in.
-* +'optname'+: The name of the option.
+* +'option'+: The name of the option.
 * +'value'+: The value to set.
 
 ==== optional arguments
-* +*-t*+, +*--temp*+: Set value temporarely.
+* +*-t*+, +*--temp*+: Set value temporarily.
 
 [[set-cmd-text]]
 === set-cmd-text
@@ -340,7 +330,8 @@ Syntax: +:tab-move ['direction']+
 Move the current tab.
 
 ==== positional arguments
-* +'direction'+: + or - for relative moving, none for absolute.
+* +'direction'+: `+` or `-` for relative moving, not given for absolute moving.
+
 
 [[tab-next]]
 === tab-next
@@ -361,8 +352,8 @@ Syntax: +:unbind 'key' ['mode']+
 Unbind a keychain.
 
 ==== positional arguments
-* +'key'+: The keychain or special key (inside <...>) to bind.
+* +'key'+: The keychain or special key (inside <...>) to unbind.
-* +'mode'+: A comma-separated list of modes to unbind the key in (default: normal mode).
+* +'mode'+: A comma-separated list of modes to unbind the key in (default: `normal`).
 
 
 [[undo]]
@@ -376,8 +367,8 @@ Syntax: +:yank [*--title*] [*--sel*]+
 Yank the current URL/title to the clipboard or primary selection.
 
 ==== optional arguments
-* +*-t*+, +*--title*+: Whether to yank the title instead of the URL.
+* +*-t*+, +*--title*+: Yank the title instead of the URL.
-* +*-s*+, +*--sel*+: True to use primary selection, False to use clipboard
+* +*-s*+, +*--sel*+: Use the primary selection instead of the clipboard.
 
 [[zoom]]
 === zoom
@@ -600,7 +591,7 @@ The percentage can be given either as argument or as count. If no percentage is
 * +'perc'+: Percentage to scroll.
 
 ==== optional arguments
-* +*-x*+, +*--horizontal*+: Whether to scroll horizontally.
+* +*-x*+, +*--horizontal*+: Scroll horizontally instead of vertically.
 
 [[search-next]]
 === search-next

qutebrowser/browser/commands.py

@@ -159,17 +159,17 @@ class CommandDispatcher:
 
     @cmdutils.register(instance='mainwindow.tabs.cmd', name='open',
                        split=False)
-    def openurl(self, urlstr, bg=False, tab=False, count=None):
+    def openurl(self, url, bg=False, tab=False, count=None):
         """Open a URL in the current/[count]th tab.
 
         Args:
-            urlstr: The URL to open, as string.
+            url: The URL to open.
-            bg: Whether to open in a background tab.
+            bg: Open in a new background tab.
-            tab: Whether to open in a tab.
+            tab: Open in a new tab.
             count: The tab index to open the URL in, or None.
         """
         try:
-            url = urlutils.fuzzy_url(urlstr)
+            url = urlutils.fuzzy_url(url)
         except urlutils.FuzzyUrlError as e:
             raise cmdexc.CommandError(e)
         if tab:
@@ -216,7 +216,7 @@ class CommandDispatcher:
         """Print the current/[count]th tab.
 
         Args:
-            preview: Whether to preview instead of printing.
+            preview: Show preview instead of printing.
             count: The tab index to print, or None.
         """
         if not qtutils.check_print_compat():
@@ -276,10 +276,6 @@ class CommandDispatcher:
                 - `yank-primary`: Yank the link to the primary selection.
                 - `fill`: Fill the commandline with the command given as
                           argument.
-                - `cmd-tab`: Fill the commandline with `:open -t` and the
-                             link.
-                - `cmd-tag-bg`: Fill the commandline with `:open -b` and
-                                the link.
                 - `rapid`: Open the link in a new tab and stay in hinting mode.
                 - `download`: Download the link.
                 - `userscript`: Call an userscript with `$QUTE_URL` set to the
@@ -312,11 +308,11 @@ class CommandDispatcher:
     def prev_page(self, tab=False):
         """Open a "previous" link.
 
-        This tries to automaticall click on typical "Previous Page" links using
+        This tries to automatically click on typical _Previous Page_ links
-        some heuristics.
+        using some heuristics.
 
         Args:
-            tab: Whether to open a new tab.
+            tab: Open in a new tab.
         """
         self._prevnext(prev=True, newtab=tab)
 
@@ -324,11 +320,11 @@ class CommandDispatcher:
     def next_page(self, tab=False):
         """Open a "next" link.
 
-        This tries to automatically click on typical "Next Page" links using
+        This tries to automatically click on typical _Next Page_ links using
         some heuristics.
 
         Args:
-            tab: Whether to open a new tab.
+            tab: Open in a new tab.
         """
         self._prevnext(prev=False, newtab=tab)
 
@@ -357,7 +353,7 @@ class CommandDispatcher:
 
         Args:
             perc: Percentage to scroll.
-            horizontal: Whether to scroll horizontally.
+            horizontal: Scroll horizontally instead of vertically.
             count: Percentage to scroll.
         """
         self._scroll_percent(perc, count,
@@ -385,8 +381,8 @@ class CommandDispatcher:
         """Yank the current URL/title to the clipboard or primary selection.
 
         Args:
-            sel: True to use primary selection, False to use clipboard
+            sel: Use the primary selection instead of the clipboard.
-            title: Whether to yank the title instead of the URL.
+            title: Yank the title instead of the URL.
         """
         clipboard = QApplication.clipboard()
         if title:
@@ -490,12 +486,13 @@ class CommandDispatcher:
             raise cmdexc.CommandError("Last tab")
 
     @cmdutils.register(instance='mainwindow.tabs.cmd')
-    def paste(self, sel=False, tab=False):
+    def paste(self, sel=False, tab=False, bg=False):
         """Open a page from the clipboard.
 
         Args:
-            sel: True to use primary selection, False to use clipboard
+            sel: Use the primary selection instead of the clipboard.
-            tab: True to open in a new tab.
+            tab: Open in a new tab.
+            bg: Open in a background tab.
         """
         clipboard = QApplication.clipboard()
         if sel and clipboard.supportsSelection():
@@ -513,7 +510,9 @@ class CommandDispatcher:
         except urlutils.FuzzyUrlError as e:
             raise cmdexc.CommandError(e)
         if tab:
-            self._tabs.tabopen(url, explicit=True)
+            self._tabs.tabopen(url, background=False, explicit=True)
+        elif bg:
+            self._tabs.tabopen(url, background=True, explicit=True)
         else:
             widget = self._current_widget()
             widget.openurl(url)
@@ -547,7 +546,8 @@ class CommandDispatcher:
         """Move the current tab.
 
         Args:
-            direction: + or - for relative moving, none for absolute.
+            direction: `+` or `-` for relative moving, not given for absolute
+                       moving.
             count: If moving absolutely: New position (default: 0)
                    If moving relatively: Offset.
         """
@@ -624,8 +624,8 @@ class CommandDispatcher:
 
         Args:
             name: The name of the quickmark to load.
-            tab: Whether to load the quickmark in a new tab.
+            tab: Load the quickmark in a new tab.
-            bg: Whether to load the quickmark in the background.
+            bg: Load the quickmark in a new background tab.
         """
         urlstr = quickmarks.get(name)
         url = QUrl(urlstr)

qutebrowser/browser/quickmarks.py

@@ -71,21 +71,21 @@ def prompt_save(url):
 
 
 @cmdutils.register()
-def quickmark_add(urlstr, name):
+def quickmark_add(url, name):
     """Add a new quickmark.
 
     Args:
-        urlstr: The url to add as quickmark, as string.
+        url: The url to add as quickmark.
         name: The name for the new quickmark.
     """
     if not name:
         raise cmdexc.CommandError("Can't set mark with empty name!")
-    if not urlstr:
+    if not url:
         raise cmdexc.CommandError("Can't set mark with empty URL!")
 
     def set_mark():
         """Really set the quickmark."""
-        marks[name] = urlstr
+        marks[name] = url
 
     if name in marks:
         message.confirm_async("Override existing quickmark?", set_mark,

qutebrowser/commands/cmdutils.py

@@ -31,6 +31,7 @@ from qutebrowser.utils import debug as debugutils
 from qutebrowser.commands import command, cmdexc, argparser
 
 cmd_dict = {}
+aliases = []
 
 
 def check_overflow(arg, ctype):
@@ -163,6 +164,7 @@ class register:  # pylint: disable=invalid-name
         Return:
             The original function (unmodified).
         """
+        global aliases, cmd_dict
         self.func = func
         names = self._get_names()
         log.commands.vdebug("Registering command {}".format(names[0]))
@@ -186,6 +188,7 @@ class register:  # pylint: disable=invalid-name
             opt_args=self.opt_args, pos_args=self.pos_args)
         for name in names:
             cmd_dict[name] = cmd
+        aliases += names[1:]
         return func
 
     def _get_names(self):

qutebrowser/config/config.py

@@ -283,7 +283,7 @@ class ConfigManager(QObject):
 
     @cmdutils.register(name='get', instance='config',
                        completion=[Completion.section, Completion.option])
-    def get_wrapper(self, sectname, optname):
+    def get_command(self, section, option):
         """Get the value from a section/option.
 
         //
@@ -291,16 +291,16 @@ class ConfigManager(QObject):
         Wrapper for the get-command to output the value in the status bar.
 
         Args:
-            sectname: The section where the option is in.
+            section: The section where the option is in.
-            optname: The name of the option.
+            option: The name of the option.
         """
         try:
-            val = self.get(sectname, optname, transformed=False)
+            val = self.get(section, option, transformed=False)
         except (NoOptionError, NoSectionError) as e:
             raise cmdexc.CommandError("get: {} - {}".format(
                 e.__class__.__name__, e))
         else:
-            message.info("{} {} = {}".format(sectname, optname, val),
+            message.info("{} {} = {}".format(section, option, val),
                          immediately=True)
 
     @functools.lru_cache()
@@ -336,7 +336,7 @@ class ConfigManager(QObject):
     @cmdutils.register(name='set', instance='config',
                        completion=[Completion.section, Completion.option,
                                    Completion.value])
-    def set_command(self, sectname, optname, value, temp=False):
+    def set_command(self, section, option, value, temp=False):
         """Set an option.
 
         //
@@ -344,13 +344,14 @@ class ConfigManager(QObject):
         Wrapper for self.set() to output exceptions in the status bar.
 
         Args:
-            sectname: The section where the option is in.
+            section: The section where the option is in.
-            optname: The name of the option.
+            option: The name of the option.
             value: The value to set.
-            temp: Set value temporarely.
+            temp: Set value temporarily.
         """
         try:
-            self.set('temp' if temp else 'conf', sectname, optname, value)
+            layer = 'temp' if temp else 'conf'
+            self.set(layer, section, option, value)
         except (NoOptionError, NoSectionError, configtypes.ValidationError,
                 ValueError) as e:
             raise cmdexc.CommandError("set: {} - {}".format(

qutebrowser/config/keyconfparser.py

@@ -124,10 +124,10 @@ class KeyConfigParser(QObject):
         """Bind a key to a command.
 
         Args:
-            key: The keychain or special key (inside <...>) to bind.
+            key: The keychain or special key (inside `<...>`) to bind.
             command: The command to execute.
             mode: A comma-separated list of modes to bind the key in
-                  (default: normal mode).
+                  (default: `normal`).
         """
         if mode is None:
             mode = 'normal'
@@ -149,9 +149,9 @@ class KeyConfigParser(QObject):
         """Unbind a keychain.
 
         Args:
-            key: The keychain or special key (inside <...>) to bind.
+            key: The keychain or special key (inside <...>) to unbind.
             mode: A comma-separated list of modes to unbind the key in
-                  (default: normal mode).
+                  (default: `normal`).
         """
         if mode is None:
             mode = 'normal'

qutebrowser/utils/utilcmds.py

@@ -19,6 +19,7 @@
 
 """Misc. utility commands exposed to the user."""
 
+import shlex
 import types
 import functools
 
@@ -41,12 +42,12 @@ def init():
 
 
 @cmdutils.register()
-def later(ms: int, *command: {'nargs': '+'}):
+def later(ms: int, command):
     """Execute a command after some time.
 
     Args:
         ms: How many milliseconds to wait.
-        command: The command/args to run.
+        command: The command to run.
     """
     timer = usertypes.Timer(name='later')
     timer.setSingleShot(True)
@@ -58,7 +59,10 @@ def later(ms: int, *command: {'nargs': '+'}):
         raise cmdexc.CommandError("Numeric argument is too large for internal "
                                   "int representation.")
     _timers.append(timer)
-    cmdline = ' '.join(command)
+    try:
+        cmdline = shlex.split(command)
+    except ValueError as e:
+        raise cmdexc.CommandError("Could not split command: {}".format(e))
     timer.timeout.connect(functools.partial(
         _commandrunner.run_safely, cmdline))
     timer.timeout.connect(lambda: _timers.remove(timer))

scripts/generate_doc.py

@@ -239,6 +239,8 @@ def generate_commands(filename):
         hidden_cmds = []
         debug_cmds = []
         for name, cmd in cmdutils.cmd_dict.items():
+            if name in cmdutils.aliases:
+                continue
             if cmd.hide:
                 hidden_cmds.append((name, cmd))
             elif cmd.debug: