docs: automatically generate help files from code

This takes the fennel code to generate documentation listing the
shortcuts installed.

.gitignore

@@ -0,0 +1 @@
+bepo-nvim-mapping

Makefile

@@ -1,9 +1,11 @@
 fnl_files = $(wildcard fnl/*.fnl)
-out_files = $(fnl_files:fnl/%.fnl=lua/%.lua)
+help_file = help/bepo-nvim.txt
+help_file_mapping = bepo-nvim-mapping
+out_files = $(fnl_files:fnl/%.fnl=lua/%.lua) $(help_file) $(help_file_mapping)
 
 all: $(out_files)
 
-fmt: $(fnl_files)
+fmt: $(fnl_files) gen_doc.fnl
 	fnlfmt --fix $<
 
 lua/%.lua: fnl/%.fnl lua/
@@ -15,4 +17,17 @@ lua/:
 clean:
 	rm -rf lua
 
-.PHONY: clean compile
+doc: $(help_file)
+
+$(help_file): $(help_file_mapping) help/
+	rm $(help_file)
+	cat $(help_file_mapping) >>$(help_file)
+	rm $(help_file_mapping)
+
+$(help_file_mapping): gen_doc.fnl $(fnl_files)
+	fennel --raw-errors --no-compiler-sandbox --metadata --globals '*' gen_doc.fnl > $(help_file_mapping)
+
+help/:
+	mkdir -p help
+
+.PHONY: clean doc $(help_file_mapping)

fnl/bepo.fnl

@@ -36,104 +36,93 @@
   (map-normal key target)
   (map-text-object key target))
 
-(fn mapping-movement []
+(macro 𝛅 [...]
-  ;; on préserve {hjkl} pour les directions
+  "When called with the right context, this will print the documentation of the
-  (map-all :c :h)
+  mappings, instead of attempting to bind. Since we access _G, this needs to be
-  (map-all :t :j)
+  called with --no-compiler-sandbox (see
-  (map-all :s :k)
+  https://fennel-lang.org/reference#compiler-environment)"
-  (map-all :r :l)
+  (fn fun-to-mods [fun]
-  (map-all :C :H)
+    "Converts a function to the modes it sets mappings for"
-  ;; ------
+    (match (tostring fun)
+      :map-text-object :ox
+      :map-visual :v
+      :map-normal :n
+      :map-all :nx
+      other (error (.. "Unsupported function " other))))
+
+  (if _G.gen-doc
+      (let [args [...]
+            docstring (. args 3)
+            (docstring body-pos) (if (= :string (type docstring))
+                                     (values docstring 4)
+                                     (values nil 3))
+            body (-> args (unpack body-pos) (list)
+                     (#(icollect [_ v (pairs $1)]
+                         (match (type v)
+                           :string {:comment v}
+                           :table {:bepo (. v 2)
+                                   :qwerty (. v 3)
+                                   :modes (fun-to-mods (. v 1))}
+                           other (error (.. "Unsupported type" other))))))
+            doc-struct {:fname (. args 1) : docstring : body}]
+        `(local ,doc-struct.fname ,doc-struct))
+      `(fn ,(unpack [...]))))
+
+(𝛅 mapping-movement [] "on préserve {hjkl} pour les directions"
+      (map-all :c :h) (map-all :t :j) (map-all :s :k) (map-all :r :l)
+      (map-all :C :H) ;; ------
       ;; {JKL} devient [TSR]
-  (map-all :T :J)
+      (map-all :T :J) (map-all :S :K) (map-all :R :L) ;; ------
-  (map-all :S :K)
-  (map-all :R :L)
-  ;; ------
       ;; on préserve les variantes avec 'g'
-  (map-all :gt :gj)
+      (map-all :gt :gj) (map-all :gs :gk) ;; ------
-  (map-all :gs :gk)
-  ;; ------
       ;; on préserve les variantes avec 'z'
-  (map-all :zT :zt)
+      (map-all :zT :zt) (map-all :zt :zj) (map-all :zk :zs) (map-all :zs :zk)
-  (map-all :zt :zj)
-  (map-all :zk :zs)
-  (map-all :zs :zk)
       ;; ------
       ;; {t} devient [h] pour être proche de [f]
-  (map-all :h :t)
+      (map-all :h :t) ;; idem pour {T} et [H]
-  ;; idem pour {T} et [H]
+      (map-all :H :T) ;; {c} devient [l]
-  (map-all :H :T)
+      (map-all :l :c) ;; {C} devient [L]
-  ;; {c} devient [l]
+      (map-all :L :C) ;; {j} devient [r]
-  (map-all :l :c)
+      (map-all :j :r) ;; {J} devient [R]
-  ;; {C} devient [L]
+      (map-all :J :R) ;; {k} devient [s]
-  (map-all :L :C)
+      (map-all :k :s) ;; {K} devient [S]
-  ;; {j} devient [r]
-  (map-all :j :r)
-  ;; {J} devient [R]
-  (map-all :J :R)
-  ;; {k} devient [s]
-  (map-all :k :s)
-  ;; {K} devient [S]
       (map-all :K :S))
 
-(fn mapping-tabs []
+(𝛅 mapping-tabs [] ;; le couple [gb]/[gé] agit sur les tabs
-  ;; le couple [gb]/[gé] agit sur les tabs
+      (map-normal :gb :gT) (map-normal "gé" :gt) ;; [gB] va au premier tab
-  (map-normal :gb :gT)
+      (map-normal :gB ":execute \"silent! tabfirst\"<CR>") ;; [gÉ] au dernier
-  (map-normal "gé" :gt)
-  ;; [gB] va au premier tab
-  (map-normal :gB ":execute \"silent! tabfirst\"<CR>")
-  ;; [gÉ] au dernier
       (map-normal "gÉ" ":execute \"silent! tablast\"<CR>")
       ;; [gT] est libéré et peut agir sur les tags
       (map-normal :gT "<C-]>"))
 
-(fn mapping-easy-access []
+(𝛅 mapping-easy-access [] ;; [<] est moins accessible que [«]
-  ;; [<] est moins accessible que [«]
+      (map-normal "«" "<") (map-visual "«" :<gv) ;; idem pour [»] et [>]
-  (map-normal "«" "<")
+      (map-normal "»" ">") (map-visual "»" :>gv)
-  (map-visual "«" "<gv")
-  ;; idem pour [»] et [>]
-  (map-normal "»" ">")
-  (map-visual "»" ">gv")
       ;; idem pour [g,] et [g;] qui sont permutés
-  (map-all "g," "g;")
+      (map-all "g," "g;") (map-all "g;" "g,")
-  (map-all "g;" "g,")
       ;; [w] est peu accessible, on utilise [é]
-  (map-all "é" :w)
+      (map-all "é" :w) ;; idem pour [W] et [É]
-  ;; idem pour [W] et [É]
+      (map-all "É" :W) ;; idem pour [aw] et [aé]
-  (map-all "É" :W)
+      (map-text-object "aé" :aw) ;; idem pour [aW] et [aÉ]
-  ;; idem pour [aw] et [aé]
+      (map-text-object "aÉ" :aW) ;; idem pour [iw] et [ié]
-  (map-text-object "aé" :aw)
+      (map-text-object "ié" :iw) ;; idem pour [iW] et [iÉ]
-  ;; idem pour [aW] et [aÉ]
-  (map-text-object "aÉ" :aW)
-  ;; idem pour [iw] et [ié]
-  (map-text-object "ié" :iw)
-  ;; idem pour [iW] et [iÉ]
       (map-text-object "iÉ" :iW))
 
-(fn mapping-window []
+(𝛅 mapping-window [] ;; [w] est libre pour faire <C-w>
-  ;; [w] est libre pour faire <C-w>
+      (map-normal :w :<C-w>) ;; et [w] pour faire <C-w><C-w>
-  (map-normal :w :<C-w>)
+      (map-normal :W :<C-w><C-w>) ;; on map [w]+direction, miniscule + majuscule
-  ;; et [w] pour faire <C-w><C-w>
+      (map-normal :wc :<C-w>h) (map-normal :wt :<C-w>j) (map-normal :ws :<C-w>k)
-  (map-normal :W :<C-w><C-w>)
+      (map-normal :wr :<C-w>l) (map-normal :wC :<C-w>H) (map-normal :wT :<C-w>J)
-  ;; on map [w]+direction, miniscule + majuscule
+      (map-normal :wS :<C-w>K) (map-normal :wR :<C-w>L)
-  (map-normal :wc :<C-w>h)
-  (map-normal :wt :<C-w>j)
-  (map-normal :ws :<C-w>k)
-  (map-normal :wr :<C-w>l)
-  (map-normal :wC :<C-w>H)
-  (map-normal :wT :<C-w>J)
-  (map-normal :wS :<C-w>K)
-  (map-normal :wR :<C-w>L)
       ;; crée un split _h_orizontal
-  (map-normal :wh :<C-w>s)
+      (map-normal :wh :<C-w>s) ;; va en haut à gauche
-  ;; va en haut à gauche
+      (map-normal "wé" :<C-w>t) ;; déplace sur un nouveau tab
-  (map-normal "wé" :<C-w>t)
-  ;; déplace sur un nouveau tab
       (map-normal "wÉ" :<C-w>T))
 
 (fn setup []
-  "Keys that are still free:
+  "In any case, the following keys are always free for you to remap as you see fit:
-  * , and ; as they may be used as leaders (if you don’t use those as leaders, you may want to swap the two)
+  * , and ; as they may be used as leaders (if you don’t use those as leaders,
+    you may want to swap the two)
   * à and À
   * ç and Ç
   * è and È"

gen_doc.fnl

@@ -0,0 +1,113 @@
+;; bepo.nvim: bepo mapping for neovim
+;; Copyright 2022 Clément Joly
+;;
+;; Licensed under the Apache License, Version 2.0 (the "License");
+;; you may not use this file except in compliance with the License.
+;; You may obtain a copy of the License at
+;;
+;;     http://www.apache.org/licenses/LICENSE-2.0
+;;
+;; Unless required by applicable law or agreed to in writing, software
+;; distributed under the License is distributed on an "AS IS" BASIS,
+;; WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+;; See the License for the specific language governing permissions and
+;; limitations under the License.
+;;
+
+(local fennel (require :fennel))
+
+(fn ==== []
+  (print (string.rep "=" 80)))
+
+(fn ---- []
+  (print (string.rep "-" 80)))
+
+(fn right-align [str max]
+  (let [len (length str)]
+    (.. str (string.rep " " (- max len)))))
+
+(fn print-mapping-struct [struct]
+  (match struct
+    {: bepo : modes : qwerty}
+    (print (string.format "%6s %5s     %s" modes bepo qwerty))
+    _ (error (.. "Received an invalid struct" (fennel.view struct)))))
+
+(fn print-lua-import [name]
+  (->> (values (right-align (string.format "require(\"bepo\").%s()" name) 46)
+               (.. :*bepo.nvim- name "*"))
+       (string.format "%s %35s")
+       (print)))
+
+(set _G.gen-doc true)
+(local bepo (require :fnl/bepo))
+
+;; Content of the help file
+(print "*bepo.nvim*       mappings for the bépo layout <https://bepo.fr>
+
+
+
+Author:   Clément Joly <https://cj.rs/contact>
+Homepage: <https://cj.rs/bepo-nvim>
+License:  APACHE license
+
+
+                                      Type |gO| to see the table of contents.
+")
+
+(====)
+
+(print "USAGE                                                            *bepo.nvim-usage*
+
+For a basic setup with all mappings defined, just add the following to your
+init.lua:
+                                                                 *bepo.nvim-setup*
+
+    require(\"bepo\").setup()
+
+See |bepo.nvim-cherry-pick| to apply only some groups of mapping. By default,
+setup() applies all mapping groups.
+")
+
+(print "                                                           *bepo.nvim-always-free*")
+
+(print (fennel.metadata:get bepo.setup :fnl/docstring))
+(print "")
+
+(====)
+(print "MAPPING CHERRY-PICK                                        *bepo.nvim-cherry-pick*
+
+You can also pick only some groups of mapping, for instance because you have
+your own preferences for some key that don’t match this extension. To apply
+only the “window” and “movement” groups of mapping, use this instead of
+|bepo.nvim-setup| in your init.lua:
+
+    require(\"bepo\").movement()
+    require(\"bepo\").window()
+
+The following subsections go into details of exactly what mappings are
+in each group. “Modes” have the same meaning as in the |map-table|.
+")
+
+(let [tbl (collect [name docstruct (pairs bepo)]
+            (if (= name :setup)
+                nil
+                (values name docstruct)))]
+  (do
+    (table.sort tbl)
+    (each [name docstruct (pairs tbl)]
+      (do
+        (----)
+        (print-lua-import name)
+        (-?> docstruct (?. :docstring) print)
+        (print "")
+        (if (> (length docstruct.body) 0)
+            (print-mapping-struct {:bepo :Bepo :modes :Modes :qwerty :Qwerty}))
+        (each [_ mapping-struct (pairs docstruct.body)]
+          (match mapping-struct
+            {:comment c} (print c)
+            _ (print-mapping-struct mapping-struct)))
+        (print "")))))
+
+;; We split the vim and the : to prevent vim from picking up that for the fennel file
+(print (.. "\nvim" ":tw=78:ts=8:ft=help:norl:"))
+

help/bepo-nvim.txt

@@ -0,0 +1,120 @@
+*bepo.nvim*       mappings for the bépo layout <https://bepo.fr>
+
+
+
+Author:   Clément Joly <https://cj.rs/contact>
+Homepage: <https://cj.rs/bepo-nvim>
+License:  APACHE license
+
+
+                                      Type |gO| to see the table of contents.
+
+================================================================================
+USAGE                                                            *bepo.nvim-usage*
+
+For a basic setup with all mappings defined, just add the following to your
+init.lua:
+                                                                 *bepo.nvim-setup*
+
+    require("bepo").setup()
+
+See |bepo.nvim-cherry-pick| to apply only some groups of mapping. By default,
+setup() applies all mapping groups.
+
+                                                           *bepo.nvim-always-free*
+In any case, the following keys are always free for you to remap as you see fit:
+  * , and ; as they may be used as leaders (if you don’t use those as leaders,
+    you may want to swap the two)
+  * à and À
+  * ç and Ç
+  * è and È
+
+================================================================================
+MAPPING CHERRY-PICK                                        *bepo.nvim-cherry-pick*
+
+You can also pick only some groups of mapping, for instance because you have
+your own preferences for some key that don’t match this extension. To apply
+only the “window” and “movement” groups of mapping, use this instead of
+|bepo.nvim-setup| in your init.lua:
+
+    require("bepo").movement()
+    require("bepo").window()
+
+The following subsections go into details of exactly what mappings are
+in each group. “Modes” have the same meaning as in the |map-table|.
+
+--------------------------------------------------------------------------------
+require("bepo").movement()                                    *bepo.nvim-movement*
+on préserve {hjkl} pour les directions
+
+ Modes  Bepo     Qwerty
+    nx     c     h
+    nx     t     j
+    nx     s     k
+    nx     r     l
+    nx     C     H
+    nx     T     J
+    nx     S     K
+    nx     R     L
+    nx    gt     gj
+    nx    gs     gk
+    nx    zT     zt
+    nx    zt     zj
+    nx    zk     zs
+    nx    zs     zk
+    nx     h     t
+    nx     H     T
+    nx     l     c
+    nx     L     C
+    nx     j     r
+    nx     J     R
+    nx     k     s
+    nx     K     S
+
+--------------------------------------------------------------------------------
+require("bepo").window()                                        *bepo.nvim-window*
+
+ Modes  Bepo     Qwerty
+     n     w     <C-w>
+     n     W     <C-w><C-w>
+     n    wc     <C-w>h
+     n    wt     <C-w>j
+     n    ws     <C-w>k
+     n    wr     <C-w>l
+     n    wC     <C-w>H
+     n    wT     <C-w>J
+     n    wS     <C-w>K
+     n    wR     <C-w>L
+     n    wh     <C-w>s
+     n   wé     <C-w>t
+     n   wÉ     <C-w>T
+
+--------------------------------------------------------------------------------
+require("bepo").easy_access()                              *bepo.nvim-easy_access*
+
+ Modes  Bepo     Qwerty
+     n    «     <
+     v    «     <gv
+     n    »     >
+     v    »     >gv
+    nx    g,     g;
+    nx    g;     g,
+    nx    é     w
+    nx    É     W
+    ox   aé     aw
+    ox   aÉ     aW
+    ox   ié     iw
+    ox   iÉ     iW
+
+--------------------------------------------------------------------------------
+require("bepo").tabs()                                            *bepo.nvim-tabs*
+
+ Modes  Bepo     Qwerty
+     n    gb     gT
+     n   gé     gt
+     n    gB     :execute "silent! tabfirst"<CR>
+     n   gÉ     :execute "silent! tablast"<CR>
+     n    gT     <C-]>
+
+
+vim:tw=78:ts=8:ft=help:norl: