docs: Update documents

README.adoc

@@ -26,7 +26,9 @@ See link:./doc/elin.txt[help] for example configurations.
 == 🍃 Related works
 
 * https://github.com/liquidz/elin-coc-source[elin-coc-source] - Completion source for coc.nvim
+* https://github.com/liquidz/elin-cmp-source[elin-cmp-source] - Completion source for nvim-cmp
 * https://github.com/liquidz/elin-format[elin-format] - Formatting plugin for elin
+* You can find other plugins with the https://github.com/topics/elin-clj-plugin[#elin-clj-plugin] topic.
 
 == 💚 Support
 

dev/elin/task/doc.clj

@@ -38,6 +38,10 @@
       (str/replace #"[()]" "")
       (str/replace #"[./#]" "-")))
 
+(defn- format-command-to-key-map
+  [command-str]
+  (str command-str "-default-mapping"))
+
 (defn- into-hash-map
   [key-fn val-fn coll]
   (reduce (fn [accm x]
@@ -57,6 +61,16 @@
       (help/parse-grouped-lines)
       (:commands)))
 
+(def ^:private command-key-mapping-dict
+  (let [grouped-lines (help/get-grouped-lines)
+        {:keys [mappings default-mappings]} (help/parse-grouped-lines grouped-lines)
+        command-to-mapping-dict (->> (reverse mappings)
+                                     (into-hash-map :command :mapping))
+        mapping-to-key-dict (->> (reverse default-mappings)
+                                 (into-hash-map :mapping :mapping-key))]
+    (update-vals command-to-mapping-dict
+                 #(get mapping-to-key-dict %))))
+
 (def ^:private handler-key-mapping-dict
   (let [grouped-lines (help/get-grouped-lines)
         {:keys [commands mappings default-mappings]} (help/parse-grouped-lines grouped-lines)
@@ -208,11 +222,17 @@
 
 (defn- generate-default-key-mapping-variables
   []
-  (->> handler-key-mapping-dict
-       (map (fn [[handler-symbol mapping-key]]
-              (format ":%s: %s" (format-handler-to-key-map handler-symbol) mapping-key)))
-       (str/join "\n")
-       (spit (io/file page-dir "variables.adoc"))))
+  (let [handler-to-mapping (map (fn [[handler-symbol mapping-key]]
+                                  (format ":%s: %s" (format-handler-to-key-map handler-symbol) mapping-key))
+                                handler-key-mapping-dict)
+        command-to-mapping (map (fn [[command mapping-key]]
+                                  (format ":%s: %s" (format-command-to-key-map command) mapping-key))
+                                command-key-mapping-dict)]
+
+    (->> (concat handler-to-mapping
+                 command-to-mapping)
+         (str/join "\n")
+         (spit (io/file page-dir "variables.adoc")))))
 
 (defn- generate-command-documents
   []

doc/pages/buffer/index.adoc

@@ -0,0 +1,22 @@
+=== Information buffer
+
+All information on Elin, such as the content of standard output during evaluation and test results, is recorded in this buffer.
+To show/clear the information buffer, use the following commands.
+
+[%autowidth,cols="a,a"]
+|===
+| Command | Default key mapping
+
+| ElinToggleInfoBuffer
+| `{elin-internal-buffer-info-toggle}`
+
+| ElinClearInfoBuffer
+| `{elin-internal-buffer-info-clear}`
+|===
+
+=== Temporal buffer
+
+This buffer temporarily displays content that is newly recorded in the <<Information buffer>> when the <<Information buffer>> is not currently visible.
+It is used, for example, to display <<Testing,test results>> or <<Macro,macro expansion results>>.
+
+This buffer automatically closes when the <<Information buffer>> is displayed.

doc/pages/cheatsheet.adoc

@@ -61,7 +61,7 @@ See https://github.com/liquidz/elin/blob/main/doc/elin-mapping.txt[elin-mapping.
 ! Jump to references of symbol under cursor
 !===
 
-| *<<Reference>>*
+| *<<Lookup>>*
 [cols="30,70"]
 !===
 ! {elin-handler-lookup-lookup}

doc/pages/completion/index.adoc

@@ -0,0 +1,21 @@
+Elin provides only omni completion by default.
+It is set to https://vim-jp.org/vimdoc-en/options.html#'omnifunc'[omnifunc] for `clojure` filetype automatically.
+
+Vim has a https://vim-jp.org/vimdoc-en/insert.html#i_CTRL-X_CTRL-O[<C-x><C-o>] key mapping for omni completion.
+
+
+=== Auto completion
+
+Auto completion feature is provided as external <<Plugin,elin plugins>> like follows.
+
+[%autowidth,cols="a,a",]
+|===
+| Plugin | Description
+
+| https://github.com/liquidz/elin-coc-source[liquidz/elin-coc-source]
+| Completion source for https://github.com/neoclide/coc.nvim[neoclide/coc.nvim]
+
+| https://github.com/liquidz/elin-cmp-source[liquidz/elin-cmp-source]
+| Completion source for https://github.com/hrsh7th/nvim-cmp[hrsh7th/nvim-cmp]
+
+|===

doc/pages/debugging/index.adoc

@@ -0,0 +1,31 @@
+=== Macro
+Expanding macro is important for writing/debugging macros. Elin provides following commands.
+
+[%autowidth,cols="a,a"]
+|===
+| Command | Default key mapping
+
+| <<ElinMacroExpand1CurrentList>>
+| `{elin-handler-evaluate-expand-1-current-list}`
+|===
+
+Expanding results are shown in the <<Temporal buffer>> and <<Information buffer>>.
+
+
+=== #dbg and #break
+
+Elin supports CIDER’s `#dbg` and `#break` reader literals.
+The easiest way is to put `#dbg` to your code, and evaluate it.
+
+[source,clojure]
+----
+(defn fib [n]
+  #dbg (loop [a 0 b 1 n n]
+         (if (<= n 0)
+           a
+           (recur b (+ a b) (dec n)))))
+----
+
+Once you evaluate `(fib 10)`, debugger will launch.
+
+This feature is implemented by the <<_interceptor_debugprocess_debugger>> interceptor.

doc/pages/evaluation/index.adoc

@@ -20,11 +20,18 @@ See the following figure for the concrete ranges.
 
 If you enable default key mappings, following key mappings are available.
 
-[%autowidth]
+[%autowidth,cols="a,a"]
 |===
-| Evaluate current expression | {elin-handler-evaluate-evaluate-current-expr}
-| Evaluate current list | {elin-handler-evaluate-evaluate-current-list}
-| Evaluate current top list | {elin-handler-evaluate-evaluate-current-top-list}
+| Feature | Default key mapping
+
+| Evaluate current expression
+| `{elin-handler-evaluate-evaluate-current-expr}`
+
+| Evaluate current list
+| `{elin-handler-evaluate-evaluate-current-list}`
+
+| Evaluate current top list
+| `{elin-handler-evaluate-evaluate-current-top-list}`
 |===
 
 === Results

doc/pages/index.adoc

@@ -53,20 +53,16 @@ This project is being developed as the successor to {vim-iced} and, as same as v
 The goal of this project is to provide a server program that serves as the foundation for a Clojure development environment and its interface, enabling it to theoretically offer a Clojure development environment to any editor.
 
 
-
 == Getting Started
 include::./getting_started/index.adoc[]
 
 
-
 == Evaluation
 include::./evaluation/index.adoc[]
 
 
-
 == Completion
-TODO
-
+include::./completion/index.adoc[]
 
 
 == Formatting
@@ -76,61 +72,44 @@ The reason is that for format checks in CI, external tools such as {cljfmt}, {cl
 However, if you blocked when saving files in namespaces with large amounts of code due to the formatting entire buffer, you can use the {elin-format} plugin to format only the current form.
 
 
-
 == Navigation
-TODO
-
-
+include::./navigation/index.adoc[]
 
-== Reference
-TODO
-
-
-
-== Macro
-TODO
 
+== Lookup
+include::./lookup/index.adoc[]
 
 
 == Namespace
-TODO
-
+include::./namespace/index.adoc[]
 
 
 == Testing
-TODO
-
+include::./testing/index.adoc[]
 
 
 == ClojureScript
 include::./clojurescript/index.adoc[]
 
 
-
 == Skeleton
-TODO
+include::./skeleton/index.adoc[]
 
 
+== Debugging
+include::./debugging/index.adoc[]
 
-== Buffer
-=== Information buffer
-TODO
-
-=== Temporal buffer
-TODO
 
+== Buffer
+include::./buffer/index.adoc[]
 
 
 == Configuration
 include::./configuration/index.adoc[]
 
 
-
 == Plugin
-The plugins are tagged with the `elin-clj-plugin` topic on GitHub, so you can view the list from the following link.
-
-https://github.com/topics/elin-clj-plugin
-
+include::./plugin/index.adoc[]
 
 
 == Handlers
@@ -139,28 +118,21 @@ Handlers process requests from the host editor.
 === Built-in Handlers
 include::./generated/handlers.adoc[]
 
-
-
 == Interceptors
 Interceptors intercept various processes and change their behavior.
 
 === Built-in Interceptors
 include::./generated/interceptors.adoc[]
 
 
-
 == Host
 === Vim/Neovim
-
 ==== Commands
 include::./generated/commands.adoc[]
 
 
-
-== Tips
-* TODO
-** Output the clojure.tools.logging contents to information buffer
-
+// == Tips
+// include::./tips/index.adoc[]
 
 
 == Cheatsheet

doc/pages/lookup/index.adoc

@@ -0,0 +1,20 @@
+There are some commands to lookup the documentation of the symbol under the cursor.
+
+[%autowidth,cols="a,a,a"]
+|===
+| Command | Default key mapping | Description
+
+| <<ElinLookup>>
+| `{elin-handler-lookup-lookup}`
+| Lookup docstring
+
+| <<ElinShowSource>>
+| `{elin-handler-lookup-show-source}`
+| Lookup source code
+
+| <<ElinShowClojureDocs>>
+| `{elin-handler-lookup-show-clojuredocs}`
+| Lookup https://clojuredocs.org/[ClojureDocs]
+
+|===
+

doc/pages/namespace/index.adoc

@@ -0,0 +1,19 @@
+Elin provides the following commands for namespace operations.
+
+[%autowidth,cols="a,a,a"]
+|===
+| Command | Default key mapping | Description
+
+| <<ElinEvalNsForm>>
+| `{elin-handler-evaluate-evaluate-namespace-form}`
+| Evaluate `ns` form in the current buffer
+
+| <<ElinAddLibspec>>
+| `{elin-handler-namespace-add-libspec}`
+| Allow selection of the available namespaces in <<Selectors>>, and add the selected one to the `ns` form.
+
+| <<ElinAddMissingLibspec>>
+| `{elin-handler-namespace-add-missing-libspec}`
+| Add the missing libspec for the symbol under the cursor to the `ns` form.
+
+|===

doc/pages/navigation/index.adoc

@@ -0,0 +1,52 @@
+=== Jump to definition
+
+Elin provides the following command to jump to the definition of the symbol under the cursor.
+
+[%autowidth,cols="a,a"]
+|===
+| Command | Default key mapping
+
+| <<ElinJumpToDefinition>>
+| `{elin-handler-navigate-jump-to-definition}`
+|===
+
+This command supports jumping to:
+
+* Qualified symbols
+* Local bindings
+* Protocol implementations
+
+=== Refer usages
+
+For browsing locations that refers to the symbol under the cursor, the following commannds are useful.
+
+[%autowidth,cols="a,a"]
+|===
+| Command | Default key mapping
+
+| <<ElinReferences>>
+| `{elin-handler-navigate-references}`
+
+| <<ElinLocalReferences>>
+| `{elin-handler-navigate-local-references}`
+|===
+
+When only one location is found, the cursor will jump to the location immediately.
+Otherwise, the locations will be added to the https://vim-jp.org/vimdoc-en/quickfix.html#location-list[location list].
+
+=== Other navigations
+
+==== Cycle source and test code
+
+You can cycle source file and test file for current namespace.
+
+[%autowidth,cols="a,a"]
+|===
+| Command | Default key mapping
+
+| <<ElinCycleSourceAndTest>>
+| `{elin-handler-navigate-cycle-source-and-test}`
+|===
+
+For example, when you are in `foo.core`, <<ElinCycleSourceAndTest>> command will open the file which has `foo.core-test` namespace.
+If there is no corresponding file, elin suggests pseudo file path to create new namespace.