Merge pull request #9 from unclebob/nip10

Nip10

1 files changed, 39 insertions, 22 deletions

diff --git a/10.md b/10.md
index 1802044..dc32410 100644
--- a/10.md
+++ b/10.md
@@ -2,42 +2,59 @@ NIP-10
 ======
 
 
-On `e` and `p` tags in Text Events (kind 1).
+On "e" and "p" tags in Text Events (kind 1).
 --------------------------------------------
 
 `draft` `optional` `author:unclebobmartin`
 
-### A Conventional use of `e` and `p` tags within clients.
+## Abstract
+This NIP describes how to use "e" and "p" tags in text events, especially those that are replies to other text events.  It helps clients thread the replies into a tree rooted at the original event.
 
-The following seems to be the conventions that are used by `Branle`, `Damus`, and `more-speech` for referencing
-events and authors when building a reply.  These conventions help clients build event threads, and alert authors of
-replies.
+##Positional "e" tags (DEPRECATED)
+>This scheme is in common use; but should be considered deprecated.
 
-### Definitions:  
- * A reply chain is the list of events from the root event to a specific reply.  
- * A reply thread is the tree of events consisting of all replies beginning at the root.
- * An event id is a 32 byte number in lower-case hexidecimal.
+`["e", <event-id> <relay-url>]`  as per NIP-01.
 
-### The `e` tag
-Used in a text event contains a single event id.  ["e", "`hex-number`"]  
+Where:
 
- * No `e` tag: 
-This event is not a reply to, nor does it refer to, any other event.
+ * `<event-id>` is the id of the event being referenced.
+ * `<relay-url>` is the URL of a recommended relay associated with the reference.  Many clients treat this field as optional.
+ 
+**The positions of the "e" tags within the event denote specific meanings as follows**:
 
- * One `e` tag:  ["e",`id`]: 
-The id of the event to which this event is a reply.
+ * No "e" tag: <br>
+ This event is not a reply to, nor does it refer to, any other event.
 
- * Two `e` tags:  ["e",`root-id`], ["e",`reply-id`]
-'root-id' is the `id` of the event at the root of the reply chain.  `reply-id` is the id of the article to which this event is a reply.  
+ * One "e" tag: <br>
+ `["e",<id>]`: The id of the event to which this event is a reply.
 
- * Many `e` tags: ["e",`root-id`]  ["e",`mention-id`], ..., ["e",`reply-id`]
-There may be any number of `mention-ids`.  These are the ids of events which may, or may not be in the reply chain.  
+ * Two "e" tags:  `["e",<root-id>]`, `["e",<reply-id>]` <br>
+ `<root-id>` is the id of the event at the root of the reply chain.  `<reply-id>` is the id of the article to which this event is a reply.  
+
+ * Many "e" tags: `["e",<root-id>]` `["e",<mention-id>]`, ..., `["e",<reply-id>]`<br>
+There may be any number of `<mention-ids>`.  These are the ids of events which may, or may not be in the reply chain.  
 They are citings from this event.  `root-id` and `reply-id` are as above.
 
-### The `p` tag
+>This scheme is deprecated because it creates ambiguities that are difficult, or impossible to resolve when an event references another but is not a reply.
+
+## Marked "e" tags (PREFERRED)
+`["e", <event-id> <relay-url> <marker>]`  
+        
+Where:
+
+ * `<event-id>` is the id of the event being referenced.
+ * `<relay-url>` is the URL of a recommended relay associated with the reference.  It is NOT optional.
+ * `<marker>` is optional and if present is one of `"reply"` or `"root"`
+
+**The order of marked "e" tags is not relevant.**  Those marked with `"reply"` denote the `<reply-id>`.  Those marked with `"root"` denote the root id of the reply thread.
+
+>This scheme is preferred because it allows events to mention others without confusing them with `<relay-id>` or `<root-id>`.  
+
+
+## The "p" tag
 Used in a text event contains a list of pubkeys used to record who is involved in a reply thread.
 
-When replying to a text event E with `p` tags P, the replying event's `p` tags should contain P as well as the pubkey of the of the event being replied to.  
+When replying to a text event E the reply event's "p" tags should contain all of E's "p" tags as well as the `"pubkey"` of the of the event being replied to.  
 
-Example:  Given a text event authored by a1 with `p` tags [`p1`, `p2`, `p3`] then the `p` tags of the reply should be [`a1`, `p1`, `p2`, `p3`] 
+Example:  Given a text event authored by `a1` with "p" tags [`p1`, `p2`, `p3`] then the "p" tags of the reply should be [`a1`, `p1`, `p2`, `p3`] 
 in no particular order.