Merge pull request #9 from unclebob/nip10

Nip10

2 files changed, 58 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.
diff --git a/14.md b/14.md
new file mode 100644
index 0000000..0b37e8a
--- /dev/null
+++ b/14.md
@@ -0,0 +1,19 @@
+NIP-14
+======
+
+Subject tag in Text events.
+---------------------------
+
+`draft` `optional` `author:unclebobmartin`
+
+This NIP defines the use of the "subject" tag in text (kind: 1) events.  
+(implemented in more-speech)
+
+`["subject": <string>]`
+
+Browsers often display threaded lists of messages.  The contents of the subject tag can be used in such lists, instead of the more ad hoc approach of using the first few words of the message.  This is very similar to the way email browsers display lists of incoming emails by subject rather than by contents.
+
+When replying to a message with a subject, clients SHOULD replicate the subject tag.  Clients MAY adorn the subject to denote
+that it is a reply.  e.g. by prepending "Re:".  
+
+Subjects should generally be shorter than 80 chars.  Long subjects will likely be trimmed by clients.