added more detail on permalink kind

34.md

@@ -167,24 +167,44 @@ The Status of a patch-revision defaults to either that of the root-patch, or `16
 
 ## Permalinks
 
-Permalinks represent a link to one or more lines of a specific file in a repository. Client should render the content tag as preformatted text or can fetch and parse the original file's content for greater accuracy.
+Permalink events (`kind: 1623`) represent a permanent reference to specific lines within a file from a Git repository. They are intended to directly reference code or documentation precisely and immutably. Clients should render the event's `content` field as preformatted text (code blocks).
 
 ```jsonc
 {
   "kind": 1623,
-  "content": "<referenced code or text>",
+  "content": "<referenced code or text excerpt>",
   "tags": [
-    ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>"],
-    ["l", "markdown"],
+    // Reference to the repo's 30617 event if one exists 
+    ["a", "30617:<repo-owner-pubkey>:<repo-id>"],
+    // Explicit repository URL (optional if resolvable via 'a' tag, recommended for interoperability)
     ["repo", "https://github.com/nostr-protocol/nostr.git"],
-    ["branch", "permalink"],
+    // refs associated with the repository (mandatory)
     ["refs/<heads|tags>/<branch-or-tag-name>","<commit-id>"]
+
+    // Specific commit identifier referencing the repository state (mandatory)
+    ["commit", "<commit-id>"],
+    // Path to the specific file in the repository (mandatory)
     ["file", "34.md"],
-    ["lines", 170, 183]
+
+    // Start and end lines referenced within the file (optional, otherwise the event refers to the complete file)
+    ["lines", "172", "196"],
+    // Language identifier for syntax highlighting (optional but recommended)
+    ["l", "markdown"],
+    // Optional description providing context or purpose of permalink
+    ["description", "Specification for permalink events within NIP-34"]
   ]
 }
 ```
 
+### Client Recommendations
+
+Clients rendering permalink events SHOULD:
+
+- Fetch and display the exact lines from the referenced commit and file if the content is not explicitly included or for verification.
+- Display provided code/text using syntax highlighting according to the specified language tag (`l`).
+- Offer navigation or direct links to view the file within external repository browsers or clients.
+
+
 ## Possible things to be added later
 
 - "branch merge" kind (specifying a URL from where to fetch the branch to be merged)