From 0c6b5a8b640341aae6b9f489dafde85002187221 Mon Sep 17 00:00:00 2001 From: "Robert C. Martin" Date: Sat, 21 May 2022 14:17:49 -0500 Subject: [PATCH 1/8] Subject and Discussion proposal --- Proposal-Subject-Discussion.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 Proposal-Subject-Discussion.md diff --git a/Proposal-Subject-Discussion.md b/Proposal-Subject-Discussion.md new file mode 100644 index 0000000..e9271cf --- /dev/null +++ b/Proposal-Subject-Discussion.md @@ -0,0 +1,33 @@ +NIP-?? +====== + +I am implementing this as a trial in more-speech. + +Subject and Discussion tags in Text events. +------------------------------------------- + +`draft` `optional` `author:unclebobmartin` + +This HIP defines the use of the Subject and Discussion tags in text (kind: 0) events. + +Subject +------- + +`["Subject": ]` + +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. + +Subjects should generally be short. + +Discussion +---------- + +`["Discussion": ]` + +Sometimes users want to send messages to a general audience based on a discussion topic. Other users would like to read all messages in a discussion topic without having to specifically follow the authors. Text messages with Discussion tags allow clients to present those messsages that match the discussion. + +Thoughts? + + From 0eab9a9f26acb1fc93b43bb4b6adfac798e22451 Mon Sep 17 00:00:00 2001 From: "Robert C. Martin" Date: Sat, 21 May 2022 14:40:57 -0500 Subject: [PATCH 2/8] change Subject and Discussion tags to lower case --- Proposal-Subject-Discussion.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Proposal-Subject-Discussion.md b/Proposal-Subject-Discussion.md index e9271cf..3c5c197 100644 --- a/Proposal-Subject-Discussion.md +++ b/Proposal-Subject-Discussion.md @@ -13,7 +13,7 @@ This HIP defines the use of the Subject and Discussion tags in text (kind: 0) ev Subject ------- -`["Subject": ]` +`["subject": ]` 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. @@ -24,7 +24,7 @@ Subjects should generally be short. Discussion ---------- -`["Discussion": ]` +`["discussion": ]` Sometimes users want to send messages to a general audience based on a discussion topic. Other users would like to read all messages in a discussion topic without having to specifically follow the authors. Text messages with Discussion tags allow clients to present those messsages that match the discussion. From e22ea1a9ac6574c662603779ace0f112600aa2e8 Mon Sep 17 00:00:00 2001 From: "Robert C. Martin" Date: Sat, 21 May 2022 15:10:56 -0500 Subject: [PATCH 3/8] kind 1 --- Proposal-Subject-Discussion.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Proposal-Subject-Discussion.md b/Proposal-Subject-Discussion.md index 3c5c197..da219fc 100644 --- a/Proposal-Subject-Discussion.md +++ b/Proposal-Subject-Discussion.md @@ -8,7 +8,7 @@ Subject and Discussion tags in Text events. `draft` `optional` `author:unclebobmartin` -This HIP defines the use of the Subject and Discussion tags in text (kind: 0) events. +This HIP defines the use of the Subject and Discussion tags in text (kind: 1) events. Subject ------- From ee0c337eed5c0e01edf5bf0e838e52284ce05075 Mon Sep 17 00:00:00 2001 From: "Robert C. Martin" Date: Sun, 22 May 2022 13:29:55 -0500 Subject: [PATCH 4/8] remove 'discussion' tag --- Proposal-Subject-Discussion.md | 19 ++++--------------- 1 file changed, 4 insertions(+), 15 deletions(-) diff --git a/Proposal-Subject-Discussion.md b/Proposal-Subject-Discussion.md index da219fc..cf9ee19 100644 --- a/Proposal-Subject-Discussion.md +++ b/Proposal-Subject-Discussion.md @@ -3,12 +3,12 @@ NIP-?? I am implementing this as a trial in more-speech. -Subject and Discussion tags in Text events. -------------------------------------------- +Subject tag in Text events. +--------------------------- `draft` `optional` `author:unclebobmartin` -This HIP defines the use of the Subject and Discussion tags in text (kind: 1) events. +This NIP defines the use of the Subject tag in text (kind: 1) events. Subject ------- @@ -19,15 +19,4 @@ Browsers often display threaded lists of messages. The contents of the subject When replying to a message with a subject, clients should replicate the subject tag. -Subjects should generally be short. - -Discussion ----------- - -`["discussion": ]` - -Sometimes users want to send messages to a general audience based on a discussion topic. Other users would like to read all messages in a discussion topic without having to specifically follow the authors. Text messages with Discussion tags allow clients to present those messsages that match the discussion. - -Thoughts? - - +Subjects should generally be shorter than 80 chars. Long subjects will likely be trimmed by clients. From ebacbccda8c27ce259e3288af0f51026904ba5a7 Mon Sep 17 00:00:00 2001 From: "Robert C. Martin" Date: Tue, 24 May 2022 07:33:11 -0500 Subject: [PATCH 5/8] Nip-14 for subject tag --- Proposal-Subject-Discussion.md => 14.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) rename Proposal-Subject-Discussion.md => 14.md (65%) diff --git a/Proposal-Subject-Discussion.md b/14.md similarity index 65% rename from Proposal-Subject-Discussion.md rename to 14.md index cf9ee19..0b37e8a 100644 --- a/Proposal-Subject-Discussion.md +++ b/14.md @@ -1,22 +1,19 @@ -NIP-?? +NIP-14 ====== -I am implementing this as a trial in more-speech. - Subject tag in Text events. --------------------------- `draft` `optional` `author:unclebobmartin` -This NIP defines the use of the Subject tag in text (kind: 1) events. - -Subject -------- +This NIP defines the use of the "subject" tag in text (kind: 1) events. +(implemented in more-speech) `["subject": ]` 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. +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. From 99a5e7ad765da3afae6a1a2f4e774c572a42eb19 Mon Sep 17 00:00:00 2001 From: "Robert C. Martin" Date: Tue, 24 May 2022 09:22:22 -0500 Subject: [PATCH 6/8] Qualified Tags Proposal --- ProposalQualifiedTags.md | 80 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 ProposalQualifiedTags.md diff --git a/ProposalQualifiedTags.md b/ProposalQualifiedTags.md new file mode 100644 index 0000000..bdc9b6a --- /dev/null +++ b/ProposalQualifiedTags.md @@ -0,0 +1,80 @@ +#NIP-?? + + +##Qualified Tags. + +`draft` `mandatory(7/1/22)` `author:unclebobmartin` + +###Abstract +In order to resolve the ambiguities that have arisen based upon the ad-hoc rules that have been used to identify replies, I propose that we add an optional qualifier to tags in general. In the case of replies these qualifiers would look like this: + +`[["e[reply]" ] ["e[root]" ]]` + +Such qualifiers ought to create the flexibility we will need as new use cases present themselves. + +###Justification +Replying to an event is a use-case that is separate from the kind of citing that the unqualified "e" tag is meant for. The attempt to use "e" tags to handle replies has led several clients to impose an ad-hoc ordering to the "e" tags. That ordering was eventually described in NIP-10. It describes these three cases: + + 1. `[["e" ]]` + 2. `[["e" ] ["e" ]]` + 3. `[["e" ] ["e" ]... ["e" ]]` + +Where: + + * `reply-id` is the id of the event being replied to. + * `root-id` is the id of the event at the root of the thread of replies. + +Unfortunately these orderings create ambiguities. + +For example, consider an event with this tag: `[["e" ]]` + +Is this event a reply to `event-id`, or is it merely mentioning `event-id`? + +To answer this question, some clients (e.g. damus) have resorted to an undocumented and ad-hoc _parsing_ rule. These clients parse the content of the event, looking for the replacement tags defined in NIP-08. (e.g. `#[n]`, where `n` is the ordinal position of the tag in the `tags` array. More on that later.) The client determimes which "e" tags hold the `` and the `` by eliminating all "e" tags that have replacement tokens in the content. The remaining "e" tags must be the `` and ``; and they are identified by their order in the tags array. + +Unfortunately, if the `` and `` are to be properly identified, this solution _forces_ the use of replacement tokens in the content. This, it seems to me is an unreasonable constraint that all clients would have to conform to. It is unreasonable because it will likely be common for the author of an event to include footnotes in "e" tags without referencing them with replacement tokens in the content. These unreferenced mentions lead to ambiguities. + +###Ambiguities + + * An event with an unreferenced footnote would use the tag `[["e" ]]`. Clients that used NIP-10, and the ad-hoc _parsing_ rule would consider this to be a reply, and would therefore thread it below an event that is merely a footnote. Users will consider this to be _odd_. + + * An event with two unreferenced footnotes would use the tags `[["e" ] ["e" ] ["e[root]" ]]` + +This eliminates the need for NIP-10, and also eliminates the need for the ad-hoc _parsing_ rule. The need for the `` is obvious. The `` is necessary because clients may not posess the event that is at the root of the thread. + +The positional ordering of NIP-08 replacement tokens could be resolved with: + +`["e[fun-event]" ]` and the content reference: `#[fun-event]`. + +###Implementation plan + +Because there are clients currently following NIP-10 and the ad-hoc _parsing_ rule, we need a way to gently transition toward the tag qualifier solution. (if adopted.) + +I propose that clients that have implemented NIP-10 (and possibly also the ad-hoc _parsing_ rule) continue to adhere to them, while ALSO adding _additional_ qualified "e" tags. Thus: + +`[["e" ] ["e" ] ["e[reply]" ] ["e[root]" ]]` + +New clients should NOT implement NIP-10 and should start using qualified tags immediately. + +I propose that we depracate NIP-10 with a cutoff date of July 1, 2022, after which NIP-10 would no longer be valid and all clients must use qualified tags for replies. + +It is my hope that the community is small enough, at this point in time, to tolerate this change without undue pain. + + From 69da7c52af1c268d990279eaf1d789a67b1ba83a Mon Sep 17 00:00:00 2001 From: "Robert C. Martin" Date: Tue, 24 May 2022 09:33:16 -0500 Subject: [PATCH 7/8] moving qualified tags to new branch --- ProposalQualifiedTags.md | 80 ---------------------------------------- 1 file changed, 80 deletions(-) delete mode 100644 ProposalQualifiedTags.md diff --git a/ProposalQualifiedTags.md b/ProposalQualifiedTags.md deleted file mode 100644 index bdc9b6a..0000000 --- a/ProposalQualifiedTags.md +++ /dev/null @@ -1,80 +0,0 @@ -#NIP-?? - - -##Qualified Tags. - -`draft` `mandatory(7/1/22)` `author:unclebobmartin` - -###Abstract -In order to resolve the ambiguities that have arisen based upon the ad-hoc rules that have been used to identify replies, I propose that we add an optional qualifier to tags in general. In the case of replies these qualifiers would look like this: - -`[["e[reply]" ] ["e[root]" ]]` - -Such qualifiers ought to create the flexibility we will need as new use cases present themselves. - -###Justification -Replying to an event is a use-case that is separate from the kind of citing that the unqualified "e" tag is meant for. The attempt to use "e" tags to handle replies has led several clients to impose an ad-hoc ordering to the "e" tags. That ordering was eventually described in NIP-10. It describes these three cases: - - 1. `[["e" ]]` - 2. `[["e" ] ["e" ]]` - 3. `[["e" ] ["e" ]... ["e" ]]` - -Where: - - * `reply-id` is the id of the event being replied to. - * `root-id` is the id of the event at the root of the thread of replies. - -Unfortunately these orderings create ambiguities. - -For example, consider an event with this tag: `[["e" ]]` - -Is this event a reply to `event-id`, or is it merely mentioning `event-id`? - -To answer this question, some clients (e.g. damus) have resorted to an undocumented and ad-hoc _parsing_ rule. These clients parse the content of the event, looking for the replacement tags defined in NIP-08. (e.g. `#[n]`, where `n` is the ordinal position of the tag in the `tags` array. More on that later.) The client determimes which "e" tags hold the `` and the `` by eliminating all "e" tags that have replacement tokens in the content. The remaining "e" tags must be the `` and ``; and they are identified by their order in the tags array. - -Unfortunately, if the `` and `` are to be properly identified, this solution _forces_ the use of replacement tokens in the content. This, it seems to me is an unreasonable constraint that all clients would have to conform to. It is unreasonable because it will likely be common for the author of an event to include footnotes in "e" tags without referencing them with replacement tokens in the content. These unreferenced mentions lead to ambiguities. - -###Ambiguities - - * An event with an unreferenced footnote would use the tag `[["e" ]]`. Clients that used NIP-10, and the ad-hoc _parsing_ rule would consider this to be a reply, and would therefore thread it below an event that is merely a footnote. Users will consider this to be _odd_. - - * An event with two unreferenced footnotes would use the tags `[["e" ] ["e" ] ["e[root]" ]]` - -This eliminates the need for NIP-10, and also eliminates the need for the ad-hoc _parsing_ rule. The need for the `` is obvious. The `` is necessary because clients may not posess the event that is at the root of the thread. - -The positional ordering of NIP-08 replacement tokens could be resolved with: - -`["e[fun-event]" ]` and the content reference: `#[fun-event]`. - -###Implementation plan - -Because there are clients currently following NIP-10 and the ad-hoc _parsing_ rule, we need a way to gently transition toward the tag qualifier solution. (if adopted.) - -I propose that clients that have implemented NIP-10 (and possibly also the ad-hoc _parsing_ rule) continue to adhere to them, while ALSO adding _additional_ qualified "e" tags. Thus: - -`[["e" ] ["e" ] ["e[reply]" ] ["e[root]" ]]` - -New clients should NOT implement NIP-10 and should start using qualified tags immediately. - -I propose that we depracate NIP-10 with a cutoff date of July 1, 2022, after which NIP-10 would no longer be valid and all clients must use qualified tags for replies. - -It is my hope that the community is small enough, at this point in time, to tolerate this change without undue pain. - - From 387ce5dbd59047463788b2f101aa3130bf68abce Mon Sep 17 00:00:00 2001 From: "Robert C. Martin" Date: Tue, 24 May 2022 18:07:09 -0500 Subject: [PATCH 8/8] Nip 10 updated with tag markers --- 10.md | 61 ++++++++++++++++++++++++++++++++++++++--------------------- 1 file 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", ]` 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. + * `` is the id of the event being referenced. + * `` 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:
+ 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:
+ `["e",]`: 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",]`, `["e",]`
+ `` is the id of the event at the root of the reply chain. `` is the id of the article to which this event is a reply. + + * Many "e" tags: `["e",]` `["e",]`, ..., `["e",]`
+There may be any number of ``. 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", ]` + +Where: + + * `` is the id of the event being referenced. + * `` is the URL of a recommended relay associated with the reference. It is NOT optional. + * `` 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 ``. 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 `` or ``. + + +## 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.