documentation: Add documentation on shada plugin

1 files changed, 143 insertions, 0 deletions

diff --git a/runtime/doc/filetype.txt b/runtime/doc/filetype.txt
index d1f8b1de4c..baf7550948 100644
--- a/runtime/doc/filetype.txt
+++ b/runtime/doc/filetype.txt
@@ -557,6 +557,149 @@ Since the text for this plugin is rather long it has been put in a separate
 file: |pi_spec.txt|.
 
 
+SHADA							*ft-shada*
+
+Allows editing binary |shada-file|s in a nice way.  Opened binary files are 
+displayed in the following format: >
+
+    Type with timestamp YYYY-mm-ddTHH:MM:SS:
+      % Key__  Description___  Value
+      + fooba  foo bar baz fo  {msgpack-value}
+      + abcde  abc def ghi jk  {msgpack-value}
+    Other type with timestamp YYYY-mm-ddTHH:MM:SS:
+      @ Description__  Value
+      - foo bar baz t  {msgpack-value}
+      # Expected more elements in list
+    Some other type with timestamp YYYY-mm-ddTHH:MM:SS:
+      # Unexpected type: type instead of map
+      = {msgpack-value}
+
+Filetype plugin defines all |Cmd-event|s.  Defined |SourceCmd| event makes 
+"source file.shada" be equivalent to "|:rshada| file.shada".  |BufWriteCmd|, 
+|FileWriteCmd| and |FileAppendCmd| events are affected by the following 
+settings:
+
+*g:shada#keep_old_header*	Boolean, if set to false all header entries 
+				are ignored when writing.  Defaults to 1.
+*g:shada#add_own_header*	Boolean, if set to true first written entry 
+				will always be header entry with two values in 
+				a map with attached data: |v:version| attached 
+				to "version" key and "shada.vim" attached to 
+				"generator" key.  Defaults to 1.
+
+Format description:
+
+1. `#` starts a comment.  Lines starting with space characters and then `#` 
+   are ignored.  Plugin may only add comment lines to indicate some errors in 
+   ShaDa format.  Lines containing no non-whitespace characters are also 
+   ignored.
+2. Each entry starts with line that has format "{type} with timestamp 
+   {timestamp}:". {timestamp} is |strftime()|-formatted string representing 
+   actual UNIX timestamp value. First strftime() argument is equal to 
+   `%Y-%m-%dT%H:%M:%S`.  When writing this timestamp is parsed using 
+   |msgpack#strptime()|, with caching (it remembers which timestamp produced 
+   particular strftime() output and uses this value if you did not change 
+   timestamp). {type} is one of
+    1 - Header
+    2 - Search pattern
+    3 - Replacement string
+    4 - History entry
+    5 - Register
+    6 - Variable
+    7 - Global mark
+    8 - Jump
+    9 - Buffer list
+   10 - Local mark
+   11 - Change
+    * - Unknown (0x{type-hex})
+
+   Each type may be represented using Unknown entry: "Jump with timestamp ..." 
+   is the same as "Unknown (0x8) with timestamp ....".
+3. After header there is one of the following lines:
+   1. "  % Key__  Description__  Value": map header.  After mapping header 
+      follows a table which may contain comments and lines consisting of 
+      "  +", key, description and |{msgpack-value}|.  Key is separated by at 
+      least two spaces with description, description is separated by at least 
+      two spaces with the value.  Each key in the map must be at most as wide 
+      as "Key__" header: "Key" allows at most 3-byte keys, "Key__" allows at 
+      most 5-byte keys.  If keys actually occupy less bytes then the rest is 
+      filled with spaces.  Keys cannot be empty, end with spaces, contain two 
+      consequent spaces inside of them or contain multibyte characters (use 
+      "=" format if you need this).  Descriptions have the same restrictions 
+      on width and contents, except that empty descriptions are allowed.  
+      Description column may be omitted.
+
+      When writing description is ignored.  Keys with values |msgpack#equal| 
+      to default ones are ignored.  Order of keys is preserved.  All keys are 
+      treated as strings (not binary strings).
+
+      Note: specifically for buffer list entries it is allowed to have more 
+      then one map header.  Each map header starts a new map entry inside 
+      buffer list because ShaDa buffer list entry is an array of maps.  I.e. >
+
+        Buffer list with timestamp 1970-01-01T00:00:00:
+          % Key  Description  Value
+          + f    file name    "/foo"
+          + l    line number  1
+          + c    column       10
+<
+      is equivalent to >
+
+        Buffer list with timestamp 1970-01-01T00:00:00:
+          = [{="f": "/foo", ="c": 10}]
+<
+      and >
+
+        Buffer list with timestamp 1970-01-01T00:00:00:
+          % Key  Description  Value
+          + f    file name    "/foo"
+
+          % Key  Description  Value
+          + f    file name    "/bar"
+<
+      is equivalent to >
+
+        Buffer list with timestamp 1970-01-01T00:00:00:
+          = [{="f": "/foo"}, {="f": "/bar"}]
+<
+      Note 2: specifically for register entries special syntax for arrays was 
+      designed: >
+
+        Register with timestamp 1970-01-01T00:00:00:
+          % Key  Description  Value
+          + rc   contents     @
+          | - "line1"
+          | - "line2"
+<
+      This is equivalent to >
+
+        Register with timestamp 1970-01-01T00:00:00:
+          % Key  Description  Value
+          + rc   contents     ["line1", "line2"]
+<
+      Such syntax is automatically used if array representation appears to be 
+      too lengthy.
+   2. "  @  Description__  Value": array header.  Same as map, but key is 
+      omitted and description cannot be omitted.  Array entries start with 
+      "  -". Example: >
+
+        History entry with timestamp 1970-01-01T00:00:00:
+          @ Description_  Value
+          - history type  SEARCH
+          - contents      "foo"
+          - separator     '/'
+<
+      is equivalent to >
+
+        History entry with timestamp 1970-01-01T00:00:00:
+          = [SEARCH, "foo", '/']
+<
+      Note: special array syntax for register entries is not recognized here.
+   3. "  = {msgpack-value}": raw values.  |{msgpack-value}| in this case may 
+      have absolutely any type.  Special array syntax for register entries is 
+      not recognized here as well.
+
+
 SQL							*ft-sql*
 
 Since the text for this plugin is rather long it has been put in a separate