From 94f7c57634fd3c0671550f13ff178a2bd3dad708 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Christian=20D=C3=BCrr?= <contact@christianduerr.com>
Date: Wed, 7 Feb 2018 10:42:59 +0100
Subject: [PATCH] Rework cursor config documentation

The documentation of the cursor fields has been completely reworked in
an attempt to make it more obvious what the specific fields in the
config are about.
---
 alacritty.yml       | 23 ++++++++++++++---------
 alacritty_macos.yml | 23 ++++++++++++++---------
 2 files changed, 28 insertions(+), 18 deletions(-)

diff --git a/alacritty.yml b/alacritty.yml
index 2858295c..d1fb1961 100644
--- a/alacritty.yml
+++ b/alacritty.yml
@@ -109,13 +109,15 @@ colors:
     foreground: '0xeaeaea'
     bright_foreground: '0xeaeaea'
 
-  # Colors the cursor will use if `custom_cursor_colors` is true
   cursor:
-    # Use custom cursor colors. If true, always display the cursor in the
-    # `colors.cursor.text` and `colors.cursor.cursor` colors,
-    # otherwise invert the colors of the background and foreground.
+    # If this is `false` the text cursor inverses
+    # the foreground and background colors.
     custom_colors: false
+    # Text color when the cursor is above a character.
+    # Only used when `custom_colors` is `true`.
     text: '0x000000'
+    # Cursor color.
+    # Only used when `custom_colors` is `true`.
     cursor: '0xffffff'
 
   # Normal colors
@@ -223,13 +225,16 @@ selection:
 dynamic_title: true
 
 cursor:
-  # Style of the cursor
+  # This is the default look of your text cursor.
+  # It might be overwritten by applications like `vim`.
   #
-  # Values for 'cursor_style':
-  # - Block
-  # - Underline
-  # - Beam
+  # Values for `style`:
+  # - Block     (Looks like: ▒)
+  # - Underline (Looks like: _)
+  # - Beam      (Looks like: |)
   style: Block
+  # When this is `true`, the text cursor is temporarily
+  # hidden when typing.
   hide_when_typing: false
 
 # Live config reload (changes require restart)
diff --git a/alacritty_macos.yml b/alacritty_macos.yml
index 99ca4c94..797bd363 100644
--- a/alacritty_macos.yml
+++ b/alacritty_macos.yml
@@ -89,13 +89,15 @@ colors:
     foreground: '0xeaeaea'
     bright_foreground: '0xeaeaea'
 
-  # Colors the cursor will use if `custom_cursor_colors` is true
   cursor:
-    # Use custom cursor colors. If true, always display the cursor in the
-    # `colors.cursor.text` and `colors.cursor.cursor` colors,
-    # otherwise invert the colors of the background and foreground.
+    # If this is `false` the text cursor inverses
+    # the foreground and background colors.
     custom_colors: false
+    # Text color when the cursor is above a character.
+    # Only used when `custom_colors` is `true`.
     text: '0x000000'
+    # Cursor color.
+    # Only used when `custom_colors` is `true`.
     cursor: '0xffffff'
 
   # Normal colors
@@ -204,13 +206,16 @@ selection:
 dynamic_title: true
 
 cursor:
-  # Style of the cursor
+  # This is the default look of your text cursor.
+  # It might be overwritten by applications like `vim`.
   #
-  # Values for 'cursor_style':
-  # - Block
-  # - Underline
-  # - Beam
+  # Values for `style`:
+  # - Block     (Looks like: ▒)
+  # - Underline (Looks like: _)
+  # - Beam      (Looks like: |)
   style: Block
+  # When this is `true`, the text cursor is temporarily
+  # hidden when typing.
   hide_when_typing: false
 
 # Live config reload (changes require restart)