Generate keybinding documentation (#162)

* Show live-generated keybinding docs on META+/

* Free doc and label as needed

* Use 'local' in lua

* Mention ALTMETA

* avoid `io.output`

* Generate a random filename

Author: raboof

etc/cfg_bindings.lua

@@ -20,21 +20,42 @@
 -- modifier to some of the F-key bindings.
 
 defbindings("WScreen", {
-    bdoc("Switch to n:th object (workspace, full screen client window) "..
-         "within current screen."),
+    bdoc("Switch to object 0 (workspace, full screen client window) "..
+         "within current screen.", "ws 0"),
     kpress(META.."1", "WScreen.switch_nth(_, 0)"),
+    bdoc("Switch to object 1 (workspace, full screen client window) "..
+         "within current screen.", "ws 1"),
     kpress(META.."2", "WScreen.switch_nth(_, 1)"),
+    bdoc("Switch to object 2 (workspace, full screen client window) "..
+         "within current screen.", "ws 2"),
     kpress(META.."3", "WScreen.switch_nth(_, 2)"),
+    bdoc("Switch to object 3 (workspace, full screen client window) "..
+         "within current screen.", "ws 3"),
     kpress(META.."4", "WScreen.switch_nth(_, 3)"),
+    bdoc("Switch to object 4 (workspace, full screen client window) "..
+         "within current screen.", "ws 4"),
     kpress(META.."5", "WScreen.switch_nth(_, 4)"),
+    bdoc("Switch to object 5 (workspace, full screen client window) "..
+         "within current screen.", "ws 5"),
     kpress(META.."6", "WScreen.switch_nth(_, 5)"),
+    bdoc("Switch to object 6 (workspace, full screen client window) "..
+         "within current screen.", "ws 6"),
     kpress(META.."7", "WScreen.switch_nth(_, 6)"),
+    bdoc("Switch to object 7 (workspace, full screen client window) "..
+         "within current screen.", "ws 7"),
     kpress(META.."8", "WScreen.switch_nth(_, 7)"),
+    bdoc("Switch to object 8 (workspace, full screen client window) "..
+         "within current screen.", "ws 8"),
     kpress(META.."9", "WScreen.switch_nth(_, 8)"),
+    bdoc("Switch to object 9 (workspace, full screen client window) "..
+         "within current screen.", "ws 9"),
     kpress(META.."0", "WScreen.switch_nth(_, 9)"),
 
-    bdoc("Switch to next/previous object within current screen."),
+    bdoc("Switch to next object (workspace, full screen client window) "..
+         "within current screen.", "->ws"),
     kpress(META.."grave", "WScreen.switch_next(_)"),
+    bdoc("Switch to previous object (workspace, full screen client window) "..
+         "within current screen.", "<-ws"),
     kpress(ALTMETA.."asciitilde", "WScreen.switch_prev(_)"),
 
     submap(META.."O", {
@@ -51,18 +72,22 @@ defbindings("WScreen", {
 
     }),
 
-    bdoc("Go to n:th screen on multihead setup."),
-    kpress(META.."Shift+1", "ioncore.goto_nth_screen(0)"),
+    bdoc("Go to screen 0 on multihead setup.", "scr 0"),
+    kpress(ALTMETA.."1", "ioncore.goto_nth_screen(0)"),
     kpress(META.."F1", "ioncore.goto_nth_screen(0)"),
-    kpress(META.."Shift+2", "ioncore.goto_nth_screen(1)"),
+    bdoc("Go to screen 1 on multihead setup.", "scr 1"),
+    kpress(ALTMETA.."2", "ioncore.goto_nth_screen(1)"),
     kpress(META.."F2", "ioncore.goto_nth_screen(1)"),
-    kpress(META.."Shift+3", "ioncore.goto_nth_screen(2)"),
+    bdoc("Go to screen 2 on multihead setup.", "scr 2"),
+    kpress(ALTMETA.."3", "ioncore.goto_nth_screen(2)"),
     kpress(META.."F3", "ioncore.goto_nth_screen(2)"),
-    kpress(META.."Shift+4", "ioncore.goto_nth_screen(3)"),
+    bdoc("Go to screen 3 on multihead setup.", "scr 3"),
+    kpress(ALTMETA.."4", "ioncore.goto_nth_screen(3)"),
     -- kpress(META.."F4", "ioncore.goto_nth_screen(3)"),
 
-    bdoc("Go to next/previous screen on multihead setup."),
+    bdoc("Go to previous screen on multihead setup.", "<-scr"),
     kpress(ALTMETA.."Escape", "ioncore.goto_prev_screen()"),
+    bdoc("Go to next screen on multihead setup.", "->scr"),
     kpress(META.."Escape", "ioncore.goto_next_screen()"),
 
     bdoc("Create a new workspace of chosen default type."),
@@ -76,7 +101,7 @@ defbindings("WScreen", {
     bdoc("Display the window list menu."),
     mpress("Button2", "mod_menu.pmenu(_, _sub, 'windowlist')"),
 
-    bdoc("Forward-circulate focus."),
+    bdoc("Forward-circulate focus.", "->frame"),
     -- '_chld' used here stands to for an actual child window that may not
     -- be managed by the screen itself, unlike '_sub', that is likely to be
     -- the managing group of that window. The right/left directions are
@@ -85,11 +110,11 @@ defbindings("WScreen", {
     kpress(META.."Tab", "ioncore.goto_next(_chld, 'right')",
            "_chld:non-nil"),
 
-    bdoc("Backward-circulate focus."),
+    bdoc("Backward-circulate focus.", "<-frame"),
     kpress(ALTMETA.."Tab", "ioncore.goto_next(_chld, 'left')",
            "_chld:non-nil"),
 
-    bdoc("Raise focused object, if possible."),
+    bdoc("Raise focused object, if possible.", "raise"),
     kpress(ALTMETA.."R", "WRegion.rqorder(_chld, 'front')",
            "_chld:non-nil"),
 })
@@ -101,22 +126,22 @@ defbindings("WScreen", {
 
 defbindings("WClientWin", {
     bdoc("Nudge the client window. This might help with some "..
-      "programs' resizing problems."),
+      "programs' resizing problems.", "nudge"),
     kpress_wait(ALTMETA.."L", "WClientWin.nudge(_)"),
 
-    bdoc("Kill client owning the client window."),
+    bdoc("Kill client owning the client window.", "kill"),
     kpress(ALTMETA.."C", "WClientWin.kill(_)"),
 
     bdoc("Send next key press to the client window. "..
-         "Some programs may not allow this by default."),
+         "Some programs may not allow this by default.", "quote"),
     kpress(ALTMETA.."Q", "WClientWin.quote_next(_)"),
 })
 
 
 -- Client window group bindings
 
 defbindings("WGroupCW", {
-    bdoc("Toggle client window group full-screen mode"),
+    bdoc("Toggle client window group full-screen mode", "fullscr"),
     kpress_wait(META.."Q", "WGroup.set_fullscreen(_, 'toggle')"),
 })
 
@@ -127,10 +152,10 @@ defbindings("WGroupCW", {
 -- contexts/objects always gets to handle the key press.
 
 defbindings("WMPlex", {
-    bdoc("Close current object."),
+    bdoc("Close current object.", "close"),
     kpress_wait(META.."C", "WRegion.rqclose_propagate(_, _sub)"),
 
-    bdoc("Detach (float) or reattach an object to its previous location."),
+    bdoc("Detach (float) or reattach an object to its previous location.", "detach"),
     -- By using _chld instead of _sub, we can detach/reattach queries
     -- attached to a group. The detach code checks if the parameter
     -- (_chld) is a group 'bottom' and detaches the whole group in that
@@ -141,52 +166,56 @@ defbindings("WMPlex", {
 -- Frames for transient windows ignore this bindmap
 
 defbindings("WMPlex.toplevel", {
-    bdoc("Toggle tag of current object."),
+    bdoc("Toggle tag of current object.", "tag"),
     kpress(META.."T", "WRegion.set_tagged(_sub, 'toggle')", "_sub:non-nil"),
 
-    bdoc("Clear all tags."),
+    bdoc("Clear all tags.", "-tags"),
     kpress(ALTMETA.."T", "ioncore.clear_tags()"),
 
-    bdoc("Lock screen"),
+    bdoc("Lock screen", "lock"),
     kpress(META.."L", "notioncore.exec_on(_, notioncore.lookup_script('notion-lock'))"),
 
-    bdoc("Run a terminal emulator."),
+    bdoc("Run a terminal emulator.", "xterm"),
     kpress(META.."Return", "mod_query.exec_on_merr(_, XTERM or 'xterm')"),
     kpress("F2", "mod_query.exec_on_merr(_, XTERM or 'xterm')"),
 
-    bdoc("Query for command line to execute."),
+    bdoc("Query for command line to execute.", "run"),
     kpress(META.."J", "mod_query.query_exec(_)"),
 
-    bdoc("Query for Lua code to execute."),
+    bdoc("Query for Lua code to execute.", "lua"),
     kpress(ALTMETA.."J", "mod_query.query_lua(_)"),
 
-    bdoc("Query for host to connect to with SSH."),
+    bdoc("Query for host to connect to with SSH.", "ssh"),
     kpress(ALTMETA.."F4", "mod_query.query_ssh(_, ':ssh')"),
 
-    bdoc("Query for file to edit."),
+    bdoc("Query for file to edit.", "edit"),
     kpress(ALTMETA.."F5",
            "mod_query.query_editfile(_, 'run-mailcap --action=edit')"),
 
-    bdoc("Query for file to view."),
+    bdoc("Query for file to view.", "view"),
     kpress(ALTMETA.."F6",
            "mod_query.query_runfile(_, 'run-mailcap --action=view')"),
 
-    bdoc("Query for keybinding."),
+    bdoc("Query for keybinding.", "qkb"),
     kpress(META.."F7",
            "mod_query.query_binding(_, _sub)"),
 
-    bdoc("Query for workspace to go to or create a new one."),
+    bdoc("Query for workspace to go to or create a new one.", "+ws"),
     kpress(ALTMETA.."F9", "mod_query.query_workspace(_)"),
 
-    bdoc("Query for a client window to go to."),
+    bdoc("Query for a client window to go to.", "go"),
     kpress(META.."G", "mod_query.query_gotoclient(_)"),
 
-    bdoc("Display context menu."),
-    kpress(META.."M", "mod_menu.menu(_, _sub, 'ctxmenu')"),
-    kpress(ALTMETA.."M", "mod_query.query_menu(_, _sub, 'ctxmenu', 'Context menu:')"),
+    bdoc("Display context menu.", "ctx"),
+    kpress(META.."C", "mod_menu.menu(_, _sub, 'ctxmenu')"),
+    bdoc("Query for context menu.", "qctx"),
+    kpress(ALTMETA.."C", "mod_query.query_menu(_, _sub, 'ctxmenu', 'Context menu:')"),
+
+    bdoc("Show Notion 'live docs'.", "help"),
+    kpress(META.."slash", "notioncore.show_live_docs(_)"),
 
-    bdoc("Query for manual page to be displayed."),
-    kpress(META.."slash", "mod_query.query_man(_, ':man')"),
+    bdoc("Query for manual page to be displayed.", "man"),
+    kpress(ALTMETA.."slash", "mod_query.query_man(_, ':man')"),
 }) 
 
 -- WFrame context bindings
@@ -195,14 +224,15 @@ defbindings("WMPlex.toplevel", {
 -- frame bindings are found in some modules' configuration files.
 
 defbindings("WFrame", {
-    bdoc("Maximize the frame horizontally/vertically."),
+    bdoc("Maximize the frame horizontally.", "hmax"),
     kpress(ALTMETA.."H", "WFrame.maximize_horiz(_)"),
+    bdoc("Maximize the frame vertically.", "vmax"),
     kpress(ALTMETA.."V", "WFrame.maximize_vert(_)"),
 
     bdoc("Display context menu."),
     mpress("Button3", "mod_menu.pmenu(_, _sub, 'ctxmenu')"),
 
-    bdoc("Begin move/resize mode."),
+    bdoc("Begin move/resize mode.", "resize"),
     kpress(META.."R", "WFrame.begin_kbresize(_)"),
 
     bdoc("Switch the frame to display the object indicated by the tab."),
@@ -220,34 +250,42 @@ defbindings("WFrame", {
     mdrag("Button1@tab", "WFrame.p_tabdrag(_)"),
     mdrag("Button2@tab", "WFrame.p_tabdrag(_)"),
 
-    bdoc("Switch to next/previous object within the frame."),
+    bdoc("Switch to next object within the frame.", "->tab"),
     -- See docs on how to disable capslock caps behaviour
     kpress(META.."Caps_Lock", "WFrame.switch_next(_)"),
     mclick(META.."Button4", "WFrame.switch_next(_)"),
+
+    bdoc("Switch to previous object within the frame.", "<-tab"),
+    kpress(ALTMETA.."Caps_Lock", "WFrame.switch_prev(_)"),
     mclick(META.."Button5", "WFrame.switch_prev(_)"),
 })
 
 -- Frames for transient windows ignore this bindmap
 
 defbindings("WFrame.toplevel", {
-    bdoc("Query for a client window to attach ('nick')."),
+    bdoc("Query for a client window to attach ('nick').", "nick"),
     kpress(META.."N", "mod_query.query_attachclient(_)"),
 
+    bdoc("Switch to tab 0 in this frame.", "tab 0"),
     kpress(META.."A", "WFrame.switch_nth(_, 0)"),
+    bdoc("Switch to tab 1 in this frame.", "tab 1"),
     kpress(META.."S", "WFrame.switch_nth(_, 1)"),
+    bdoc("Switch to tab 2 in this frame.", "tab 2"),
     kpress(META.."D", "WFrame.switch_nth(_, 2)"),
+    bdoc("Switch to tab 3 in this frame.", "tab 3"),
     kpress(META.."F", "WFrame.switch_nth(_, 3)"),
 
-    bdoc("Move current object within the frame left/right."),
+    bdoc("Move current tab to the right within the frame.", "tab->"),
     kpress(ALTMETA.."comma", "WFrame.dec_index(_, _sub)", "_sub:non-nil"),
+    bdoc("Move current tab to the left within the frame.", "tab<-"),
     kpress(ALTMETA.."period", "WFrame.inc_index(_, _sub)", "_sub:non-nil"),
 
     bdoc("Maximize the frame horizontally/vertically."),
     kpress(ALTMETA.."H", "WFrame.maximize_horiz(_)"),
     kpress(ALTMETA.."V", "WFrame.maximize_vert(_)"),
 
     bdoc("Attach tagged objects to this frame."),
-    kpress(META.."Y", "ioncore.tagged_attach(_)"),
+    kpress(META.."N", "ioncore.tagged_attach(_)"),
 })
 
 -- Bindings for floating frames

etc/cfg_tiling.lua

@@ -4,28 +4,27 @@
 
 -- Bindings for the tilings.
 defbindings("WTiling", {
-    bdoc("Split current frame horizontally."),
+    bdoc("Split current frame horizontally.", "hsplit"),
     kpress(META.."I", "WTiling.split_at(_, _sub, 'right', true)"),
 
-    bdoc("Split current frame vertically."),
+    bdoc("Split current frame vertically.", "vsplit"),
     kpress(ALTMETA.."I", "WTiling.split_at(_, _sub, 'bottom', true)"),
 
-    bdoc("Destroy current frame."),
+    bdoc("Destroy current frame.", "unsplit"),
     kpress(META.."X", "WTiling.unsplit_at(_, _sub)"),
 
-    bdoc("Go to frame above/below current frame."),
+    bdoc("Go to frame below current frame.", "vframe"),
     kpress(META.."W", "ioncore.goto_next(_sub, 'down', {no_ascend=_})"),
+    bdoc("Go to frame above current frame.", "^frame"),
     kpress(ALTMETA.."W", "ioncore.goto_next(_sub, 'up', {no_ascend=_})"),
     mclick(META.."Shift+Button4", "ioncore.goto_next(_sub, 'up', {no_ascend=_})"),
     mclick(META.."Shift+Button5", "ioncore.goto_next(_sub, 'down', {no_ascend=_})"),
 })
 
 -- Frame bindings.
 defbindings("WFrame.floating", {
-    submap(META.."K", {
-        bdoc("Tile frame, if no tiling exists on the workspace"),
-        kpress("B", "mod_tiling.mkbottom(_)"),
-    }),
+    bdoc("Tile frame, if no tiling exists on the workspace", "tile"),
+    kpress(ALTMETA.."B", "mod_tiling.mkbottom(_)"),
 })
 
 -- Context menu for tiled workspaces.

ioncore/binding.c

@@ -163,6 +163,14 @@ void binding_deinit(WBinding *binding)
         bindmap_destroy(binding->submap);
         binding->submap=NULL;
     }
+    if(binding->doc){
+        free(binding->doc);
+        binding->doc=NULL;
+    }
+    if(binding->label){
+        free(binding->label);
+        binding->label=NULL;
+    }
 
     binding->func=extl_unref_fn(binding->func);
 }
@@ -171,7 +179,9 @@ void binding_deinit(WBinding *binding)
 static void do_destroy_binding(WBinding *binding)
 {
     assert(binding!=NULL);
+
     binding_deinit(binding);
+
     free(binding);
 }
 

ioncore/binding.h

@@ -44,6 +44,7 @@ DECLSTRUCT(WBinding){
     WBindmap *submap;
     ExtlFn func;
     const char *doc;
+    const char *label;
 };
 
 

ioncore/bindmaps.c

@@ -217,6 +217,7 @@ WBindmap *ioncore_create_cycle_bindmap(uint kcb, uint state,
     b.submap=NULL;
     b.func=extl_ref_fn(cycle);
     b.doc=NULL;
+    b.label=NULL;
 
     if(!bindmap_add_binding(bindmap, &b)){
         extl_unref_fn(b.func);