Improve formatting of launch --type help message

kitty/cli.py

@@ -122,8 +122,7 @@ def option(x: str) -> str:
         idx = x.find('-')
     if idx > -1:
         x = x[idx:]
-    parts = map(bold, x.split())
+    return bold(x.rstrip('>'))
-    return ' '.join(parts)
 
 
 @role
@@ -131,6 +130,11 @@ def code(x: str) -> str:
     return cyan(x)
 
 
+@role
+def term(x: str) -> str:
+    return italic(x.split('<', 1)[0])
+
+
 @role
 def kbd(x: str) -> str:
     return x
@@ -169,6 +173,7 @@ def parse_option_spec(spec: Optional[str] = None) -> Tuple[OptionSpecSeq, Option
     state = NORMAL
     lines = spec.splitlines()
     prev_line = ''
+    prev_indent = 0
     seq: OptionSpecSeq = []
     disabled: OptionSpecSeq = []
     mpat = re.compile('([a-z]+)=(.+)')
@@ -178,6 +183,9 @@ def parse_option_spec(spec: Optional[str] = None) -> Tuple[OptionSpecSeq, Option
     }
     empty_cmd = current_cmd
 
+    def indent_of_line(x: str) -> int:
+        return len(x) - len(x.lstrip())
+
     for line in lines:
         line = line.rstrip()
         if state is NORMAL:
@@ -221,9 +229,17 @@ def parse_option_spec(spec: Optional[str] = None) -> Tuple[OptionSpecSeq, Option
                             cv[ck] = vv
         elif state is HELP:
             if line:
+                current_indent = indent_of_line(line)
+                if current_indent > 1:
+                    if prev_indent == 0:
+                        current_cmd['help'] += '\n'
+                    else:
+                        line = line.strip()
+                prev_indent = current_indent
                 spc = '' if current_cmd['help'].endswith('\n') else ' '
                 current_cmd['help'] += spc + line
             else:
+                prev_indent = 0
                 if prev_line:
                     current_cmd['help'] += '\n\n'
                 else:
@@ -355,15 +371,16 @@ class PrintHelpForSeq:
             help_text = opt['help']
             if help_text == '!':
                 continue  # hidden option
-            a('  ' + ', '.join(map(green, sorted(opt['aliases']))))
+            a('  ' + ', '.join(map(green, sorted(opt['aliases'], reverse=True))))
+            defval = opt.get('default')
             if not opt.get('type', '').startswith('bool-'):
-                blocks[-1] += '={}'.format(italic(opt['dest'].upper()))
+                if defval:
+                    dt = '=[{}]'.format(italic(defval))
+                    blocks[-1] += dt
             if opt.get('help'):
-                defval = opt.get('default')
+                t = help_text.replace('%default', str(defval)).strip()
-                t = help_text.replace('%default', str(defval))
+                t = t.replace('#placeholder_for_formatting#', '')
-                wa(prettify(t.strip()), indent=4)
+                wa(prettify(t), indent=4)
-                if defval is not None:
-                    wa(f'Default: {defval}', indent=4)
                 if opt.get('choices'):
                     wa('Choices: {}'.format(', '.join(opt['choices'])), indent=4)
                 a('')
@@ -425,6 +442,7 @@ def seq_as_rst(
         if opt.get('help'):
             defval = opt.get('default')
             t = help_text.replace('%default', str(defval)).strip()
+            t = t.replace('#placeholder_for_formatting#', '')
             a('')
             a(textwrap.indent(prettify_rst(t), ' ' * 4))
             if defval is not None:

kitty/launch.py

@@ -57,13 +57,30 @@ of the active window in the tab is used as the tab title. The special value
 type=choices
 default=window
 choices=window,tab,os-window,overlay,background,clipboard,primary
-Where to launch the child process, in a new kitty :code:`window` in the current
+Where to launch the child process:
-tab, a new :code:`tab`, or a new :code:`os-window` or an :code:`overlay` over
+
-the current window. Note that if the current window already has an overlay, then
+:term:`window`
-it will open a new window. The value of :code:`background` means the process
+    a new :term:`window` in the current tab,
-will be run in the background. The values :code:`clipboard` and :code:`primary`
+
-are meant to work with :option:`--stdin-source <launch --stdin-source>` to copy
+:term:`tab`
-data to the system clipboard or primary selection.
+    a new tab in the current :term:`OS Window <os_window>`
+
+:term:`os-window <os_window>`
+    a new operating system window
+
+:term:`overlay`
+    an overlay window covering the current active window.
+    Note that if the current window already has an overlay,
+    then it will open a new window.
+
+:italic:`background`
+    the process will be run in the background, without a window
+
+:italic:`clipboard` and :italic:`primary`
+    are meant to work with :option:`--stdin-source <launch --stdin-source>` to copy
+    data to the system clipboard or primary selection.
+
+#placeholder_for_formatting#
 
 
 --keep-focus --dont-take-focus
@@ -151,14 +168,12 @@ type=list
 Restrict the actions remote control is allowed to take. This works like
 :opt:`remote_control_password`. You can specify a password and list of actions
 just as for :opt:`remote_control_password`. For example::
-
     --remote-control-password '"my passphrase" get-* set-colors'
 
 This password will be in effect for this window only.
 Note that any passwords you have defined for :opt:`remote_control_password`
 in :file:`kitty.conf` are also in effect. You can override them by using the same password here.
 You can also disable all :opt:`remote_control_password` global passwords for this window, by using::
-
     --remote-control-password '!'
 
 This option only takes effect if :option:`--allow-remote-control`