doc: Update documentation

3 files changed, 9 insertions, 23 deletions

diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index e21f5357a2..16f9a2ea6e 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -4944,8 +4944,8 @@ json_decode({expr})					*json_decode()*
 
 json_encode({expr})					*json_encode()*
 		Convert {expr} into a JSON string.  Accepts 
-		|msgpack-special-dict| as the input.  Will not convert |Funcref|s, 
-		mappings with non-string keys (can be created as 
+		|msgpack-special-dict| as the input.  Will not convert 
+		|Funcref|s, mappings with non-string keys (can be created as 
 		|msgpack-special-dict|), values with self-referencing 
 		containers, strings which contain non-UTF-8 characters, 
 		pseudo-UTF-8 strings which contain codepoints reserved for 
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index d212e029aa..c30a88f48d 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -5151,8 +5151,8 @@ A jump table for the options with a short description can be found at |Q_op|.
 		saved.  When not included, the value of 'history' is used.
 							*shada-c*
 	c	Dummy option, kept for compatibility reasons.  Has no actual 
-		effect.  Current encoding state is described in 
-		|shada-encoding|.
+		effect: ShaDa always uses UTF-8 and 'encoding' value is fixed 
+		to UTF-8 as well.
 							*shada-f*
 	f	Whether file marks need to be stored.  If zero, file marks ('0
 		to '9, 'A to 'Z) are not stored.  When not present or when
diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt
index daf6ad9ca2..2d1dd22222 100644
--- a/runtime/doc/starting.txt
+++ b/runtime/doc/starting.txt
@@ -1097,23 +1097,6 @@ SHADA FILE NAME						*shada-file-name*
   default and the name given with 'shada' or "-i" (unless it's NONE).
 
 
-CHARACTER ENCODING					*shada-encoding*
-
-The text in the ShaDa file is UTF-8-encoded.  Normally you will always work 
-with the same 'encoding' value, and this works just fine.  However, if you 
-read the ShaDa file with value for 'encoding' different from utf-8 and 
-'encoding' used when writing ShaDa file, some of the text (non-ASCII 
-characters) may be invalid as Neovim always attempts to convert the text in 
-the ShaDa file from the UTF-8 to the current 'encoding' value.  Filenames are 
-never converted, affected elements are:
-
-- history strings;
-- variable values;
-- register values;
-- last used search and substitute patterns;
-- last used substitute replacement string.
-
-
 MANUALLY READING AND WRITING				*shada-read-write*
 
 Two commands can be used to read and write the ShaDa file manually.  This
@@ -1221,8 +1204,11 @@ exactly four MessagePack objects:
 3. Third goes the length of the fourth entry.  Unsigned integer as well, used 
    for fast skipping without parsing.
 4. Fourth is actual entry data.  All currently used ShaDa entries use 
-   containers to hold data: either map or array.  Exact format depends on the 
-   entry type:
+   containers to hold data: either map or array.  All string values in those 
+   containers are either binary (applies to filenames) or UTF-8, yet parser 
+   needs to expect that invalid bytes may be present in a UTF-8 string.
+
+   Exact format depends on the entry type:
 
    Entry type (name)   Entry data ~
    1 (Header)          Map containing data that describes the generator