Use rst roles to format cli help text

docs/_static/custom.css

@@ -92,6 +92,10 @@ div.sphinxsidebar {
     color: blue;
 }
 
+.env {
+    font-style: italic;
+}
+
 .italic {
     font-style: italic;
 }

docs/conf.py

@@ -91,6 +91,7 @@ rst_prolog = '''
 .. role:: bold
 .. role:: cyan
 .. role:: title
+.. role:: env
 
 ''' + create_shortcut_defs()
 

docs/conf.rst

@@ -18,6 +18,6 @@ You can also display the current configuration by running ``kitty
 |kitty| looks for a config file in the OS config directories (usually
 :file:`~/.config/kitty/kitty.conf` and additionally
 :file:`~/Library/Preferences/kitty/kitty.conf` on macOS) but you can pass a
-specific path via the ``--config`` option or use the ``KITTY_CONFIG_DIRECTORY``
+specific path via the :option:`kitty --config` option or use the ``KITTY_CONFIG_DIRECTORY``
-environment variable. See the help for the :option:`--config` option in ``kitty
+environment variable. See the :option:`kitty --config` option 
---help`` for full details. 
+for full details. 

docs/remote-control.rst

@@ -102,7 +102,7 @@ instance of |kitty| using the :option:`--to` command line argument to ``kitty @`
 
 
 Note that is all you want to do is run a single |kitty| "daemon" and have subsequent
-|kitty| invocations appear as new top-level windows, you can use the simpler :option:`--single-instance`
+|kitty| invocations appear as new top-level windows, you can use the simpler :option:`kitty --single-instance`
 option, see ``kitty --help`` for that.
 
 The builtin kitty shell

kittens/diff/main.py

@@ -372,7 +372,7 @@ type=list
 --override -o
 type=list
 Override individual configuration options, can be specified multiple times.
-Syntax: |_ name=value|. For example: |_ -o background=gray|
+Syntax: :italic:`name=value`. For example: :italic:`-o background=gray`
 
 '''.format, config_help=CONFIG_HELP.format(conf_name='diff', appname=appname))
 

kittens/icat/main.py

@@ -34,14 +34,14 @@ Horizontal alignment for the displayed image.
 --place
 Choose where on the screen to display the image. The image will
 be scaled to fit into the specified rectangle. The syntax for
-specifying rectanges is <|_ width|>x<|_ height|>@<|_ left|>x<|_ top|>. All measurements
+specifying rectanges is <:italic:`width`>x<:italic:`height`>@<:italic:`left`>x<:italic:`top`>. All measurements
-are in cells (i.e. cursor positions) with the origin |_ (0, 0)| at
+are in cells (i.e. cursor positions) with the origin :italic:`(0, 0)` at
 the top-left corner of the screen.
 
 
 --scale-up
 type=bool-set
-When used in combination with |_ --place| it will cause images that
+When used in combination with :option:`--place` it will cause images that
 are smaller than the specified area to be scaled up to use as much
 of the specified area as possible.
 
@@ -56,8 +56,8 @@ type=choices
 choices=detect,file,stream
 default=detect
 Which mechanism to use to transfer images to the terminal. The default is to
-auto-detect. |_ file| means to use a temporary file and |_ stream| means to
+auto-detect. :italic:`file` means to use a temporary file and :italic:`stream` means to
-send the data via terminal escape codes. Note that if you use the |_ file|
+send the data via terminal escape codes. Note that if you use the :italic:`file`
 transfer mode and you are connecting over a remote session then image display
 will not work.
 
@@ -66,7 +66,7 @@ will not work.
 type=bool-set
 Detect support for image display in the terminal. If not supported, will exit
 with exit code 1, otherwise will exit with code 0 and print the supported
-transfer mode to stderr, which can be used with the |_ --transfer-mode| option.
+transfer mode to stderr, which can be used with the :option:`--transfer-mode` option.
 
 
 --detection-timeout
@@ -78,7 +78,7 @@ detecting image display support.
 
 --print-window-size
 type=bool-set
-Print out the window size as |_ widthxheight| (in pixels) and quit. This is a
+Print out the window size as :italic:`widthxheight` (in pixels) and quit. This is a
 convenience method to query the window size if using kitty icat from a
 scripting language that cannot make termios calls.
 '''

kitty/cli.py

@@ -19,29 +19,29 @@ sequence, which are merged. Use the special value NONE to not load a config
 file.
 
 If this option is not specified, config files are searched for in the order:
-"$XDG_CONFIG_HOME/{appname}/{conf_name}.conf", "~/.config/{appname}/{conf_name}.conf", {macos_confpath}
+:file:`$XDG_CONFIG_HOME/{appname}/{conf_name}.conf`, :file:`~/.config/{appname}/{conf_name}.conf`, {macos_confpath}
-"$XDG_CONFIG_DIRS/{appname}/{conf_name}.conf". The first one that exists is used as the
+:file:`$XDG_CONFIG_DIRS/{appname}/{conf_name}.conf`. The first one that exists is used as the
 config file.
 
-If the environment variable "KITTY_CONFIG_DIRECTORY" is specified, that
+If the environment variable :env:`KITTY_CONFIG_DIRECTORY` is specified, that
 directory is always used and the above searching does not happen.
 
-If "/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. with lower
 priority) than any user config files. It can be used to specify system-wide
 defaults for all users.
-'''.replace('{macos_confpath}', '~/Library/Preferences/{appname}/{conf_name}.conf, ' if is_macos else '')
+'''.replace('{macos_confpath}', ':file:`~/Library/Preferences/{appname}/{conf_name}.conf`,' if is_macos else '')
 
 OPTIONS = '''
 --class
 dest=cls
 default={appname}
 condition=not is_macos
-Set the class part of the |_ WM_CLASS| window property
+Set the class part of the :italic:`WM_CLASS` window property
 
 
 --name
 condition=not is_macos
-Set the name part of the |_ WM_CLASS| property (defaults to using the value from |_ --class|)
+Set the name part of the :italic:`WM_CLASS` property (defaults to using the value from :option:`{appname} --class`)
 
 
 --title
@@ -56,7 +56,7 @@ type=list
 --override -o
 type=list
 Override individual configuration options, can be specified multiple times.
-Syntax: |_ name=value|. For example: |_ -o font_size=20|
+Syntax: :italic:`name=value`. For example: :option:`kitty -o` font_size=20
 
 
 --directory -d
@@ -71,33 +71,33 @@ Detach from the controlling terminal, if any
 
 
 --session
-Path to a file containing the startup |_ session| (tabs, windows, layout, programs).
+Path to a file containing the startup :italic:`session` (tabs, windows, layout, programs).
 See the README file for details and an example.
 
 
 --single-instance -1
 type=bool-set
-If specified only a single instance of |_ {appname}| will run. New invocations will
+If specified only a single instance of :italic:`{appname}` will run. New invocations will
-instead create a new top-level window in the existing |_ {appname}| instance. This
+instead create a new top-level window in the existing :italic:`{appname}` instance. This
-allows |_ {appname}| to share a single sprite cache on the GPU and also reduces
+allows :italic:`{appname}` to share a single sprite cache on the GPU and also reduces
-startup time. You can also have separate groups of |_ {appname}| instances by using the
+startup time. You can also have separate groups of :italic:`{appname}` instances by using the
-|_ --instance-group| option
+:option:`kitty --instance-group` option
 
 
 --instance-group
-Used in combination with the |_ --single-instance| option. All |_ {appname}| invocations
+Used in combination with the :option:`kitty --single-instance` option. All :italic:`{appname}` invocations
-with the same |_ --instance-group| will result in new windows being created
+with the same :option:`kitty --instance-group` will result in new windows being created
-in the first |_ {appname}| instance within that group
+in the first :italic:`{appname}` instance within that group
 
 
 --listen-on
 Tell kitty to listen on the specified address for control
-messages. For example, |_ --listen-on=unix:/tmp/mykitty| or
+messages. For example, :option:`{appname} --listen-on` unix:/tmp/mykitty or
-|_ --listen-on=tcp:localhost:12345|. On Linux systems, you can also use abstract
+:option:`{appname} --listen-on` tcp:localhost:12345. On Linux systems, you can also use abstract
-UNIX sockets, not associated with a file, like this: |_ --listen-on=unix:@mykitty|.
+UNIX sockets, not associated with a file, like this: :option:`{appname} --listen-on` unix:@mykitty.
-To control kitty, you can send it commands with |_ kitty @| using the |_ --to| option
+To control kitty, you can send it commands with :italic:`kitty @` using the :option:`kitty @ --to` option
 to specify this address. Note that this option will be ignored, unless you set
-|_ allow_remote_control| to yes in |_ kitty.conf|
+:italic:`allow_remote_control` to yes in |kitty.conf|.
 
 
 # Debugging options
@@ -114,7 +114,7 @@ Output commands received from child process to stdout
 
 --replay-commands
 Replay previously dumped commands. Specify the path to a dump file previously created by --dump-commands. You
-can open a new kitty window to replay the commands with:
+can open a new kitty window to replay the commands with::
 
     kitty sh -c "kitty --replay-commands /path/to/dump/file; read"
 
@@ -125,7 +125,8 @@ Path to file in which to store the raw bytes received from the child process
 
 --debug-gl
 type=bool-set
-Debug OpenGL commands. This will cause all OpenGL calls to check for errors instead of ignoring them. Useful when debugging rendering problems
+Debug OpenGL commands. This will cause all OpenGL calls to check for errors
+instead of ignoring them. Useful when debugging rendering problems
 
 
 --debug-font-fallback
@@ -182,6 +183,19 @@ def title(x):
     return blue(bold(x))
 
 
+def option(x):
+    parts = map(bold, x.split())
+    return ' '.join(parts)
+
+
+def env(x):
+    return italic(x)
+
+
+def file(x):
+    return italic(x)
+
+
 def parse_option_spec(spec=OPTIONS):
     NORMAL, METADATA, HELP = 'NORMAL', 'METADATA', 'HELP'
     state = NORMAL
@@ -193,7 +207,7 @@ def parse_option_spec(spec=OPTIONS):
     current_cmd = None
 
     for line in lines:
-        line = line.strip()
+        line = line.rstrip()
         if state is NORMAL:
             if not line:
                 continue
@@ -220,10 +234,11 @@ def parse_option_spec(spec=OPTIONS):
                     current_cmd['choices'] = {x.strip() for x in current_cmd['choices'].split(',')}
         elif state is HELP:
             if line:
-                current_cmd['help'] += ' ' + line.lstrip()
+                spc = '' if current_cmd['help'].endswith('\n') else ' '
+                current_cmd['help'] += spc + line
             else:
                 if prev_line:
-                    current_cmd['help'] += '\n\n\t'
+                    current_cmd['help'] += '\n\n'
                 else:
                     state = NORMAL
                     (seq if current_cmd.get('condition', True) else disabled).append(current_cmd)
@@ -236,33 +251,17 @@ def parse_option_spec(spec=OPTIONS):
 
 
 def prettify(text):
+    role_map = globals()
 
     def sub(m):
-        t = m.group(2)
+        role, text = m.group(1, 2)
-        for ch in m.group(1):
+        return role_map[role](text)
-            t = {'C': cyan, '_': italic, '*': bold, 'G': green, 'T': title}[ch](t)
-        return t
 
-    text = re.sub(r'[|]([a-zA-Z_*]+?) (.+?)[|]', sub, text)
+    text = re.sub(r':([a-z]+):`([^`]+)`', sub, text)
-    return text
+    return text.replace('|kitty.conf|', italic('kitty.conf'))
 
 
 def prettify_rst(text):
-
-    def roled(role):
-        def f(x):
-            if x.startswith(':'):
-                return x
-            return ':{}:`{}`'.format(role, x.replace('`', r'\`'))
-        return f
-
-    def sub(m):
-        t = m.group(2)
-        for ch in m.group(1):
-            t = {'C': roled('cyan'), '_': roled('italic'), '*': roled('bold'), 'G': roled('green'), 'T': roled('title')}[ch](t)
-        return t
-
-    text = re.sub(r'[|]([a-zA-Z_*]+?) (.+?)[|]', sub, text)
     return text
 
 
@@ -307,6 +306,12 @@ def wrap(text, limit=80):
     return reversed(lines)
 
 
+default_msg = (
+        'Run the :italic:`{appname}` terminal emulator. You can also specify the :italic:`program` to run inside :italic:`{appname}` as normal'
+        ' arguments following the :italic:`options`. For example: {appname} /bin/sh'
+    ).format(appname=appname)
+
+
 def print_help_for_seq(seq, usage, message, appname):
     from kitty.utils import screen_size_function
     screen_size = screen_size_function()
@@ -333,10 +338,7 @@ def print_help_for_seq(seq, usage, message, appname):
     optstring = '[options] ' if seq else ''
     a('{}: {} {}{}'.format(title('Usage'), bold(yellow(appname)), optstring, usage))
     a('')
-    message = message or (
+    message = message or default_msg
-        'Run the |G {appname}| terminal emulator. You can also specify the |_ program| to run inside |_ {appname}| as normal'
-        ' arguments following the |_ options|. For example: {appname} /bin/sh'
-    ).format(appname=appname)
     wa(prettify(message))
     a('')
     if seq:
@@ -386,10 +388,7 @@ def seq_as_rst(seq, usage, message, appname):
     a('')
     a('  {} {}{}'.format(appname, optstring, usage))
     a('')
-    message = message or (
+    message = message or default_msg
-        'Run the |G {appname}| terminal emulator. You can also specify the |_ program| to run inside |_ {appname}| as normal'
-        ' arguments following the |_ options|. For example: {appname} /bin/sh'
-    ).format(appname=appname)
     a(prettify_rst(message))
     a('')
     if seq:
@@ -413,11 +412,6 @@ def seq_as_rst(seq, usage, message, appname):
             defval = opt.get('default')
             t = help_text.replace('%default', str(defval)).strip()
             a('')
-            t = re.sub(r':$', '::', t, flags=re.MULTILINE)
-            t = t.replace('::\n\n\t ', '::\n    \n        ')
-            t = t.replace('\n\n\t ', '\n    \n')
-            t = re.sub(r'(--[a-zA-Z0-9-]+)', r':option:`{} \1` '.format(appname), t)
-            t = re.sub('"(.+?)"', r'``\1``', t)
             a(textwrap.indent(prettify_rst(t), ' ' * 4))
             if defval is not None:
                 a(textwrap.indent('Default: {}'.format(defval), ' ' * 4))

kitty/cmds.py

@@ -46,19 +46,19 @@ def cmd(short_desc, desc=None, options_spec=None, no_response=False, argspec='..
 MATCH_WINDOW_OPTION = '''\
 --match -m
 The window to match. Match specifications are of the form:
-|_ field:regexp|. Where field can be one of: id, title, pid, cwd, cmdline, num.
+:italic:`field:regexp`. Where field can be one of: id, title, pid, cwd, cmdline, num.
-You can use the |_ ls| command to get a list of windows. Note that for
+You can use the :italic:`ls` command to get a list of windows. Note that for
 numeric fields such as id, pid and num the expression is interpreted as a number,
 not a regular expression. The field num refers to the window position in the current tab,
 starting from zero and counting clockwise (this is the same as the order in which the
-windows are reported by the |_ ls| command). The window id of the current window
+windows are reported by the :italic:`ls` command). The window id of the current window
 is available as the KITTY_WINDOW_ID environment variable.
 '''
 MATCH_TAB_OPTION = '''\
 --match -m
 The tab to match. Match specifications are of the form:
-|_ field:regexp|. Where field can be one of: id, title, pid, cwd, cmdline.
+:italic:`field:regexp`. Where field can be one of: id, title, pid, cwd, cmdline.
-You can use the |_ ls| command to get a list of tabs. Note that for
+You can use the :italic:`ls` command to get a list of tabs. Note that for
 numeric fields such as id and pid the expression is interpreted as a number,
 not a regular expression. When using title or id, first a matching tab is
 looked for and if not found a matching window is looked for, and the tab
@@ -70,10 +70,10 @@ for that window is used.
 @cmd(
     'List all tabs/windows',
     'List all windows. The list is returned as JSON tree. The top-level is a list of'
-    ' operating system {appname} windows. Each OS window has an |_ id| and a list'
+    ' operating system {appname} windows. Each OS window has an :italic:`id` and a list'
-    ' of |_ tabs|. Each tab has its own |_ id|, a |_ title| and a list of |_ windows|.'
+    ' of :italic:`tabs`. Each tab has its own :italic:`id`, a :italic:`title` and a list of :italic:`windows`.'
-    ' Each window has an |_ id|, |_ title|, |_ current working directory|, |_ process id (PID)| and'
+    ' Each window has an :italic:`id`, :italic:`title`, :italic:`current working directory`, :italic:`process id (PID)` and'
-    ' |_ command-line| of the process running in the window.\n\n'
+    ' :italic:`command-line` of the process running in the window.\n\n'
     'You can use these criteria to select windows/tabs for the other commands.'.format(appname=appname),
     argspec=''
 )
@@ -110,14 +110,14 @@ def set_font_size(boss, window, payload):
 @cmd(
     'Send arbitrary text to specified windows',
     'Send arbitrary text to specified windows. The text follows Python'
-    ' escaping rules. So you can use escapes like |_ \\x1b| to send control codes'
+    ' escaping rules. So you can use escapes like :italic:`\\x1b` to send control codes'
-    ' and |_ \\u21fa| to send unicode characters. If you use the |_ --match| option'
+    ' and :italic:`\\u21fa` to send unicode characters. If you use the :option:`kitty @ send-text --match` option'
     ' the text will be sent to all matched windows. By default, text is sent to'
     ' only the currently active window.',
     options_spec=MATCH_WINDOW_OPTION + '''\n
 --stdin
 type=bool-set
-Read the text to be sent from |_ stdin|. Note that in this case the text is sent as is,
+Read the text to be sent from :italic:`stdin`. Note that in this case the text is sent as is,
 not interpreted for escapes. If stdin is a terminal, you can press Ctrl-D to end reading.
 
 
@@ -202,7 +202,7 @@ def send_text(boss, window, payload):
 # set_window_title {{{
 @cmd(
     'Set the window title',
-    'Set the title for the specified window(s). If you use the |_ --match| option'
+    'Set the title for the specified window(s). If you use the :option:`kitty @ set-window-title --match` option'
     ' the title will be set for all matched windows. By default, only the window'
     ' in which the command is run is affected. If you do not specify a title, the'
     ' last title set by the child process running in the window will be used.',
@@ -229,7 +229,7 @@ def set_window_title(boss, window, payload):
 # set_tab_title {{{
 @cmd(
     'Set the tab title',
-    'Set the title for the specified tab(s). If you use the |_ --match| option'
+    'Set the title for the specified tab(s). If you use the :option:`kitty @ set-tab-title --match` option'
     ' the title will be set for all matched tabs. By default, only the tab'
     ' in which the command is run is affected. If you do not specify a title, the'
     ' title of the currently active window in the tab is used.',
@@ -297,8 +297,8 @@ The number of cells to change the size by, can be negative to decrease the size.
 type=choices
 choices=horizontal,vertical,reset
 default=horizontal
-The axis along which to resize. If |_ horizontal|, it will make the window wider or narrower by the specified increment.
+The axis along which to resize. If :italic:`horizontal`, it will make the window wider or narrower by the specified increment.
-If |_ vertical|, it will make the window taller or shorter by the specified increment. The special value |_ reset| will
+If :italic:`vertical`, it will make the window taller or shorter by the specified increment. The special value :italic:`reset` will
 reset the layout to its default configuration.
 
 
@@ -363,12 +363,12 @@ def close_tab(boss, window, payload):
 # new_window {{{
 @cmd(
     'Open new window',
-    'Open a new window in the specified tab. If you use the |_ --match| option'
+    'Open a new window in the specified tab. If you use the :option:`kitty @ new-window --match` option'
     ' the first matching tab is used. Otherwise the currently active tab is used.'
     ' Prints out the id of the newly opened window. Any command line arguments'
     ' are assumed to be the command line used to run in the new window, if none'
     ' are provided, the default shell is run. For example:\n'
-    '|_ kitty @ new-window --title Email mutt|',
+    ':italic:`kitty @ new-window --title Email mutt`',
     options_spec=MATCH_TAB_OPTION + '''\n
 --title
 The title for the new window. By default it will use the title set by the

kitty/remote_control.py

@@ -87,13 +87,13 @@ all_commands = tuple(sorted(cmap))
 
 
 def parse_rc_args(args):
-    cmds = ('  |G {}|\n    {}'.format(cmap[c].name, cmap[c].short_desc) for c in all_commands)
+    cmds = ('  :green:`{}`\n    {}'.format(cmap[c].name, cmap[c].short_desc) for c in all_commands)
     msg = (
         'Control {appname} by sending it commands. Add'
-        ' |_ allow_remote_control yes| to kitty.conf for this'
+        ' :italic:`allow_remote_control yes` to |kitty.conf| for this'
-        ' to work.\n\n|T Commands|:\n{cmds}\n\n'
+        ' to work.\n\n:title:`Commands`:\n{cmds}\n\n'
         'You can get help for each individual command by using:\n'
-        '{appname} @ |_ command| -h'
+        '{appname} @ :italic:`command` -h'
     ).format(appname=appname, cmds='\n'.join(cmds))
 
     return parse_args(args[1:], global_options_spec, 'command ...', msg, '{} @'.format(appname))