From 2be45eeca352d782e694629a7a50a6f69cc52697 Mon Sep 17 00:00:00 2001
From: Kovid Goyal <kovid@kovidgoyal.net>
Date: Mon, 4 Jun 2018 12:40:23 +0530
Subject: [PATCH] More conf docs

---
 kitty/config.py      |  69 +----------------------
 kitty/config_data.py | 128 ++++++++++++++++++++++++++++++++++++++++++-
 kitty/session.py     |   2 +-
 3 files changed, 130 insertions(+), 69 deletions(-)

diff --git a/kitty/config.py b/kitty/config.py
index 14fa026de..9f61e70fe 100644
--- a/kitty/config.py
+++ b/kitty/config.py
@@ -13,12 +13,11 @@ from . import fast_data_types as defines
 from .conf.definition import as_conf_file
 from .conf.utils import (
     init_config, key_func, load_config as _load_config, merge_dicts,
-    parse_config_base, positive_float, positive_int, python_string, to_bool,
+    parse_config_base, positive_int, python_string, to_bool,
     to_cmdline, to_color, unit_float
 )
 from .config_data import all_options
 from .constants import cache_dir, defconf
-from .layout import all_layouts
 from .rgb import color_as_int, color_from_int
 from .utils import log_error
 from .config_data import to_modifiers, parse_mods
@@ -248,26 +247,6 @@ def parse_send_text(val, key_definitions):
     return parse_key(key_str, key_definitions)
 
 
-def uniq(vals, result_type=list):
-    seen = set()
-    seen_add = seen.add
-    return result_type(x for x in vals if x not in seen and not seen_add(x))
-
-
-def to_layout_names(raw):
-    parts = [x.strip().lower() for x in raw.split(',')]
-    ans = []
-    for p in parts:
-        if p == '*':
-            ans.extend(sorted(all_layouts))
-            continue
-        name = p.partition(':')[0]
-        if name not in all_layouts:
-            raise ValueError('The window layout {} is unknown'.format(p))
-        ans.append(p)
-    return uniq(ans)
-
-
 def macos_titlebar_color(x):
     x = x.strip('"')
     if x == 'system':
@@ -277,49 +256,14 @@ def macos_titlebar_color(x):
     return (color_as_int(to_color(x)) << 8) | 2
 
 
-def tab_separator(x):
-    for q in '\'"':
-        if x.startswith(q) and x.endswith(q):
-            x = x[1:-1]
-            break
-    if not x.strip():
-        x = ('\xa0' * len(x)) if x else defaults.tab_separator
-    return x
-
-
-def tab_font_style(x):
-    return {
-        'bold-italic': (True, True),
-        'bold': (True, False),
-        'italic': (False, True)
-    }.get(x.lower().replace('_', '-'), (False, False))
-
-
-def tab_bar_edge(x):
-    return {'top': 1, 'bottom': 3}.get(x.lower(), 3)
-
-
-def window_size(val):
-    val = val.lower()
-    unit = 'cells' if val.endswith('c') else 'px'
-    return positive_int(val.rstrip('c')), unit
-
-
 type_map = {
     'allow_remote_control': to_bool,
     'focus_follows_mouse': to_bool,
     'input_delay': positive_int,
     'sync_to_monitor': to_bool,
     'close_on_child_death': to_bool,
-    'window_border_width': positive_float,
-    'window_margin_width': positive_float,
-    'tab_bar_margin_width': positive_float,
-    'window_padding_width': positive_float,
     'enable_audio_bell': to_bool,
-    'enabled_layouts': to_layout_names,
     'remember_window_size': to_bool,
-    'initial_window_width': window_size,
-    'initial_window_height': window_size,
     'macos_hide_titlebar': to_bool,
     'macos_hide_from_tasks': to_bool,
     'macos_option_as_alt': to_bool,
@@ -327,23 +271,16 @@ type_map = {
     'dynamic_background_opacity': to_bool,
     'background_opacity': unit_float,
     'dim_opacity': unit_float,
-    'tab_separator': tab_separator,
-    'active_tab_font_style': tab_font_style,
-    'inactive_tab_font_style': tab_font_style,
-    'inactive_text_alpha': unit_float,
     'window_alert_on_bell': to_bool,
-    'tab_bar_edge': tab_bar_edge,
     'bell_on_tab': to_bool,
     'kitty_mod': to_modifiers,
     'clear_all_shortcuts': to_bool,
     'clipboard_control': lambda x: frozenset(x.lower().split()),
-    'window_resize_step_cells': int,
-    'window_resize_step_lines': int,
 }
 
 for name in (
-    'foreground background active_border_color inactive_border_color'
-    ' selection_foreground selection_background bell_border_color'
+    'foreground background '
+    ' selection_foreground selection_background '
 ).split():
     type_map[name] = to_color
 for i in range(256):
diff --git a/kitty/config_data.py b/kitty/config_data.py
index 015860033..f3bece6f3 100644
--- a/kitty/config_data.py
+++ b/kitty/config_data.py
@@ -7,8 +7,11 @@ from gettext import gettext as _
 
 from . import fast_data_types as defines
 from .conf.definition import option_func
-from .conf.utils import positive_float, positive_int, to_cmdline, to_color
+from .conf.utils import (
+    positive_float, positive_int, to_cmdline, to_color, unit_float
+)
 from .fast_data_types import CURSOR_BEAM, CURSOR_BLOCK, CURSOR_UNDERLINE
+from .layout import all_layouts
 from .utils import log_error
 
 # Utils  {{{
@@ -82,6 +85,32 @@ def to_modifiers(val):
     return parse_mods(val.split('+'), val) or 0
 
 
+def window_size(val):
+    val = val.lower()
+    unit = 'cells' if val.endswith('c') else 'px'
+    return positive_int(val.rstrip('c')), unit
+
+
+def uniq(vals, result_type=list):
+    seen = set()
+    seen_add = seen.add
+    return result_type(x for x in vals if x not in seen and not seen_add(x))
+
+
+def to_layout_names(raw):
+    parts = [x.strip().lower() for x in raw.split(',')]
+    ans = []
+    for p in parts:
+        if p == '*':
+            ans.extend(sorted(all_layouts))
+            continue
+        name = p.partition(':')[0]
+        if name not in all_layouts:
+            raise ValueError('The window layout {} is unknown'.format(p))
+        ans.append(p)
+    return uniq(ans)
+
+
 all_options = {}
 
 
@@ -97,6 +126,8 @@ o, g, all_groups = option_func(all_options, {
     'mouse': [_('Mouse'), ],
     'performance': [_('Performance tuning')],
     'bell': [_('Terminal bell')],
+    'window': [_('Window layout')],
+    'tabbar': [_('Tab bar')],
 })
 type_map = {o.name: o.option_type for o in all_options.values()}
 # }}}
@@ -240,7 +271,6 @@ moving the mouse around'''))
 
 # }}}
 
-
 g('performance')  # {{{
 
 o('repaint_delay', 10, option_type=positive_int, long_text=_('''
@@ -284,3 +314,97 @@ Show a bell symbol on the tab if a bell occurs in one of the windows in the
 tab and the window is not the currently focused window'''))
 
 # }}}
+
+g('window')  # {{{
+o('remember_window_size', True, long_text=_('''
+If enabled, the window size will be remembered so that new instances of kitty
+will have the same size as the previous instance. If disabled, the window will
+initially have size configured by initial_window_width/height, in pixels. You
+can use a suffix of "c" on the width/height values to have them interpreted as
+number of cells instead of pixels.
+'''))
+o('initial_window_width', '640', option_type=window_size)
+o('initial_window_height', '400', option_type=window_size)
+
+o('enabled_layouts', '*', option_type=to_layout_names, long_text=_('''
+The enabled window layouts. A comma separated list of layout names. The special
+value :code:`*` means all layouts. The first listed layout will be used as the
+startup layout. For a list of available layouts, see the :ref:`layouts`.
+'''))
+
+o('window_resize_step_cells', 2, option_type=positive_int, long_text=_('''
+The step size (in units of cell width/cell height) to use when resizing
+windows. The cells value is used for horizontal resizing and the lines value
+for vertical resizing.
+'''))
+o('window_resize_step_lines', 2, option_type=positive_int)
+
+o('window_border_width', 1.0, option_type=positive_float, long_text=_('''
+The width (in pts) of window borders. Will be rounded to the nearest number of pixels based on screen resolution.
+Note that borders are displayed only when more than one window is visible. They are meant to separate multiple windows.'''))
+
+o('window_margin_width', 0.0, option_type=positive_float, long_text=_('''
+The window margin (in pts) (blank area outside the border)'''))
+
+o('window_padding_width', 0.0, option_type=positive_float, long_text=_('''
+The window padding (in pts) (blank area between the text and the window border)'''))
+
+o('active_border_color', '#00ff00', option_type=to_color, long_text=_('''
+The color for the border of the active window'''))
+
+o('inactive_border_color', '#cccccc', option_type=to_color, long_text=_('''
+The color for the border of inactive windows'''))
+
+o('bell_border_color', '#ff5a00', option_type=to_color, long_text=_('''
+The color for the border of inactive windows in which a bell has occurred'''))
+
+o('inactive_text_alpha', 1.0, option_type=unit_float, long_text=_('''
+Fade the text in inactive windows by the specified amount (a number between
+zero and one, with zero being fully faded).
+'''))
+# }}}
+
+g('tabbar')   # {{{
+default_tab_separator = ' ┇'
+
+
+def tab_separator(x):
+    for q in '\'"':
+        if x.startswith(q) and x.endswith(q):
+            x = x[1:-1]
+            break
+    if not x.strip():
+        x = ('\xa0' * len(x)) if x else default_tab_separator
+    return x
+
+
+def tab_bar_edge(x):
+    return {'top': 1, 'bottom': 3}.get(x.lower(), 3)
+
+
+def tab_font_style(x):
+    return {
+        'bold-italic': (True, True),
+        'bold': (True, False),
+        'italic': (False, True)
+    }.get(x.lower().replace('_', '-'), (False, False))
+
+
+o('tab_bar_edge', 'bottom', option_type=tab_bar_edge, long_text=_('''
+Which edge to show the tab bar on, top or bottom'''))
+
+o('tab_bar_margin_width', 0.0, option_type=positive_float, long_text=_('''
+The margin to the left and right of the tab bar (in pts)'''))
+
+o('tab_separator', '"{}"'.format(default_tab_separator), option_type=tab_separator, long_text=_('''
+The separator between tabs in the tab bar'''))
+
+o('active_tab_foreground', '#000', option_type=to_color, long_text=_('''
+Tab bar colors and styles'''))
+o('active_tab_background', '#eee', option_type=to_color)
+o('active_tab_font_style', 'bold-italic', option_type=tab_font_style)
+o('inactive_tab_foreground', '#444', option_type=to_color)
+o('inactive_tab_background', '#999', option_type=to_color)
+o('inactive_tab_font_style', 'normal', option_type=tab_font_style)
+
+# }}}
diff --git a/kitty/session.py b/kitty/session.py
index 1c882be38..b4e6a8d49 100644
--- a/kitty/session.py
+++ b/kitty/session.py
@@ -4,7 +4,7 @@
 
 import shlex
 
-from .config import to_layout_names
+from .config_data import to_layout_names
 from .constants import shell_path
 from .layout import all_layouts