From 58a21b9ef064ac4b0198fc7dd3ea82a879c745cf Mon Sep 17 00:00:00 2001
From: Michael Peyton Jones <me@michaelpj.com>
Date: Mon, 11 Apr 2022 10:21:53 +0100
Subject: [PATCH] Make PositionEncodingKind a type

As discussed here:
https://github.com/microsoft/language-server-protocol/commit/f9c85d535bbbf918d2433c034f20f99ddadf0ba1#r70968669
---
 .../lsp/3.17/general/initialize.md            | 13 ++----
 _specifications/lsp/3.17/types/position.md    | 41 +++++++++++++++++--
 2 files changed, 40 insertions(+), 14 deletions(-)

diff --git a/_specifications/lsp/3.17/general/initialize.md b/_specifications/lsp/3.17/general/initialize.md
index a379ff0b4..e03ea40c6 100644
--- a/_specifications/lsp/3.17/general/initialize.md
+++ b/_specifications/lsp/3.17/general/initialize.md
@@ -510,13 +510,6 @@ interface ClientCapabilities {
 		 *
 		 * If omitted it defaults to ['utf-16'].
 		 *
-		 * For the following standard Unicode encodings these values should be
-		 * used:
-		 *
-		 * UTF-8: 'utf-8'
-		 * UTF-16: 'utf-16'
-		 * UTF-32: 'utf-32'
-		 *
 		 * Implementation considerations: since the conversion from one encoding
 		 * into another requires the content of the file / line the conversion
 		 * is best done where the file is read which is usually on the server
@@ -525,7 +518,7 @@ interface ClientCapabilities {
 		 * @since 3.17.0
 		 * @proposed
 		 */
-		positionEncodings?: ('utf-16' | 'utf-8' | 'utf-32' | string)[];
+		positionEncodings?: PositionEncodingKind[];
 	};
 
 	/**
@@ -621,7 +614,7 @@ interface ServerCapabilities {
 	 * @since 3.17.0
 	 * @proposed
 	 */
-	positionEncoding?: 'utf-16' | 'utf-8' | 'utf-32' | string;
+	positionEncoding?: PositionEncodingKind;
 
 	/**
 	 * Defines how text documents are synced. Is either a detailed structure
@@ -873,4 +866,4 @@ interface ServerCapabilities {
 	 */
 	experimental?: LSPAny;
 }
-```
\ No newline at end of file
+```
diff --git a/_specifications/lsp/3.17/types/position.md b/_specifications/lsp/3.17/types/position.md
index 22f5f2a27..bc46eac25 100644
--- a/_specifications/lsp/3.17/types/position.md
+++ b/_specifications/lsp/3.17/types/position.md
@@ -10,13 +10,46 @@ interface Position {
 	line: uinteger;
 
 	/**
-	 * Character offset on a line in a document (zero-based). Assuming that
-	 * the line is represented as a string, the `character` value represents
-	 * the gap between the `character` and `character + 1`.
+	 * Character offset on a line in a document (zero-based). The meaning of this
+	 * offset is determined by the negotiated `PositionEncodingKind`.
 	 *
 	 * If the character value is greater than the line length it defaults back
 	 * to the line length.
 	 */
 	character: uinteger;
 }
-```
\ No newline at end of file
+```
+
+When describing positions the protocol needs to specify how offsets (specifically character offsets) should be interpreted.
+The corresponding `PostionEncodingKind` is negotiated between the server and client and server during initialization.
+
+```typscript
+/**
+ * A type indicating how positions are encoded,
+ * specifically what column offsets mean.
+ */
+export type PositionEncodingKind = string;
+
+/**
+ * A set of predefined position encoding kinds.
+ */
+export namespace PositionEncodingKind {
+
+	/**
+	 * Character offsets count UTF-8 code units.
+	 */
+	export const UTF8: PositionEncodingKind = 'utf-8';
+
+	/**
+	 * Character offsets count UTF-16 code units.
+	 * This is the default and must always be supported
+	 * by servers
+	 */
+	export const UTF16: PositionEncodingKind = 'utf-16';
+
+	/**
+	 * Character offsets count UTF-32 code units.
+	 */
+	export const UTF32: PositionEncodingKind = 'utf-32';
+}
+```