Document and add create_hl_autocmd.

This allows to enable or disable inserting highlighting autocommands.

Relates to #70.

doc/hop.txt

@@ -474,6 +474,40 @@ below.
 >
         case_insensitive = true
 <
+
+`create_hl_autocmd`                                 *hop-config-create_hl_autocmd*
+    Create and set highlight autocommands to automatically apply highlights.
+    You will want this if you use a theme that clears all highlights before
+    applying its colorscheme.
+
+    Defaults:~
+>
+        create_hl_autocmd = true
+<
+
+==============================================================================
+HIGHLIGHTS                                                      *hop-highlights*
+
+Anywhere in the hint buffer that doesn’t contain a hint, the |hl-EndOfBuffer|
+highlight is used. For the rest:
+
+`HopNextKey`                                                   *hop-hl-HopNextkey*
+    Highlight used for the mono-sequence keys (i.e. sequence of 1).
+
+`HopNextKey1`                                                 *hop-hl-HopNextKey1*
+    Highlight used for the first key in a sequence.
+
+`HopNextKey2`                                                 *hop-hl-HopNextKey2*
+    Highlight used for the second and remaining keys in a sequence.
+
+`HopUnmatched`                                               *hop-hl-HopUnmatched*
+    Highlight used for unmatched part of the buffer when running a Hop command
+    / Lua functions.
+
+Highlights are inserted in an augroup, `HopInitHighlight`, and an autocommand
+is automatically set when initializing the plugin, unless you set
+|hop-config-create_hl_autocmd| to `false`.
+
 ==============================================================================
 LICENSE                                                            *hop-license*
 
@@ -508,24 +542,5 @@ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-==============================================================================
-HIGHLIGHTS                                                      *hop-highlights*
-
-Anywhere in the hint buffer that doesn’t contain a hint, the |hl-EndOfBuffer|
-highlight is used. For the rest:
-
-`HopNextKey`                                                   *hop-hl-HopNextkey*
-    Highlight used for the mono-sequence keys (i.e. sequence of 1).
-
-`HopNextKey1`                                                 *hop-hl-HopNextKey1*
-    Highlight used for the first key in a sequence.
-
-`HopNextKey2`                                                 *hop-hl-HopNextKey2*
-    Highlight used for the second and remaining keys in a sequence.
-
-`HopUnmatched`                                               *hop-hl-HopUnmatched*
-    Highlight used for unmatched part of the buffer when running a Hop command
-    / Lua functions.
-
 ==============================================================================
 vim:tw=78:sw=4:ts=8:ft=help:norl:

lua/hop/defaults.lua

@@ -8,5 +8,6 @@ M.winblend = 50
 M.teasing = true
 M.jump_on_sole_occurrence = true
 M.case_insensitive = true
+M.create_hl_autocmd = true
 
 return M

lua/hop/init.lua

@@ -3,14 +3,6 @@ local hint = require'hop.hint'
 
 local M = {}
 
-M.opts = defaults
-
--- Setup user settings.
-function M.setup(opts)
-  -- Look up keys in user-defined table with fallback to defaults.
-  M.opts = setmetatable(opts, {__index = defaults})
-end
-
 -- Allows to override global options with user local overrides.
 local function get_command_opts(local_opts)
   -- In case, local opts are defined, chain opts lookup: [user_local] -> [user_global] -> [default]
@@ -238,9 +230,19 @@ function M.hint_lines(opts)
   hint_with(hint.by_line_start, get_command_opts(opts))
 end
 
--- Insert the highlights and register the autocommand.
-local highlight = require'hop.highlight'
-highlight.insert_highlights()
-highlight.create_autocmd()
+-- Setup user settings.
+M.opts = defaults
+function M.setup(opts)
+  -- Look up keys in user-defined table with fallback to defaults.
+  M.opts = setmetatable(opts, {__index = defaults})
+
+  -- Insert the highlights and register the autocommand if asked to.
+  local highlight = require'hop.highlight'
+  highlight.insert_highlights()
+
+  if opts.create_hl_autocmd then
+    highlight.create_autocmd()
+  end
+end
 
 return M