diff --git a/docs/_static/custom.css b/docs/_static/custom.css index e2c170288..440ba5ba0 100644 --- a/docs/_static/custom.css +++ b/docs/_static/custom.css @@ -92,6 +92,10 @@ div.sphinxsidebar { color: blue; } +.env { + font-style: italic; +} + .italic { font-style: italic; } diff --git a/docs/conf.py b/docs/conf.py index f9fea1309..628ae55fd 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -91,6 +91,7 @@ rst_prolog = ''' .. role:: bold .. role:: cyan .. role:: title +.. role:: env ''' + create_shortcut_defs() diff --git a/docs/conf.rst b/docs/conf.rst index 6c3bfc55f..2a1e91874 100644 --- a/docs/conf.rst +++ b/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`` -environment variable. See the help for the :option:`--config` option in ``kitty ---help`` for full details. +specific path via the :option:`kitty --config` option or use the ``KITTY_CONFIG_DIRECTORY`` +environment variable. See the :option:`kitty --config` option +for full details. diff --git a/docs/remote-control.rst b/docs/remote-control.rst index f28a03e0f..ceb2f36da 100644 --- a/docs/remote-control.rst +++ b/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 diff --git a/kittens/diff/main.py b/kittens/diff/main.py index 1bda390bb..d077369e1 100644 --- a/kittens/diff/main.py +++ b/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)) diff --git a/kittens/icat/main.py b/kittens/icat/main.py index 4c877e011..427c18bce 100755 --- a/kittens/icat/main.py +++ b/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 -are in cells (i.e. cursor positions) with the origin |_ (0, 0)| at +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 :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 -send the data via terminal escape codes. Note that if you use the |_ file| +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 :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. ''' diff --git a/kitty/cli.py b/kitty/cli.py index ce9f4a340..ce27a90cc 100644 --- a/kitty/cli.py +++ b/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} -"$XDG_CONFIG_DIRS/{appname}/{conf_name}.conf". The first one that exists is used as the +:file:`$XDG_CONFIG_HOME/{appname}/{conf_name}.conf`, :file:`~/.config/{appname}/{conf_name}.conf`, {macos_confpath} +: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 -instead create a new top-level window in the existing |_ {appname}| instance. This -allows |_ {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 -|_ --instance-group| option +If specified only a single instance of :italic:`{appname}` will run. New invocations will +instead create a new top-level window in the existing :italic:`{appname}` instance. This +allows :italic:`{appname}` to share a single sprite cache on the GPU and also reduces +startup time. You can also have separate groups of :italic:`{appname}` instances by using the +:option:`kitty --instance-group` option --instance-group -Used in combination with the |_ --single-instance| option. All |_ {appname}| invocations -with the same |_ --instance-group| will result in new windows being created -in the first |_ {appname}| instance within that group +Used in combination with the :option:`kitty --single-instance` option. All :italic:`{appname}` invocations +with the same :option:`kitty --instance-group` will result in new windows being created +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 -|_ --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|. -To control kitty, you can send it commands with |_ kitty @| using the |_ --to| option +messages. For example, :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. +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) - for ch in m.group(1): - t = {'C': cyan, '_': italic, '*': bold, 'G': green, 'T': title}[ch](t) - return t + role, text = m.group(1, 2) + return role_map[role](text) - text = re.sub(r'[|]([a-zA-Z_*]+?) (.+?)[|]', sub, text) - return text + text = re.sub(r':([a-z]+):`([^`]+)`', sub, 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 ( - '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) + message = message or default_msg 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 ( - '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) + message = message or default_msg 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)) diff --git a/kitty/cmds.py b/kitty/cmds.py index d377b1843..c596dfde5 100644 --- a/kitty/cmds.py +++ b/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. -You can use the |_ ls| command to get a list of windows. Note that for +:italic:`field:regexp`. Where field can be one of: id, title, pid, cwd, cmdline, num. +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. -You can use the |_ ls| command to get a list of tabs. Note that for +:italic:`field:regexp`. Where field can be one of: id, title, pid, cwd, cmdline. +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' - ' of |_ tabs|. Each tab has its own |_ id|, a |_ title| and a list of |_ windows|.' - ' Each window has an |_ id|, |_ title|, |_ current working directory|, |_ process id (PID)| and' - ' |_ command-line| of the process running in the window.\n\n' + ' operating system {appname} windows. Each OS window has an :italic:`id` and a list' + ' of :italic:`tabs`. Each tab has its own :italic:`id`, a :italic:`title` and a list of :italic:`windows`.' + ' Each window has an :italic:`id`, :italic:`title`, :italic:`current working directory`, :italic:`process id (PID)` and' + ' :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' - ' and |_ \\u21fa| to send unicode characters. If you use the |_ --match| option' + ' escaping rules. So you can use escapes like :italic:`\\x1b` to send control codes' + ' 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. -If |_ vertical|, it will make the window taller or shorter by the specified increment. The special value |_ reset| will +The axis along which to resize. If :italic:`horizontal`, it will make the window wider or narrower by the specified increment. +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 diff --git a/kitty/remote_control.py b/kitty/remote_control.py index 44f847b64..69e5a5a40 100644 --- a/kitty/remote_control.py +++ b/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' - ' to work.\n\n|T Commands|:\n{cmds}\n\n' + ' :italic:`allow_remote_control yes` to |kitty.conf| for this' + ' 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))