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.

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*

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
+Since the mapping is defined with |:lmap| the resulting quote will not be
-used for the start of another character.
+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:

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*
 

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)