1 files changed, 138 insertions, 0 deletions
diff --git a/runtime/doc/textprop.txt b/runtime/doc/textprop.txt
new file mode 100644
index 0000000..3752551
--- /dev/null
+++ b/runtime/doc/textprop.txt
@@ -0,0 +1,138 @@
+*textprop.txt*  For Vim version 8.1.  Last change: 2019 Jan 08
+
+
+		  VIM REFERENCE MANUAL    by Bram Moolenaar
+
+
+Displaying text with properties attached.		*text-properties*
+
+THIS IS UNDER DEVELOPMENT - ANYTHING MAY STILL CHANGE  *E967*
+
+What is not working yet:
+- Adjusting column/length when inserting text
+- Text properties spanning more than one line
+- prop_find()
+- callbacks when text properties are outdated
+
+
+1. Introduction			|text-prop-intro|
+2. Functions			|text-prop-functions|
+3. When text changes		|text-prop-changes|
+
+
+{Vi does not have text properties}
+{not able to use text properties when the |+textprop| feature was
+disabled at compile time}
+
+==============================================================================
+1. Introduction						*text-prop-intro*
+
+Text properties can be attached to text in a buffer.  They will move with the
+text: If lines are deleted or inserted the properties move with the text they
+are attached to.  Also when inserting/deleting text in the line before the
+text property.  And when inserting/deleting text inside the text property, it
+will increase/decrease in size.
+
+The main use for text properties is to highlight text.  This can be seen as a
+replacement for syntax highlighting.  Instead of defining patterns to match
+the text, the highlighting is set by a script, possibly using the output of an
+external parser.  This only needs to be done once, not every time when
+redrawing the screen, thus can be much faster, after the initial cost of
+attaching the text properties.
+
+Text properties can also be used for other purposes to identify text.  For
+example, add a text property on a function name, so that a search can be
+defined to jump to the next/previous function.
+
+A text property is attached at a specific line and column, and has a specified
+length.  The property can span multiple lines.
+
+A text property has these fields:
+	"id"		a number to be used as desired
+	"type"		the name of a property type
+
+
+Property Types ~
+							*E971*
+A text property normally has the name of a property type, which defines 
+how to highlight the text.  The property type can have these entries:
+	"highlight"	name of the highlight group to use
+	"priority"	when properties overlap, the one with the highest
+			priority will be used.
+	"start_incl"	when TRUE inserts at the start position will be
+			included in the text property
+	"end_incl"    	when TRUE inserts at the end position will be
+			included in the text property
+
+
+Example ~
+
+Suppose line 11 in a buffer has this text (excluding the indent):
+
+	The number 123 is smaller than 4567.
+
+To highlight the numbers in this text: >
+	call prop_type_add('number', {'highlight': 'Constant'})
+	call prop_add(11, 12, {'length': 3, 'type': 'number'})
+	call prop_add(11, 32, {'length': 4, 'type': 'number'})
+
+Try inserting or deleting lines above the text, you will see that the text
+properties stick to the text, thus the line number is adjusted as needed.
+
+Setting "start_incl" and "end_incl" is useful when white space surrounds the
+text, e.g. for a function name.  Using false is useful when the text starts
+and/or ends with a specific character, such as the quote surrounding a string.
+
+	func FuncName(arg) ~
+	     ^^^^^^^^        property with start_incl and end_incl set
+
+	var = "text"; ~
+	      ^^^^^^	     property with start_incl and end_incl not set
+
+Nevertheless, when text is inserted or deleted the text may need to be parsed
+and the text properties updated.  But this can be done asynchronously.
+
+==============================================================================
+2. Functions						*text-prop-functions*
+
+Manipulating text property types:
+
+prop_type_add({name}, {props})		define a new property type
+prop_type_change({name}, {props})	change an existing property type
+prop_type_delete({name} [, {props}])	delete a property type
+prop_type_get([{name} [, {props}])	get property type values
+prop_type_list([{props}])		get list of property types
+
+
+Manipulating text properties:
+
+prop_add({lnum}, {col}, {props})  	add a text property
+prop_clear({lnum} [, {lnum-end} [, {bufnr}]])
+					remove all text properties
+prop_find({props} [, {direction}])	search for a text property
+prop_list({lnum} [, {props})  		text properties in {lnum}
+prop_remove({props} [, {lnum} [, {lnum-end}]])
+					remove a text property
+
+==============================================================================
+3. When text changes				*text-prop-changes*
+
+Vim will do its best to keep the text properties on the text where it was
+attached.  When inserting or deleting text the properties after the change
+will move accordingly.
+
+When text is deleted and a text property no longer includes any text, it is
+deleted.  However, a text property that was defined as zero-width will remain,
+unless the whole line is deleted.
+
+When using replace mode, the text properties stay on the same character
+positions, even though the characters themselves change.
+
+
+When text property columns are not updated ~
+
+- When setting the line with |setline()| or through an interface, such as Lua,
+  Tcl or Python.
+
+
+ vim:tw=78:ts=8:noet:ft=help:norl: