[PATCH v4 1/3] ox-texinfo: Add function for use by kbd macro

[Jonas Bernoulli <jonas@bernoul.li>]

* doc/doc-setup.org: Use org-texinfo-kbd-macro for kbd macro.
* doc/org-manual.org: Add new node "Key bindings in Texinfo export".
* lisp/ox-texinfo.el (org-texinfo--quoted-keys-regexp): New variable.
* lisp/ox-texinfo.el (org-texinfo-kbd-macro): New function.
---
 doc/doc-setup.org  |  2 +-
 doc/org-manual.org | 27 +++++++++++++++++++++++++++
 lisp/ox-texinfo.el | 30 +++++++++++++++++++++++++++++-
 3 files changed, 57 insertions(+), 2 deletions(-)

diff --git a/doc/doc-setup.org b/doc/doc-setup.org
index 9d15505e2..786a0cb14 100644
--- a/doc/doc-setup.org
+++ b/doc/doc-setup.org
@@ -49,5 +49,5 @@
 
 # The "kbd" macro turns KBD into @kbd{KBD}.  Additionally, it
 # encloses case-sensitive special keys (SPC, RET...) within @key{...}.
-#+macro: kbd (eval (let ((case-fold-search nil) (regexp (regexp-opt '("SPC" "RET" "LFD" "TAB" "BS" "ESC" "DELETE" "SHIFT" "Ctrl" "Meta" "Alt" "Cmd" "Super" "UP" "LEFT" "RIGHT" "DOWN") 'words))) (format "@@texinfo:@kbd{@@%s@@texinfo:}@@" (replace-regexp-in-string regexp "@@texinfo:@key{@@\\&@@texinfo:}@@" $1 t))))
+#+macro: kbd (eval (org-texinfo-kbd-macro $1))
 
diff --git a/doc/org-manual.org b/doc/org-manual.org
index b4c20f252..e88cf1ed9 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -15353,6 +15353,33 @@ your king.
 ,#+END_QUOTE
 #+end_example
 
+*** Key bindings in Texinfo export
+:PROPERTIES:
+:DESCRIPTION: @@kbd Texinfo command.
+:END:
+
+Org does not provide any markup for key bindings that corresponds to
+Texinfo's ~@kbd~ and ~@key~ commands.  One way to deal with this is to
+fall back to code syntax.  =~C-x SPC~=, for example, is transcoded to
+~@code{C-x SPC}~.
+
+A better approach is to define and use an Org macro named ~kbd~.  To
+make that easier the function ~org-texinfo-kbd-macro~ is provided,
+which is intended to be used like this:
+
+#+begin_example
+#+macro: kbd (eval (org-texinfo-kbd-macro $1))
+
+Type {{{kbd(C-c SPC)}}}.
+#+end_example
+
+#+texinfo: @noindent
+which becomes
+
+#+begin_example
+Type @kbd{C-c @key{SPC}}.
+#+end_example
+
 *** Special blocks in Texinfo export
 :PROPERTIES:
 :DESCRIPTION: Special block attributes.
diff --git a/lisp/ox-texinfo.el b/lisp/ox-texinfo.el
index 46806ccca..ddd405d05 100644
--- a/lisp/ox-texinfo.el
+++ b/lisp/ox-texinfo.el
@@ -407,6 +407,13 @@ (defconst org-texinfo-inline-image-rules
 	      (regexp-opt '("eps" "pdf" "png" "jpg" "jpeg" "gif" "svg"))))
   "Rules characterizing image files that can be inlined.")
 
+(defvar org-texinfo--quoted-keys-regexp
+  (regexp-opt '("BS" "TAB" "RET" "ESC" "SPC" "DEL"
+		"LFD" "DELETE" "SHIFT" "Ctrl" "Meta" "Alt"
+		"Cmd" "Super" "UP" "LEFT" "RIGHT" "DOWN")
+	      'words)
+  "Regexp matching keys that have to be quoted using @key{KEY}.")
+
 \f
 ;;; Internal Functions
 
@@ -1611,7 +1618,28 @@ (defun org-texinfo-verse-block (_verse-block contents _info)
   (format "@display\n%s@end display" contents))
 
 \f
-;;; Interactive functions
+;;; Public Functions
+
+(defun org-texinfo-kbd-macro (key &optional noquote)
+  "Quote KEY using @kbd{...} and if necessary @key{...}.
+
+This is intended to be used as an Org macro like so:
+
+  #+macro: kbd (eval (org-texinfo-kbd-macro $1))
+  Type {{{kbd(C-c SPC)}}}.
+
+Also see info node `(org)Key bindings in Texinfo export'.
+
+If optional NOQOUTE is non-nil, then do not add the quoting
+that is necessary when using this in an Org macro."
+  (format (if noquote "@kbd{%s}" "@@texinfo:@kbd{@@%s@@texinfo:}@@")
+	  (let ((case-fold-search nil))
+	    (replace-regexp-in-string
+	     org-texinfo--quoted-keys-regexp
+	     (if noquote "@key{\\&}" "@@texinfo:@key{@@\\&@@texinfo:}@@")
+	     key t))))
+
+;;; Interactive Functions
 
 ;;;###autoload
 (defun org-texinfo-export-to-texinfo
-- 
2.34.1