Add hyperlinks section to manual (#1816)

5 files changed, 70 insertions, 18 deletions

diff --git a/manual/src/SUMMARY.md b/manual/src/SUMMARY.md
index 588727a..38b6212 100644
--- a/manual/src/SUMMARY.md
+++ b/manual/src/SUMMARY.md
@@ -10,6 +10,7 @@
 - [Usage](./usage.md)
   - [Choosing colors (styles)](./choosing-colors-styles.md)
   - [Line numbers](./line-numbers.md)
+  - [Hyperlinks](./hyperlinks.md)
   - [Side-by-side view](./side-by-side-view.md)
   - [Grep](./grep.md)
   - ["Features": named groups of settings](./features-named-groups-of-settings.md)
diff --git a/manual/src/git-blame.md b/manual/src/git-blame.md
index 6798fe1..94d5def 100644
--- a/manual/src/git-blame.md
+++ b/manual/src/git-blame.md
@@ -2,5 +2,6 @@
 
 Set delta as the pager for `blame` in the `[pager]` section of your gitconfig: see the [example gitconfig](./get-started.md).
 If `hyperlinks` is enabled in the `[delta]` section then each blame commit will link to the commit on GitHub/GitLab/Bitbucket/etc.
+ See [hyperlinks](./hyperlinks.md).
 
 <table><tr><td><img width=600px src="https://user-images.githubusercontent.com/52205/141891376-1fdb87dc-1d9c-4ad6-9d72-eeb19a8aeb0b.png" alt="image" /></td></tr></table>
diff --git a/manual/src/grep.md b/manual/src/grep.md
index a090389..9892541 100644
--- a/manual/src/grep.md
+++ b/manual/src/grep.md
@@ -14,21 +14,4 @@ rg --json -C 2 handle | delta
 <img width="600px" alt="image" src="https://github.com/dandavison/open-in-editor/assets/52205/d203d380-5acb-4296-aeb9-e38c73d6c27f">
 </td></tr></table>
 
-If you enable hyperlinks then grep hits will be formatted as [OSC8 hyperlinks](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda) in terminal emulators that support the feature. If you're using VSCode, IntelliJ, or PyCharm, then use the dedicated URL handlers. I.e. one of the following lines:
-
-```gitconfig
-[delta]
-    hyperlinks = true
-    hyperlinks-file-link-format = "vscode://file/{path}:{line}"
-    # or: hyperlinks-file-link-format = "idea://open?file={path}&line={line}"
-    # or: hyperlinks-file-link-format = "pycharm://open?file={path}&line={line}"
-```
-
-For editors that don't have special URL handlers, it is possible to use a tool like <https://github.com/dandavison/open-in-editor/> to make your OS handle a click on those links by opening your editor at the correct file and line number, e.g.
-
-```gitconfig
-[delta]
-   hyperlinks = true
-   hyperlinks-file-link-format = "file-line://{path}:{line}"
-   # Now configure your OS to handle "file-line" URLs
-```
+With `hyperlinks` enabled, the line numbers in the grep output will be clickable links. See [hyperlinks](./hyperlinks.md).
diff --git a/manual/src/hyperlinks.md b/manual/src/hyperlinks.md
new file mode 100644
index 0000000..6b33df6
--- /dev/null
+++ b/manual/src/hyperlinks.md
@@ -0,0 +1,65 @@
+# Hyperlinks
+
+Delta uses [terminal hyperlinks](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda) to turn line numbers, file paths, commit hashes, etc into clickable links, as long as your terminal emulator supports the feature. Enable the feature with
+
+```gitconfig
+[delta]
+    hyperlinks = true
+```
+
+Commit hashes link to GitHub/GitLab/Bitbucket (use `hyperlinks-commit-link-format` for full control).
+
+The links on line numbers (in grep output, as well as diffs) are particularly interesting: with a little bit of effort, they can be made to open your editor or IDE at the correct line.
+Use `hyperlinks-file-link-format` to construct the correct URL for your system.
+For VSCode and JetBrains IDEs this is easy, since they support their own special URL protocols. Here are examples:
+
+```gitconfig
+[delta]
+    hyperlinks = true
+    hyperlinks-file-link-format = "vscode://file/{path}:{line}"
+    # or: hyperlinks-file-link-format = "idea://open?file={path}&line={line}"
+    # or: hyperlinks-file-link-format = "pycharm://open?file={path}&line={line}"
+```
+
+Zed also supports its own URL protocol, and probably others.
+
+If your editor does not have its own URL protocol, then there are still many possibilities, although they may be more work.
+
+- The easiest is probably to write a toy HTTP server (e.g. in [Python](https://docs.python.org/3/library/http.server.html)) that opens the links in the way that you need. Then your delta config would look something like
+    ```gitconfig
+    [delta]
+    hyperlinks = true
+    hyperlinks-file-link-format = "http://localhost:8000/open-in-editor?path={path}&line={line}"
+    # Now write an HTTP server that handles those requests by opening your editor at the file and line
+    ```
+
+    Here's some Python code that could be used as a starting point:
+    ```python
+    from http.server import BaseHTTPRequestHandler, HTTPServer
+    from subprocess import call
+    from urllib.parse import parse_qs, urlparse
+
+    class OpenInEditor(BaseHTTPRequestHandler):
+        def do_GET(self):
+            if self.path.startswith("/open-in-editor"):
+                query = parse_qs(urlparse(self.path).query)
+                [path], [line] = query["path"], query["line"]
+                # Replace with the right command for your editor
+                call(["code", "-g", f"{path}:{line}"])
+                self.send_response(200)
+            else:
+                self.send_response(404)
+            self.end_headers()
+
+    print("Starting httpd server on port 8000...")
+    HTTPServer(("", 8000), OpenInEditor).serve_forever()
+    ```
+
+- Another possibility is to register a custom protocol with your OS (like VSCode does) that invokes a script to open the file. [dandavison/open-in-editor](https://github.com/dandavison/open-in-editor) is a project that aimed to do that and may be helpful. However, registering the protocol with your OS can be frustrating, depending on your appetite for such things. If you go this route, your delta configuration would look like
+    ```gitconfig
+    [delta]
+    hyperlinks = true
+    hyperlinks-file-link-format = "my-file-line-protocol://{path}:{line}"
+    # Now configure your OS to handle "my-file-line-protocol" URLs!
+    ```
+- Finally, you can just use traditional `file://` links (making sure your OS is configured to use the correct editor). But then your editor won't open the file at the correct line, which would be missing out on something very useful.
\ No newline at end of file
diff --git a/manual/src/tips-and-tricks/using-delta-with-vscode.md b/manual/src/tips-and-tricks/using-delta-with-vscode.md
index 3deafbb..daea0e0 100644
--- a/manual/src/tips-and-tricks/using-delta-with-vscode.md
+++ b/manual/src/tips-and-tricks/using-delta-with-vscode.md
@@ -11,3 +11,5 @@ To format file links for opening in VSCode from other terminal emulators, use th
 ```
 
 (To use VSCode Insiders, change that to `vscode-insiders://file/{path}:{line}`).
+
+ See [hyperlinks](./hyperlinks.md).