doc: api.txt; deprecate <special>

runtime/doc/api.txt

@@ -165,7 +165,16 @@ nvim_input({keys})                                              *nvim_input()*
 
                                                     *nvim_replace_termcodes()*
 nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special})
-                Replaces any terminal codes with the internal representation
+                Replaces terminal codes and |keycodes| (<CR>, <Esc>, ...) in a
+                string with the internal representation.
+
+                Parameters:~
+                    {str}        String to be converted.
+                    {from_part}  Legacy Vim parameter. Usually true.
+                    {do_lt}      Also translate <lt>. Does nothing if
+                                 `special` is false.
+                    {special}    Replace |keycodes|, e.g. <CR> becomes a "\n"
+                                 char.
 
 nvim_command_output({str})                             *nvim_command_output()*
                 TODO: Documentation
@@ -182,8 +191,10 @@ nvim_eval({expr})                                                *nvim_eval()*
                     Evaluation result or expanded object
 
 nvim_call_function({fname}, {args})                     *nvim_call_function()*
-                Calls a VimL function with the given arguments. On VimL error:
+                Calls a VimL function with the given arguments
-                Returns a generic error; v:errmsg is not updated.
+
+                On VimL error: Returns a generic error; v:errmsg is not
+                updated.
 
                 Parameters:~
                     {fname}  Function to call
@@ -192,6 +203,23 @@ nvim_call_function({fname}, {args})                     *nvim_call_function()*
                 Return:~
                     Result of the function call
 
+nvim_execute_lua({code}, {args})                          *nvim_execute_lua()*
+                Execute lua code. Parameters might be passed, they are
+                available inside the chunk as `...`. The chunk can return a
+                value.
+
+                To evaluate an expression, it must be prefixed with "return ".
+                For instance, to call a lua function with arguments sent in
+                and get its return value back, use the code "return
+                my_function(...)".
+
+                Parameters:~
+                    {code}  lua code to execute
+                    {args}  Arguments to the code
+
+                Return:~
+                    Return value of lua code if present or NIL.
+
 nvim_strwidth({str})                                         *nvim_strwidth()*
                 Calculates the number of display cells occupied by `text`.
                 <Tab> counts as one cell.
@@ -382,6 +410,17 @@ nvim_get_mode()                                              *nvim_get_mode()*
                 Return:~
                     Dictionary { "mode": String, "blocking": Boolean }
 
+nvim_get_keymap({mode})                                    *nvim_get_keymap()*
+                Get a list of dictionaries describing global (i.e. non-buffer)
+                mappings Note that the "buffer" key will be 0 to represent
+                false.
+
+                Parameters:~
+                    {mode}  The abbreviation for the mode
+
+                Return:~
+                    An array of maparg() like dictionaries describing mappings
+
 nvim_get_api_info()                                      *nvim_get_api_info()*
                 TODO: Documentation
 
@@ -414,6 +453,54 @@ nvim_call_atomic({calls})                                 *nvim_call_atomic()*
                     error ocurred, the values from all preceding calls will
                     still be returned.
 
+nvim__id({obj})                                                   *nvim__id()*
+                Returns object given as argument
+
+                This API function is used for testing. One should not rely on
+                its presence in plugins.
+
+                Parameters:~
+                    {obj}  Object to return.
+
+                Return:~
+                    its argument.
+
+nvim__id_array({arr})                                       *nvim__id_array()*
+                Returns array given as argument
+
+                This API function is used for testing. One should not rely on
+                its presence in plugins.
+
+                Parameters:~
+                    {arr}  Array to return.
+
+                Return:~
+                    its argument.
+
+nvim__id_dictionary({dct})                             *nvim__id_dictionary()*
+                Returns dictionary given as argument
+
+                This API function is used for testing. One should not rely on
+                its presence in plugins.
+
+                Parameters:~
+                    {dct}  Dictionary to return.
+
+                Return:~
+                    its argument.
+
+nvim__id_float({flt})                                       *nvim__id_float()*
+                Returns floating-point value given as argument
+
+                This API function is used for testing. One should not rely on
+                its presence in plugins.
+
+                Parameters:~
+                    {flt}  Value to return.
+
+                Return:~
+                    its argument.
+
 
 ==============================================================================
 Buffer Functions                                                  *api-buffer*
@@ -492,6 +579,18 @@ nvim_buf_get_changedtick({buffer})                *nvim_buf_get_changedtick()*
                 Return:~
                     b:changedtickvalue.
 
+nvim_buf_get_keymap({buffer}, {mode})                  *nvim_buf_get_keymap()*
+                Get a list of dictionaries describing buffer-local mappings
+                Note that the buffer key in the dictionary will represent the
+                buffer handle where the mapping is present
+
+                Parameters:~
+                    {mode}       The abbreviation for the mode
+                    {buffer_id}  Buffer handle
+
+                Return:~
+                    An array of maparg() like dictionaries describing mappings
+
 nvim_buf_set_var({buffer}, {name}, {value})               *nvim_buf_set_var()*
                 Sets a buffer-scoped (b:) variable
 

runtime/doc/deprecated.txt

@@ -39,10 +39,16 @@ Functions ~
 *highlightID()*		Obsolete name for |hlID()|.
 *last_buffer_nr()*	Obsolete name for bufnr("$").
 
+Modifiers ~
+*:menu-<special>*
+*:menu-special*		<> notation is always enabled. |cpo-<|
+*:map-<special>*
+*:map-special*		<> notation is always enabled. |cpo-<|
+
 Options ~
 *'fe'*			'fenc'+'enc' before Vim 6.0; no longer used.
 *'langnoremap'*		Deprecated alias to 'nolangremap'.
 *'vi'*
 *'viminfo'*		Deprecated alias to 'shada' option.
 
- vim:tw=78:ts=8:ft=help:norl:
+ vim:noet:tw=78:ts=8:ft=help:norl:

runtime/doc/gui.txt

@@ -501,21 +501,13 @@ The ":set ic" will not be echoed when using this menu.  Messages from the
 executed command are still given though.  To shut them up too, add a ":silent"
 in the executed command: >
 	:menu <silent> Search.Header :exe ":silent normal /Header\r"<CR>
-"<silent>" may also appear just after "<special>" or "<script>".
+"<silent>" may also appear just after "<script>".
-
-					*:menu-<special>* *:menu-special*
-Define a menu with <> notation for special keys, even though the "<" flag
-may appear in 'cpoptions'.  This is useful if the side effect of setting
-'cpoptions' is not desired.  Example: >
-	:menu <special> Search.Header /Header<CR>
-"<special>" must appear as the very first argument to the ":menu" command or
-just after "<silent>" or "<script>".
 
 						*:menu-<script>* *:menu-script*
 The "to" part of the menu will be inspected for mappings.  If you don't want
 this, use the ":noremenu" command (or the similar one for a specific mode).
 If you do want to use script-local mappings, add "<script>" as the very first
-argument to the ":menu" command or just after "<silent>" or "<special>".
+argument to the ":menu" command or just after "<silent>".
 
 							*menu-priority*
 You can give a priority to a menu.  Menus with a higher priority go more to

runtime/doc/map.txt

@@ -149,7 +149,7 @@ type "a", then "bar" will get inserted.
 
 1.2 SPECIAL ARGUMENTS					*:map-arguments*
 
-"<buffer>", "<nowait>", "<silent>", "<special>", "<script>", "<expr>" and
+"<buffer>", "<nowait>", "<silent>", "<script>", "<expr>" and
 "<unique>" can be used in any order.  They must appear right after the
 command, before any other arguments.
 
@@ -189,12 +189,6 @@ Prompts will still be given, e.g., for inputdialog().
 Using "<silent>" for an abbreviation is possible, but will cause redrawing of
 the command line to fail.
 
-						*:map-<special>* *:map-special*
-Define a mapping with <> notation for special keys, even though the "<" flag
-may appear in 'cpoptions'.  This is useful if the side effect of setting
-'cpoptions' is not desired.  Example: >
-	:map <special> <F12> /Header<CR>
-<
 						*:map-<script>* *:map-script*
 If the first argument to one of these commands is "<script>" and it is used to
 define a new mapping or abbreviation, the mapping will only remap characters
@@ -451,8 +445,7 @@ There are two ways to map a special key:
    (see table of keys |key-notation|, all keys from <Up> can be used).  The
    first ten function keys can be defined in two ways: Just the number, like
    "#2", and with "<F>", like "<F2>".  Both stand for function key 2.  "#0"
-   refers to function key 10.  The <> form cannot be used when 'cpoptions'
+   refers to function key 10.
-   includes the '<' flag.
 
 DETAIL: Vim first checks if a sequence from the keyboard is mapped.  If it
 isn't the terminal key codes are tried.  If a terminal code is found it is
@@ -1026,8 +1019,7 @@ functions used in one script use the same name as in other scripts.  To avoid
 this, they can be made local to the script.
 
 						*<SID>* *<SNR>* *E81*
-The string "<SID>" can be used in a mapping or menu.  This requires that the
+The string "<SID>" can be used in a mapping or menu.
-'<' flag is not present in 'cpoptions'.
    When executing the map command, Vim will replace "<SID>" with the special
 key code <SNR>, followed by a number that's unique for the script, and an
 underscore.  Example: >

runtime/doc/tips.txt

@@ -113,7 +113,6 @@ screen, you can use CTRL-X CTRL-E and CTRL-X CTRL-Y to scroll the screen.
 To make this easier, you could use these mappings: >
 	:inoremap <C-E> <C-X><C-E>
 	:inoremap <C-Y> <C-X><C-Y>
-(Type this literally, make sure the '<' flag is not in 'cpoptions').
 You then lose the ability to copy text from the line above/below the cursor
 |i_CTRL-E|.
 
@@ -129,8 +128,6 @@ If you like the scrolling to go a bit smoother, you can use these mappings: >
 	:map <C-U> <C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y>
 	:map <C-D> <C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E>
 
-(Type this literally, make sure the '<' flag is not in 'cpoptions').
-
 ==============================================================================
 Correcting common typing mistakes			*type-mistakes*
 

src/nvim/api/vim.c

@@ -141,7 +141,7 @@ Integer nvim_input(String keys)
 ///
 /// @param str        String to be converted.
 /// @param from_part  Legacy Vim parameter. Usually true.
-/// @param do_lt      Also translate <lt>. Does nothing if `special` is false.
+/// @param do_lt      Also translate <lt>. Ignored if `special` is false.
 /// @param special    Replace |keycodes|, e.g. <CR> becomes a "\n" char.
 /// @see replace_termcodes
 /// @see cpoptions