docs: mdBook-LS feature&video;update limitation&future work

README.md

@@ -1,22 +1,40 @@
 # mdBook Language Server
 
-WIP.
-
 mdBook-LS provides a language server to preview mdBook projects live,
-patching the edited chapter instantly as you type in your editor.
-Please see [Editor Setup](#editor-setup) for details on usage.
+patching the edited chapter instantly and asynchronously as you type in
+your editor.
+
+## mdBook-LS Features
+
+<https://github.com/SichangHe/mdbook_ls/assets/84777573/f75eb653-a143-4191-9c87-e6cb6064e6bc>
+
+- **Live preview**: Instantly see the latest preview as you type in the editor.
+- **Asynchronous patching**: No blocking your editor; under high load,
+    always tries to render the latest version while
+    showing intermediate feedbacks, using [a two-JoinSet].
+- **Peripheral watching**:
+    Change the important files of your project (`.gitignore`, `book.toml`,
+    `SUMMARY.md`, and the theme directory) and see the book fully rebuilt;
+    it reloads the file watcher and the web server as needed.
+- Refresh a patched page to manually trigger a full rebuild.
 
 ## Editor Setup
 
-<details>
-<summary>✅ NeoVim setup with LSPConfig</summary>
+### ✅ NeoVim setup with LSPConfig
+
+Please paste the below `mdbook_ls_setup` function in
+your Nvim configuration and call it with your client's `capabilities`.
+[Please see my config for an
+example](https://github.com/SichangHe/.config/blob/2a284f52c4d09632ad6e8bdacdd3b2a753736d46/nvim/lua/plugins/lsp.lua#L259).
 
-The plan is to merge this into [nvim-lspconfig].
+The snippet provides two Vim commands:
+`MDBookLSOpenPreview` starts the preview (if not already started)
+and opens the browser at the chapter you are editing;
+`MDBookLSStopPreview` stops updating the preview
+(Warp may keep serving on the port despite being cancelled).
 
-Before that happens,
-please paste the below `mdbook_ls_setup` function somewhere in
-your configuration files and [call it with your client's
-`capabilities`](https://github.com/SichangHe/.config/blob/ed7b2e2b5f2a0876ded985e345f2dc20ca2c1017/nvim/lua/plugins/lsp.lua#L259).
+<details>
+<summary>The <code>mdbook_ls_setup</code> function.</summary>
 
 ```lua
 local function mdbook_ls_setup(capabilities)
@@ -54,15 +72,15 @@ local function mdbook_ls_setup(capabilities)
         commands = {
             MDBookLSOpenPreview = {
                 open_preview,
-                description = 'Open MDBook-LS preview',
+                description = 'Open mdBook-LS preview',
             },
             MDBookLSStopPreview = {
                 stop_preview,
-                description = 'Stop MDBook-LS preview',
+                description = 'Stop mdBook-LS preview',
             },
         },
         docs = {
-            description = [[TODO]],
+            description = [[The mdBook Language Server for previewing mdBook projects live.]],
         },
     }
     lspconfig['mdbook_ls'].setup {
@@ -71,28 +89,33 @@ local function mdbook_ls_setup(capabilities)
 end
 ```
 
-Now, you would have two Vim commands:
-`MDBookLSOpenPreview` starts the preview (if not already started)
-and opens the browser at the chapter you are editing;
-`MDBookLSStopPreview` stops updating the preview
-(Warp may keep serving on the port despite being cancelled).
-
 </details>
 
+I plan to merge this into [nvim-lspconfig] in the future.
+
+### ❓ Visual Studio Code and other editor setup
+
 <details>
-<summary>❌ Visual Studio Code setup</summary>
+<summary>No official support, but community plugins are welcome.</summary>
 
-I do not currently use VSCode,
-do not plan to go through Microsoft's hoops to make an official plugin,
-and do not wish to maintain such plugins.
-If you use both VSCode and mdBook-LS,
-please feel free to make a VSCode plugin yourself and create an issue so
-I can link your plugin here.
+I do not currently use VSCode and these other editors,
+so I do not wish to maintain plugins for them.
+
+However,
+it should be straightforward to implement plugins for them since
+mdBook-LS implements the Language Server Protocol (LSP).
+So,
+please feel free to make a plugin yourself and create an issue for me to
+link it here.
 
 </details>
 
 ## mdBook Incremental Preview
 
+mdBook-Incremental-Preview powers the live preview feature of mdBook-LS.
+It can also be used standalone if you only wish to update the preview on
+file saves.
+
 mdBook-Incremental-Preview provides incremental preview building for
 mdBook projects.
 Unlike `mdbook watch` or `mdbook serve`,
@@ -110,7 +133,8 @@ mdbook-incremental-preview
 
 It has basically the same functionality as `mdbook serve` but incremental:
 
-- Chapter changes are patched individually and pushed to browser.
+- Chapter changes are patched individually and pushed to the browser,
+    without refresh.
 - Full rebuilds happen only when the `.gitignore`, `book.toml`, `SUMMARY.md`,
     or the theme directory changes,
     or a patched page is requested by a new client.
@@ -144,6 +168,14 @@ An example is below in [the MathJax support section](#mathjax-support).
     which operate on a single chapter.
     Even the `link` preprocessor works because
     it reads the input files directly.
+- Neither `print.html` or the search index are updated incrementally.
+    They are only rebuilt on full rebuilds,
+    which can be triggered by refreshing a patched page.
+- The book template (`index.hbs`)
+    has to include exactly `{{ content }}` in the `<main>` tag (the default),
+    otherwise the patching will not work correctly.
+    A workaround would be to allow custom injected scripts,
+    but I will not implement that unless demanded.
 
 ### MathJax support
 
@@ -153,29 +185,31 @@ so you should instead consider [mdBook-KaTeX], [client-side KaTeX]
 or other alternatives.
 
 If you have to stick with MathJax,
-add a custom script that listens to the `load` event and reruns MathJax,
+please add a custom script that listens to the `load` event and reruns MathJax,
 like this:
 
 ```javascript
-document.addEventListener("load", () => {
-    if (MathJax?.Hub?.Typeset != undefined) {
-        MathJax.Hub.Typeset();
-    }
-});
+document.addEventListener("load", () => MathJax.Hub.Typeset());
 ```
 
-### Future work for incremental preview
-
-- Background search indexing to save full rebuild time.
-
 ## Debugging
 
 We use `tracing-subscriber` with the `env-filter` feature to
 emit logs[^tracing-env-filter].
 Please configure the log level by setting the `RUST_LOG` environment variable.
 
+## Contributing
+
+I welcome high-quality issues and pull requests.
+
+## Future work
+
+- Unit tests so I do not need to test it in the editor on every commit.
+- Integrate with Open Telemetry so I do not need to stare at all the logs.
+
 [^tracing-env-filter]: <https://docs.rs/tracing-subscriber/latest/tracing_subscriber/#feature-flags>
 
+[a two-JoinSet]: https://docs.rs/tokio_two_join_set/latest/tokio_two_join_set/struct.TwoJoinSet.html
 [client-side KaTeX]: https://katex.org/docs/browser.html
 [load-event]: https://developer.mozilla.org/en-US/docs/Web/API/Window/load_event
 [mdBook-KaTeX]: https://github.com/lzanini/mdbook-katex