Merge branch 'docs' of https://github.com/page-down/kitty

docs/glossary.rst

@@ -45,6 +45,7 @@ Environment variables
 ------------------------
 
 Variables that influence kitty behavior
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. envvar:: KITTY_CONFIG_DIRECTORY
 
@@ -68,7 +69,6 @@ Variables that influence kitty behavior
    The terminal editor (such as ``vi`` or ``nano``) kitty uses, when, for
    instance, opening :file:`kitty.conf` in response to :sc:`edit_config_file`.
 
-
 .. envvar:: EDITOR
 
    Same as :envvar:`VISUAL`. Used if :envvar:`VISUAL` is not set.
@@ -84,13 +84,24 @@ Variables that influence kitty behavior
    is possible for the autodiscovery to fail; the default Wayland XKB mappings
    are used in this case. See :pull:`3943` for details.
 
+.. envvar:: KITTY_CLONE_SOURCE_CODE
+
+   Set this to some shell code that will be executed in the cloned window with
+   :code:`eval` when :ref:`clone-in-kitty <clone_shell>` is used.
+
+.. envvar:: KITTY_CLONE_SOURCE_PATH
+
+   Set this to the path of a file that will be sourced in the cloned window when
+   :ref:`clone-in-kitty <clone_shell>` is used.
+
 
 Variables that kitty sets when running child programs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. envvar:: LANG
 
-   This is set only on macOS, and only if the country and language from the
+   This is only set on macOS. If the country and language from the macOS user
-   macOS user settings form a valid locale.
+   settings form an invalid locale, it will be set to :code:`en_US.UTF-8`.
 
 
 .. envvar:: KITTY_WINDOW_ID
@@ -137,7 +148,7 @@ Variables that kitty sets when running child programs
 
    Set when the :doc:`remote control <remote-control>` facility is enabled and
    the a socket is used for control via :option:`kitty --listen-on` or :opt:`listen_on`.
-   Contains the path to the socket. Avoids needs to use :option:`kitty @ --to` when
+   Contains the path to the socket. Avoid the need to use :option:`kitty @ --to` when
    issuing remote control commands.
 
 
@@ -158,7 +169,7 @@ Variables that kitty sets when running child programs
 .. envvar:: KITTY_COMMON_OPTS
 
    Set with the values of some common kitty options when running
-   kittens, so kittens can use them without needing to load kitty.conf.
+   kittens, so kittens can use them without needing to load :file:`kitty.conf`.
 
 
 .. envvar:: KITTY_SHELL_INTEGRATION

docs/shell-integration.rst

@@ -223,7 +223,7 @@ Clone the current shell into a new window
 -----------------------------------------------
 
 You can clone the current shell into a new kitty window by simply running the
-:code:`clone-in-kitty` command, for example:
+:command:`clone-in-kitty` command, for example:
 
 .. code-block:: sh
 
@@ -235,24 +235,27 @@ This will open a new window running a new shell instance but with all
 environment variables and the current working directory copied. This even
 works over SSH when using :doc:`kittens/ssh`.
 
-The :file:`clone-in-kitty` command takes almost all the same arguments as the
+The :command:`clone-in-kitty` command takes almost all the same arguments as the
 :doc:`launch <launch>` command, so you can open a new tab instead or a new OS
 window, etc. Arguments of launch that can cause code execution or that don't
-make sense when cloning are ignored. Most prominently, the following options
+make sense when cloning are ignored. Most prominently, the following options are
-are ignored: :option:`launch --allow-remote-control`, :option:`launch
+ignored: :option:`--allow-remote-control <launch --allow-remote-control>`,
---copy-cmdline`, :option:`launch --copy-env`, :option:`launch --stdin-source`,
+:option:`--copy-cmdline <launch --copy-cmdline>`, :option:`--copy-env <launch
-:option:`launch --marker` and :option:`launch --watcher`.
+--copy-env>`, :option:`--stdin-source <launch --stdin-source>`,
+:option:`--marker <launch --marker>` and :option:`--watcher <launch --watcher>`.
 
-:file:`clone-in-kitty` can be configured to source arbitrary code in the
+:command:`clone-in-kitty` can be configured to source arbitrary code in the
 cloned window using environment variables. It will automatically clone virtual
-environments created by the python venv module or conda. In addition, setting the
+environments created by the :link:`Python venv module
-env var :file:`KITTY_CLONE_SOURCE_PATH` to the path of a file will cause
+<https://docs.python.org/3/library/venv.html>` or :link:`Conda
-that file to be sourced in the cloned window. Similarly, setting
+<https://conda.io/>`. In addition, setting the
-:file:`KITTY_CLONE_SOURCE_CODE` to some shell code will cause that code to be
+env var :envvar:`KITTY_CLONE_SOURCE_CODE` to some shell code will cause that
-run in the cloned window with :code:`eval`. This can be controlled by
+code to be run in the cloned window with :code:`eval`. Similarly, setting
+:envvar:`KITTY_CLONE_SOURCE_PATH` to the path of a file will cause that file to
+be sourced in the cloned window. This can be controlled by
 :opt:`clone_source_strategies`.
 
-:file:`clone-in-kitty` works by asking the shell to serialize its internal
+:command:`clone-in-kitty` works by asking the shell to serialize its internal
 state (mainly CWD and env vars) and this state is transmitted to kitty and
 restored by the shell integration scripts in the cloned window.
 

kittens/hints/main.py

@@ -525,10 +525,10 @@ OPTIONS = r'''
 --program
 type=list
 What program to use to open matched text. Defaults to the default open program
-for the operating system. Use a value of :file:`-` to paste the match into the
+for the operating system. Use a value of :code:`-` to paste the match into the
-terminal window instead. A value of :file:`@` will copy the match to the
+terminal window instead. A value of :code:`@` will copy the match to the
-clipboard. A value of :file:`*` will copy the match to the primary selection
+clipboard. A value of :code:`*` will copy the match to the primary selection
-(on systems that support primary selections). A value of :file:`default` will
+(on systems that support primary selections). A value of :code:`default` will
 run the default open program. Can be specified multiple times to run multiple
 programs.
 
@@ -538,22 +538,22 @@ default=url
 choices=url,regex,path,line,hash,word,linenum,hyperlink,ip
 The type of text to search for. A value of :code:`linenum` is special, it looks
 for error messages using the pattern specified with :option:`--regex`, which
-must have the named groups, :code:`path` and :code:`line`. If not specified,
+must have the named groups: :code:`path` and :code:`line`. If not specified,
 will look for :code:`path:line`. The :option:`--linenum-action` option
 controls where to display the selected error message, other options are ignored.
 
 
 --regex
 default={default_regex}
-The regular expression to use when :option:`kitty +kitten hints --type`=regex.
+The regular expression to use when option :option:`--type` is set to
-The regular expression is in python syntax. If you specify a numbered group in
+:code:`regex`, in python syntax. If you specify a numbered group in the regular
-the regular expression only the group will be matched. This allow you to match
+expression, only the group will be matched. This allow you to match text
-text ignoring a prefix/suffix, as needed. The default expression matches lines.
+ignoring a prefix/suffix, as needed. The default expression matches lines. To
-To match text over multiple lines you should prefix the regular expression with
+match text over multiple lines, you should prefix the regular expression with
 :code:`(?ms)`, which turns on MULTILINE and DOTALL modes for the regex engine.
-If you specify named groups and a :option:`kitty +kitten hints --program` then
+If you specify named groups and a :option:`--program`, then the program will be
-the program will be passed arguments corresponding to each named group of
+passed arguments corresponding to each named group of the form
-the form key=value.
+:code:`key=value`.
 
 
 --linenum-action
@@ -565,22 +565,22 @@ window, :code:`window` a new kitty window, :code:`tab` a new tab,
 :code:`os_window` a new OS window and :code:`background` run in the background.
 The actual action is whatever arguments are provided to the kitten, for
 example:
-:code:`kitty + kitten hints --type=linenum --linenum-action=tab vim +{line} {path}`
+:code:`kitty +kitten hints --type=linenum --linenum-action=tab vim +{line} {path}`
 will open the matched path at the matched line number in vim in
-a new kitty tab. Note that only when using :code:`self` are the special values for
+a new kitty tab. Note that in order to use :option:`--program` to copy or paste
-:option:`kitty +kitten hints --program` to copy/paste the text respected.
+text, you need to use the special value :code:`self`.
 
 
 --url-prefixes
 default=default
-Comma separated list of recognized URL prefixes. Defaults, to
+Comma separated list of recognized URL prefixes. Defaults to the list of
-the list of prefixes defined in kitty.conf.
+prefixes defined by the :opt:`url_prefixes` option in :file:`kitty.conf`.
 
 
 --word-characters
 Characters to consider as part of a word. In addition, all characters marked as
-alphanumeric in the unicode database will be considered as word characters.
+alphanumeric in the Unicode database will be considered as word characters.
-Defaults to the select_by_word_characters setting from kitty.conf.
+Defaults to the :opt:`select_by_word_characters` option from :file:`kitty.conf`.
 
 
 --minimum-match-length
@@ -591,26 +591,26 @@ The minimum number of characters to consider a match.
 
 --multiple
 type=bool-set
-Select multiple matches and perform the action on all of them together at the end.
+Select multiple matches and perform the action on all of them together at the
-In this mode, press :kbd:`Esc` to finish selecting.
+end. In this mode, press :kbd:`Esc` to finish selecting.
 
 
 --multiple-joiner
 default=auto
-String to use to join multiple selections when copying to the clipboard or
+String for joining multiple selections when copying to the clipboard or
-inserting into the terminal. The special strings: "space", "newline", "empty",
+inserting into the terminal. The special values are: :code:`space` - a space
-"json" and "auto" are interpreted as a space character, a newline an empty
+character, :code:`newline` - a newline, :code:`empty` - an empty joiner,
-joiner, a JSON serialized list and an automatic choice, based on the type of
+:code:`json` - a JSON serialized list, :code:`auto` - an automatic choice, based
-text being selected. In addition, integers are interpreted as zero-based
+on the type of text being selected. In addition, integers are interpreted as
-indices into the list of selections. You can use 0 for the first selection and
+zero-based indices into the list of selections. You can use :code:`0` for the
--1 for the last.
+first selection and :code:`-1` for the last.
 
 
 --add-trailing-space
 default=auto
 choices=auto,always,never
-Add trailing space after matched text. Defaults to auto, which adds the space
+Add trailing space after matched text. Defaults to :code:`auto`, which adds the
-when used together with :option:`--multiple`.
+space when used together with :option:`--multiple`.
 
 
 --hints-offset
@@ -621,45 +621,47 @@ greater than or equal to zero are respected.
 
 
 --alphabet
-The list of characters to use for hints. The default is to use numbers and lowercase
+The list of characters to use for hints. The default is to use numbers and
-English alphabets. Specify your preference as a string of characters. Note that
+lowercase English alphabets. Specify your preference as a string of characters.
-unless you specify the hints offset as zero the first match will be highlighted with
+Note that you need to specify the :option:`--hints-offset` as zero to use the
-the second character you specify.
+first character to highlight the first match, otherwise it will start with the
+second character by default.
 
 
 --ascending
 type=bool-set
-Have the hints increase from top to bottom instead of decreasing from top to bottom.
+Make the hints increase from top to bottom, instead of decreasing from top to
+bottom.
 
 
 --hints-foreground-color
 default=black
 type=str
-The foreground color for hints
+The foreground color for hints.
 
 
 --hints-background-color
 default=green
 type=str
-The background color for hints
+The background color for hints.
 
 
 --hints-text-color
 default=gray
 type=str
-The foreground color for text pointed to by the hints
+The foreground color for text pointed to by the hints.
 
 
 --customize-processing
-Name of a python file in the kitty config directory which will be imported to provide
+Name of a python file in the kitty config directory which will be imported to
-custom implementations for pattern finding and performing actions
+provide custom implementations for pattern finding and performing actions
-on selected matches. See {hints_url}
+on selected matches. You can also specify absolute paths to load the script from
-for details. You can also specify absolute paths to load the script from elsewhere.
+elsewhere. See {hints_url} for details.
 
 
 --window-title
-The window title for the hints window, default title is selected based on
+The title for the hints window, default title is based on the type of text being
-the type of text being hinted.
+hinted.
 '''.format(
     default_regex=DEFAULT_REGEX,
     line='{{line}}', path='{{path}}',

kitty/cli.py

@@ -28,26 +28,27 @@ class OptionDict(TypedDict):
 
 CONFIG_HELP = '''\
 Specify a path to the configuration file(s) to use. All configuration files are
-merged onto the builtin {conf_name}.conf, overriding the builtin values. This option
+merged onto the builtin :file:`{conf_name}.conf`, overriding the builtin values.
-can be specified multiple times to read multiple configuration files in
+This option can be specified multiple times to read multiple configuration files
-sequence, which are merged. Use the special value NONE to not load a config
+in sequence, which are merged. Use the special value :code:`NONE` to not load
-file.
+any config file.
 
 If this option is not specified, config files are searched for in the order:
-:file:`$XDG_CONFIG_HOME/{appname}/{conf_name}.conf`, :file:`~/.config/{appname}/{conf_name}.conf`, {macos_confpath}
+:file:`$XDG_CONFIG_HOME/{appname}/{conf_name}.conf`,
-:file:`$XDG_CONFIG_DIRS/{appname}/{conf_name}.conf`. The first one that exists is used as the
+:file:`~/.config/{appname}/{conf_name}.conf`,{macos_confpath}
-config file.
+:file:`$XDG_CONFIG_DIRS/{appname}/{conf_name}.conf`. The first one that exists
+is used as the config file.
 
 If the environment variable :envvar:`KITTY_CONFIG_DIRECTORY` is specified, that
 directory is always used and the above searching does not happen.
 
-If :file:`/etc/xdg/{appname}/{conf_name}.conf` exists it is merged before (i.e. with lower
+If :file:`/etc/xdg/{appname}/{conf_name}.conf` exists, it is merged before (i.e.
-priority) than any user config files. It can be used to specify system-wide
+with lower priority) than any user config files. It can be used to specify
-defaults for all users. You can use either :code:`-` or :code:`/dev/stdin` to read the
+system-wide defaults for all users. You can use either :code:`-` or
-config from STDIN.
+:file:`/dev/stdin` to read the config from STDIN.
 '''.replace(
     '{macos_confpath}',
-    (':file:`~/Library/Preferences/{appname}/{conf_name}.conf`,' if is_macos else ''), 1
+    (' :file:`~/Library/Preferences/{appname}/{conf_name}.conf`,' if is_macos else ''), 1
 )
 
 
@@ -294,9 +295,10 @@ def get_defaults_from_seq(seq: OptionSpecSeq) -> Dict[str, Any]:
 
 
 default_msg = ('''\
-Run the :italic:`{appname}` terminal emulator. You can also specify the :italic:`program`
+Run the :italic:`{appname}` terminal emulator. You can also specify the
-to run inside :italic:`{appname}` as normal arguments following the :italic:`options`.
+:italic:`program` to run inside :italic:`{appname}` as normal arguments
-For example: {appname} sh -c "echo hello, world. Press ENTER to quit; read"
+following the :italic:`options`.
+For example: {appname} --hold sh -c "echo hello, world"
 
 For comprehensive documentation for kitty, please see: {url}''').format(
     appname=appname, url=website_url())
@@ -583,17 +585,20 @@ def options_spec() -> str:
 dest=cls
 default={appname}
 condition=not is_macos
-Set the class part of the :italic:`WM_CLASS` window property. On Wayland, it sets the app id.
+Set the class part of the :italic:`WM_CLASS` window property. On Wayland, it
+sets the app id.
 
 
 --name
 condition=not is_macos
-Set the name part of the :italic:`WM_CLASS` property (defaults to using the value from :option:`{appname} --class`)
+Set the name part of the :italic:`WM_CLASS` property. Defaults to using the
+value from :option:`{appname} --class`.
 
 
 --title -T
-Set the OS window title. This will override any title set by the program running inside kitty, permanently
+Set the OS window title. This will override any title set by the program running
-fixing the OS Window's title. So only use this if you are running a program that does not set titles.
+inside kitty, permanently fixing the OS window's title. So only use this if you
+are running a program that does not set titles.
 
 
 --config -c
@@ -604,68 +609,74 @@ type=list
 --override -o
 type=list
 Override individual configuration options, can be specified multiple times.
-Syntax: :italic:`name=value`. For example: :option:`kitty -o` font_size=20
+Syntax: :italic:`name=value`. For example: :option:`{appname} -o` font_size=20
 
 
 --directory --working-directory -d
 default=.
-Change to the specified directory when launching
+Change to the specified directory when launching.
 
 
 --detach
 type=bool-set
 condition=not is_macos
-Detach from the controlling terminal, if any
+Detach from the controlling terminal, if any.
 
 
 --session
-Path to a file containing the startup :italic:`session` (tabs, windows, layout, programs).
+Path to a file containing the startup :italic:`session` (tabs, windows, layout,
-Use - to read from STDIN. See the README file for details and an example.
+programs). Use - to read from STDIN. See the :file:`README` file for details and
+an example.
 
 
 --hold
 type=bool-set
 Remain open after child process exits. Note that this only affects the first
-window. You can quit by either using the close window shortcut or pressing any key.
+window. You can quit by either using the close window shortcut or pressing any
+key.
 
 
 --single-instance -1
 type=bool-set
-If specified only a single instance of :italic:`{appname}` will run. New invocations will
+If specified only a single instance of :italic:`{appname}` will run. New
-instead create a new top-level window in the existing :italic:`{appname}` instance. This
+invocations will instead create a new top-level window in the existing
-allows :italic:`{appname}` to share a single sprite cache on the GPU and also reduces
+:italic:`{appname}` instance. This allows :italic:`{appname}` to share a single
-startup time. You can also have separate groups of :italic:`{appname}` instances by using the
+sprite cache on the GPU and also reduces startup time. You can also have
-:option:`kitty --instance-group` option
+separate groups of :italic:`{appname}` instances by using the :option:`{appname}
+--instance-group` option.
 
 
 --instance-group
-Used in combination with the :option:`kitty --single-instance` option. All :italic:`{appname}` invocations
+Used in combination with the :option:`{appname} --single-instance` option. All
-with the same :option:`kitty --instance-group` will result in new windows being created
+:italic:`{appname}` invocations with the same :option:`{appname}
-in the first :italic:`{appname}` instance within that group
+--instance-group` will result in new windows being created in the first
+:italic:`{appname}` instance within that group.
 
 
 --wait-for-single-instance-window-close
 type=bool-set
-Normally, when using :option:`--single-instance`, :italic:`{appname}` will open a new window in an existing
+Normally, when using :option:`{appname} --single-instance`, :italic:`{appname}`
-instance and quit immediately. With this option, it will not quit till the newly opened
+will open a new window in an existing instance and quit immediately. With this
-window is closed. Note that if no previous instance is found, then :italic:`{appname}` will wait anyway,
+option, it will not quit till the newly opened window is closed. Note that if no
+previous instance is found, then :italic:`{appname}` will wait anyway,
 regardless of this option.
 
 
 --listen-on
-Tell kitty to listen on the specified address for control
+Listen on the specified socket address for control messages. For example,
-messages. For example, :option:`{appname} --listen-on`=unix:/tmp/mykitty or
+:option:`{appname} --listen-on`=unix:/tmp/mykitty or
 :option:`{appname} --listen-on`=tcp:localhost:12345. On Linux systems, you can
 also use abstract UNIX sockets, not associated with a file, like this:
-:option:`{appname} --listen-on`=unix:@mykitty. Environment variables
+:option:`{appname} --listen-on`=unix:@mykitty. Environment variables are
-in the setting are expanded and relative paths are resolved with
+expanded and relative paths are resolved with respect to the temporary
-respect to the temporary directory. To control kitty, you can send
+directory. To control kitty, you can send commands to it with
-it commands with :italic:`kitty @` using the :option:`kitty @ --to` option to
+:italic:`{appname} @` using the :option:`{appname} @ --to` option to specify
-specify this address. This option will be ignored, unless you set
+this address. Unless you enabled :opt:`allow_remote_control` in
-:opt:`allow_remote_control` to yes in :file:`kitty.conf`. Note that if you run
+:file:`{conf_name}.conf`, this option will be ignored. Note that if you run
-:italic:`kitty @` within a kitty window, there is no need to specify the :option:`kitty @ --to`
+:italic:`{appname} @` within a kitty window, there is
-option as it is read automatically from the environment. For UNIX sockets, this
+no need to specify the :option:`{appname} @ --to` option as it will
-can also be specified in :file:`kitty.conf`.
+automatically read from the environment. For UNIX sockets, this can also be
+specified in :file:`{conf_name}.conf`.
 
 
 --start-as
@@ -679,45 +690,48 @@ Control how the initial kitty window is created.
 
 --version -v
 type=bool-set
-The current {appname} version
+The current {appname} version.
 
 
 --dump-commands
 type=bool-set
-Output commands received from child process to stdout
+Output commands received from child process to STDOUT.
 
 
 --replay-commands
-Replay previously dumped commands. Specify the path to a dump file previously created by :option:`kitty --dump-commands`. You
+Replay previously dumped commands. Specify the path to a dump file previously
+created by :option:`{appname} --dump-commands`. You
 can open a new kitty window to replay the commands with::
 
-    kitty sh -c "kitty --replay-commands /path/to/dump/file; read"
+    {appname} --hold {appname} --replay-commands /path/to/dump/file
 
 
 --dump-bytes
-Path to file in which to store the raw bytes received from the child process
+Path to file in which to store the raw bytes received from the child process.
 
 
 --debug-rendering --debug-gl
 type=bool-set
 Debug rendering commands. This will cause all OpenGL calls to check for errors
 instead of ignoring them. Also prints out miscellaneous debug information.
-Useful when debugging rendering problems
+Useful when debugging rendering problems.
 
 
 --debug-input --debug-keyboard
 dest=debug_keyboard
 type=bool-set
-This option will cause kitty to print out key and mouse events as they are received
+Print out key and mouse events as they are received.
 
 
 --debug-font-fallback
 type=bool-set
-Print out information about the selection of fallback fonts for characters not present in the main font.
+Print out information about the selection of fallback fonts for characters not
+present in the main font.
 
 
 --watcher
-This option is deprecated in favor of the :opt:`watcher` option in kitty.conf and should not be used.
+This option is deprecated in favor of the :opt:`watcher` option in
+:file:`{conf_name}.conf` and should not be used.
 
 
 --execute -e
@@ -725,7 +739,8 @@ type=bool-set
 !
 '''
         setattr(options_spec, 'ans', OPTIONS.format(
-            appname=appname, config_help=CONFIG_HELP.format(appname=appname, conf_name=appname),
+            appname=appname, conf_name=appname,
+            config_help=CONFIG_HELP.format(appname=appname, conf_name=appname),
         ))
     ans: str = getattr(options_spec, 'ans')
     return ans
@@ -769,7 +784,7 @@ def parse_args(
     return ans, parse_cmdline(oc, disabled, ans, args=args)
 
 
-SYSTEM_CONF = '/etc/xdg/kitty/kitty.conf'
+SYSTEM_CONF = f'/etc/xdg/{appname}/{appname}.conf'
 
 
 def create_opts(args: CLIOptions, accumulate_bad_lines: Optional[List[BadLineType]] = None) -> KittyOpts:

kitty/conf/types.py

@@ -55,6 +55,7 @@ def ref_map() -> Dict[str, str]:
         'functional': f'{website_url("keyboard-protocol")}#functional-key-definitions',
         'ssh_copy_command': f'{website_url("kittens/ssh")}#ssh-copy-command',
         'shell_integration': website_url("shell-integration"),
+        'clone_shell': f'{website_url("shell-integration")}#clone-shell',
         'github_discussions': 'https://github.com/kovidgoyal/kitty/discussions',
     }
     for actions in get_all_actions().values():
@@ -65,17 +66,30 @@ def ref_map() -> Dict[str, str]:
 
 def remove_markup(text: str) -> str:
 
+    def extract(m: 'Match[str]') -> Tuple[str, str]:
+        parts = m.group(2).split('<')
+        t = parts[0].strip()
+        q = parts[-1].rstrip('>')
+        return t, q
+
     def sub(m: 'Match[str]') -> str:
         if m.group(1) == 'ref':
-            q = m.group(2).split('<')[-1].rstrip('>')
+            t, q = extract(m)
-            return ref_map()[q]
+            return f'{t} <{ref_map()[q]}>'
+        if m.group(1) == 'doc':
+            t, q = extract(m)
+            return f'{t} <{website_url(q.lstrip("/"))}>'
         if m.group(1) == 'ac':
             q = m.group(2).split('<')[-1].rstrip('>')
-            return ref_map()[f'action-{q}']
+            return q
+        if m.group(1) == 'term':
+            t, _ = extract(m)
+            return t
+        if m.group(1) == 'option':
+            t, _ = extract(m)
+            return t
         if m.group(1) == 'disc':
-            parts = m.group(2).split('<')
+            t, q = extract(m)
-            t = parts[0].strip()
-            q = parts[-1].rstrip('>')
             return f'{t} {ref_map()["github_discussions"]}/{q}'
         return str(m.group(2))