Merge 8db305eec1 into 7dec812f99

22.md

@@ -8,7 +8,7 @@ Comment
 
 A comment is a threading note always scoped to a root event or an [`I`-tag](73.md).
 
-It uses `kind:1111` with plaintext `.content` (no HTML, Markdown, or other formatting).
+It uses `kind:1111` with `.content` following the rules described in [NIP 27](./27).
 
 Comments MUST point to the root scope using uppercase tag names (e.g. `K`, `E`, `A` or `I`)
 and MUST point to the parent item with lowercase ones (e.g. `k`, `e`, `a` or `i`).

27.md

@@ -1,22 +1,65 @@
 NIP-27
 ======
 
-Text Note References
---------------------
+Nostr Unassuming Markup Language (NUML)
+---------------------------------------
 
-`draft` `optional`
+`draft` `mandatory`
 
-This document standardizes the treatment given by clients of inline references of other events and profiles inside the `.content` of any event that has readable text in its `.content` (such as kinds 1 and 30023).
+Unless explicitly specified otherwise, text content in nostr events MUST follow the guidelines below for balancing human readability and embedded links. Client MAY parse and display content to improve the aesthetics of displayed content.
 
-When creating an event, clients should include mentions to other profiles and to other events in the middle of the `.content` using [NIP-21](21.md) codes, such as `nostr:nprofile1qqsw3dy8cpu...6x2argwghx6egsqstvg`.
+# Recognized Formatting
 
-Including [NIP-18](18.md)'s quote tags (`["q", "<event-id> or <event-address>", "<relay-url>", "<pubkey-if-a-regular-event>"]`) for each reference is optional, clients should do it whenever they want the profile being mentioned to be notified of the mention, or when they want the referenced event to recognize their mention as a reply.
+- A `>` at the beginning of a line followed by a single space MAY be used to indicate quotations
+- A `#` at the beginning of a word MAY be used to indicate a topic and SHOULD have a corresponding `t` tag
+- A `$` at the beginning of a word MAY be used to indicate a stock ticker
+- Matched `*` characters within a single line MAY be used to indicate emphasis
+- Matched `:` characters around a single word MAY be used to indicate emojis (see [NIP 30](./30.md))
+- Single-backticks with no language tag MAY be used for inline code blocks
+- Triple-backticks with no language tag MAY be used for multi-line code blocks
+- Unordered lists MUST be one level deep, contain only one line, and SHOULD use the `-` character followed by a single space.
+- Ordered lists MUST be one level deep, contain only one line, and MUST be sequentially numbered using decimals, followed by a period and a space. Out-of-order numbers SHOULD be rendered as such.
 
-A reader client that receives an event with such `nostr:...` mentions in its `.content` can do any desired context augmentation (for example, linking to the profile or showing a preview of the mentioned event contents) it wants in the process. If turning such mentions into links, they could become internal links, [NIP-21](21.md) links or direct links to web clients that will handle these references.
+## Example
 
----
+```
+> This is a multiline quote
+>
+> And it ends here
 
-## Example of a profile mention process
+#bitcoin $BTC *emphasis* :custom_emoji: `inline code`
+
+- This
+- is
+- an
+- unordered
+- list
+
+1. This
+2. is
+3. an
+4. ordered
+5. list
+```
+
+# Embedding References
+
+URLs (excluding base64 encoded image data), [NIP 19](./19.md) nostr entities (prefixed with `nostr:`), and [NIP 73](./73.md) external content ids MAY be embedded in NUML `content`.
+
+Clients MAY display these references as-is, or they MAY use special handling when rendering them. When rendering references:
+
+- Inline references SHOULD be handled differently from references placed on their own line.
+- References on their own line MAY be rendered by embedding a representation of them (an image, video, card, audio player, etc).
+- Domain names without schema or path (e.g. `nytimes.com`) SHOULD be rendered as text.
+
+When publishing content:
+
+- A [NIP 18](./18.md) `q` tag pointing to any `nostr:nevent1...` or `nostr:naddr1...` references MAY be included if filtering by quoted entity is desired.
+- A [NIP 02](./02.md) `p` tag pointing to any `nostr:pub1...` or `nostr:nprofile1...` references MAY be included if notifying the tagged user is desired.
+- A [NIP 92](./92.md) `imeta` tag SHOULD be included for any media URLs in the content.
+- When a user manually pastes a [NIP 19](./19.md) entity, publishing clients SHOULD prefix the entity with `nostr:` before publishing.
+
+## Example
 
 Suppose Bob is writing a note in a client that has search-and-autocomplete functionality for users that is triggered when they write the character `@`.
 
@@ -41,14 +84,4 @@ Bob presses "enter" and now he sees his typed note as `"hello @mattn"`, `@mattn`
 }
 ```
 
-(Alternatively, the mention could have been a `nostr:npub1...` URL.)
-
-After Bob publishes this event and Carol sees it, her client will initially display the `.content` as it is, but later it will parse the `.content` and see that there is a `nostr:` URL in there, decode it, extract the public key from it (and possibly relay hints), fetch that profile from its internal database or relays, then replace the full URL with the name `@mattn`, with a link to the internal page view for that profile.
-
-## Verbose and probably unnecessary considerations
-
-- The example above was very concrete, but it doesn't mean all clients have to implement the same flow. There could be clients that do not support autocomplete at all, so they just allow users to paste raw [NIP-19](19.md) codes into the body of text, then prefix these with `nostr:` before publishing the event.
-- The flow for referencing other events is similar: a user could paste a `note1...` or `nevent1...` code and the client will turn that into a `nostr:note1...` or `nostr:nevent1...` URL. Then upon reading such references the client may show the referenced note in a preview box or something like that -- or nothing at all.
-- Other display procedures can be employed: for example, if a client that is designed for dealing with only `kind:1` text notes sees, for example, a [`kind:30023`](23.md) `nostr:naddr1...` URL reference in the `.content`, it can, for example, decide to turn that into a link to some hardcoded webapp capable of displaying such events.
-- Clients may give the user the option to include or not include tags for mentioned events or profiles. If someone wants to mention `mattn` without notifying them, but still have a nice augmentable/clickable link to their profile inside their note, they can instruct their client to _not_ create a `["p", ...]` tag for that specific mention.
-- In the same way, if someone wants to reference another note but their reference is not meant to show up along other replies to that same note, their client can choose to not include a corresponding `["e", ...]` tag for any given `nostr:nevent1...` URL inside `.content`. Clients may decide to expose these advanced functionalities to users or be more opinionated about things.
+After Bob publishes this event and Carol sees it, her client may display the `.content` as it is or it may parse the `.content`, decode the `nprofile` reference, extract the public key from it (and possibly relay hints), fetch that profile from its internal database or relays, then replace the full URL with the name `@mattn`, with a link to the internal page view for that profile.