From 455a1e953246fed6ffd5fc992b649d2dbbf7da65 Mon Sep 17 00:00:00 2001
From: Kovid Goyal <kovid@kovidgoyal.net>
Date: Mon, 13 Jan 2020 12:38:58 +0530
Subject: [PATCH] Basic docs for marking

---
 docs/index.rst |  8 ++++++++
 docs/marks.rst | 35 +++++++++++++++++++++++++++++++++++
 2 files changed, 43 insertions(+)
 create mode 100644 docs/marks.rst

diff --git a/docs/index.rst b/docs/index.rst
index 46c88fbfd..2ebe2738a 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -441,6 +441,14 @@ internal buffer named ``a`` and :kbd:`F2` to paste from that buffer. The buffer
 names are arbitrary strings, so you can define as many such buffers as you
 need.
 
+Marks
+-------------
+
+kitty has the ability to mark text on the screen based on regular expressions.
+This can be useful to highlight words or phrases when browsing output from long
+running programs or similar. To learn how this feature works, see :doc:`marks`.
+
+
 Frequently Asked Questions
 ---------------------------------
 
diff --git a/docs/marks.rst b/docs/marks.rst
new file mode 100644
index 000000000..dc6ade52e
--- /dev/null
+++ b/docs/marks.rst
@@ -0,0 +1,35 @@
+Marks
+=================
+
+
+kitty has the ability to mark text on the screen based on regular expressions.
+This can be useful to highlight words or phrases when browsing output from long
+running programs or similar. Lets start with a few examples:
+
+Suppose we want to be able to highlight the word ERROR in the current window.
+Add the following to :file:`kitty.conf`::
+
+    map f1 toggle_marker text 1 ERROR
+
+Now when you press :kbd:`F1` all instances of the word :code:`ERROR` will be
+highlighted. To turn off the highlighting, press :kbd:`F1` again.
+If you want to make it case-insensitive, use::
+
+    map f1 toggle_marker itext 1 ERROR
+
+To make it match only complete words, use::
+
+    map f1 toggle_marker regex 1 \bERROR\b
+
+Suppose you want to highlight both :code:`ERROR` and :code:`WARNING`, case
+insensitively::
+
+    map f1 toggle_marker iregex 1 \bERROR\b 2 \bWARNING\b
+
+kitty supports up to 3 mark groups (the numbers in the commands above). You
+can control the colors used for these groups in :file:`kitty.conf` with::
+
+    mark1_foreground red
+    mark1_background gray
+    mark2_foreground green
+    ...