Update documentation

Update vim_diff.txt with :lmap differences, update documentation on
'keymap', and add tests.

The tests added are to demonstrate the behaviour specified in the
documentation of :loadkeymap.

4 files changed, 27 insertions, 4 deletions

diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt
index 9b61fa6527..c64f8a1e0a 100644
--- a/runtime/doc/map.txt
+++ b/runtime/doc/map.txt
@@ -386,7 +386,8 @@ state for Insert mode is also used when typing a character as an argument to
 command like "f" or "t".
    Language mappings will never be applied to already mapped characters.  They
 are only used for typed characters.  This assumes that the language mapping
-was already done when typing the mapping.
+was already done when typing the mapping. Correspondingly, language mappings
+are applied when recording macros, rather than when applying them.
 
 
 1.4 LISTING MAPPINGS					*map-listing*
diff --git a/runtime/doc/mbyte.txt b/runtime/doc/mbyte.txt
index 531629fddc..2d4a20ed72 100644
--- a/runtime/doc/mbyte.txt
+++ b/runtime/doc/mbyte.txt
@@ -834,7 +834,7 @@ keyboards and encodings.
 The actual mappings are in the lines below "loadkeymap".  In the example "a"
 is mapped to "A" and "b" to "B".  Thus the first item is mapped to the second
 item.  This is done for each line, until the end of the file.
-These items are exactly the same as what can be used in a |:lnoremap| command,
+These items are exactly the same as what can be used in a |:lmap| command,
 using "<buffer>" to make the mappings local to the buffer.
 You can check the result with this command: >
 	:lmap
@@ -849,8 +849,9 @@ Since Vim doesn't know if the next character after a quote is really an "a",
 it will wait for the next character.  To be able to insert a single quote,
 also add this line: >
 	''	'
-Since the mapping is defined with |:lnoremap| the resulting quote will not be
-used for the start of another character.
+Since the mapping is defined with |:lmap| the resulting quote will not be
+used for the start of another character defined in the 'keymap'.
+It can be used in a standard |:imap| mapping.
 The "accents" keymap uses this.				*keymap-accents*
 
 The first column can also be in |<>| form:
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index 3924dd4ebe..2d53f26028 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -309,6 +309,12 @@ Highlight groups:
 VimL (Vim script) compatibility:
   `count` does not alias to |v:count|
 
+|:lmap|s are applied to macro recordings, in Vim if a macro is recorded while
+using |:lmap|ped keys then the behaviour during record and replay differs.
+'keymap' is implemented via |:lmap| instead of |:lnoremap| in order to allow
+using macros and 'keymap' at the same time.
+This means that you can use |:imap| on the results of keys from 'keymap'.
+
 ==============================================================================
 5. Missing legacy features				 *nvim-features-missing*
 
diff --git a/test/functional/options/keymap_spec.lua b/test/functional/options/keymap_spec.lua
index 43fd1eb990..7f6d623dc7 100644
--- a/test/functional/options/keymap_spec.lua
+++ b/test/functional/options/keymap_spec.lua
@@ -215,4 +215,19 @@ describe("'keymap' / :lmap", function()
     feed('il')
     expect('aalllaaa')
   end)
+  it('does not cause recursive mappings', function()
+    command('lmap a l')
+    feed('qaila<esc>q')
+    expect('allllaaa')
+    feed('u@a')
+    expect('allllaaa')
+  end)
+  it('can handle multicharacter mappings', function()
+    command("lmap 'a x")
+    command("lmap '' '")
+    feed("qai'a''a<esc>q")
+    expect("x'alllaaa")
+    feed('u@a')
+    expect("x'alllaaa")
+  end)
 end)