[RFC] New "kbd" macro?

[RFC] New "kbd" macro?

[Nicolas Goaziou]

[-- Attachment #1: Type: text/plain, Size: 1132 bytes --]

Hello,

I would like to submit a new minor macro for integration within Org: the
"kbd" macro.

The "kbd" macro focuses on normalizing keybinding during export. For
example, during Texinfo export, {{{kbd(v SPC)}}} becomes 

  @kbd{v @key{SPC}}

whereas in another back-end, it becomes

  v <SPC>

More specifically:

  Within {{{kbd(...)}}}, the following case-sensitive keys are wrapped
  within angle brackets: SPC, RET, LFD, TAB, BS, ESC, DELETE, SHIFT,
  CTRL, META, up, down, left, right.

With an optional argument, it can wrap the key-binding within verbatim
or code markup:

  {{{kbd(v SPC,code)}}}      =>  ~v <SPC>~

  {{{kbd(v SPC,verbatim)}}}  =>  =v <SPC>=

Other markup is not implemented because, in that case, you can wrap
appropriate characters around the macro.

Granted, this is probably only useful for Texinfo export, but defining
it as a global macro makes Org documents a bit more portable across
export back-ends.

If there is any interest in it, I will add tests and documentation.
I attach a proof of concept.

WDYT?


Regards,

-- 
Nicolas Goaziou                                                0x80A93738

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: implement kbd macro --]
[-- Type: text/x-diff, Size: 2969 bytes --]

From be6192293c41a3d252572a0fdbed7ac5b7a0c6bd Mon Sep 17 00:00:00 2001
From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
Date: Wed, 13 Sep 2017 13:01:59 +0200
Subject: [PATCH] org-macro: Implement kbd macro

* lisp/org-macro.el (org-macro--special-keys-re): New variable.
(org-macro--kbd): New function.
(org-macro-initialize-templates): Use new function.
---
 lisp/org-macro.el | 41 +++++++++++++++++++++++++++++++++++++++--
 1 file changed, 39 insertions(+), 2 deletions(-)

diff --git a/lisp/org-macro.el b/lisp/org-macro.el
index 3453e5e07..cad38cdd2 100644
--- a/lisp/org-macro.el
+++ b/lisp/org-macro.el
@@ -64,6 +64,8 @@
 (declare-function vc-call "vc-hooks" (fun file &rest args) t)
 (declare-function vc-exec-after "vc-dispatcher" (code))
 
+(defvar org-export-current-backend)
+
 ;;; Variables
 
 (defvar-local org-macro-templates nil
@@ -164,6 +166,9 @@ function installs the following ones: \"property\",
     (org-macro--counter-initialize)
     (funcall update-templates
 	     (cons "n" "(eval (org-macro--counter-increment \"$1\" \"$2\"))"))
+    ;; Install "kbd" macro.
+    (funcall update-templates
+	     (cons "kbd" "(eval (org-macro--kbd \"$1\" \"$2\"))"))
     (setq org-macro-templates templates)))
 
 (defun org-macro-expand (macro templates)
@@ -294,6 +299,15 @@ Return a list of arguments, as strings.  This is the opposite of
 \f
 ;;; Helper functions and variables for internal macros
 
+(defvar org-macro--counter-table nil
+  "Hash table containing counter value per name.")
+
+(defconst org-macro--special-keys-re
+  (regexp-opt
+   '("SPC" "RET" "LFD" "TAB" "BS" "ESC" "DELETE" "SHIFT" "CTRL" "META"
+     "up" "left" "right" "down"))
+  "Regexp matching special keyboard keys.")
+
 (defun org-macro--vc-modified-time (file)
   (save-window-excursion
     (when (vc-backend file)
@@ -318,8 +332,31 @@ Return a list of arguments, as strings.  This is the opposite of
 	  (kill-buffer buf))
 	date))))
 
-(defvar org-macro--counter-table nil
-  "Hash table containing counter value per name.")
+(defun org-macro--kbd (kbd wrap)
+  "Return normalized keyboard sequence KBD.
+
+KBD is a string.  Within KBD, the following case-sensitive keys
+are wrapped within angle brackets: SPC, RET, LFD, TAB, BS, ESC,
+DELETE, SHIFT, CTRL, META, up, down, left, right.
+
+When WRAP is \"code\", the whole sequence is surrounded with
+\"~\" markers.  If WRAP is \"verbatim\", the sequence is
+surrounded with \"=\" markers."
+  (let* ((case-fold-search nil)
+	 (template
+	  (pcase wrap
+	    ("code" "~%s~")
+	    ("verbatim" "=%s=")
+	    (_ "%s"))))
+    (format template
+	    (pcase org-export-current-backend
+	      (`texinfo
+	       (format "@@texinfo:@kbd{%s}@@"
+		       (replace-regexp-in-string
+			org-macro--special-keys-re "@key{\\&}" kbd t)))
+	      (_
+	       (replace-regexp-in-string
+		org-macro--special-keys-re "<\\&>" kbd t))))))
 
 (defun org-macro--counter-initialize ()
   "Initialize `org-macro--counter-table'."
-- 
2.14.1

Re: [RFC] New "kbd" macro?

[Kaushal Modi]

[-- Attachment #1: Type: text/plain, Size: 1504 bytes --]

On Wed, Sep 13, 2017 at 9:23 AM Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

> Hello,
>
> I would like to submit a new minor macro for integration within Org: the
> "kbd" macro.
>

Awesome!


> The "kbd" macro focuses on normalizing keybinding during export. For
> example, during Texinfo export, {{{kbd(v SPC)}}} becomes
>
>   @kbd{v @key{SPC}}
>
> whereas in another back-end, it becomes
>
>   v <SPC>
>

Can we have {{{kbd(v SPC)}}} export to below for HTML?

<kbd>v <span class="key">SPC</span></kbd>

It will be tremendously useful for blog posts. At the moment, I use this
hack[1] in ox-hugo.el.

*Also stuff within angle brackets will hide in HTML if you choose to leave
the export as "v <SPC>" for HTML too!*

More specifically:
>
>   Within {{{kbd(...)}}}, the following case-sensitive keys are wrapped
>   within angle brackets: SPC, RET, LFD, TAB, BS, ESC, DELETE, SHIFT,
>   CTRL, META, up, down, left, right.
>
> With an optional argument, it can wrap the key-binding within verbatim
> or code markup:
>
>   {{{kbd(v SPC,code)}}}      =>  ~v <SPC>~
>
>   {{{kbd(v SPC,verbatim)}}}  =>  =v <SPC>=
>

Looks good.

Granted, this is probably only useful for Texinfo export, but defining
> it as a global macro makes Org documents a bit more portable across
> export back-ends.
>

For HTML too! :)

If there is any interest in it, I will add tests and documentation.
> I attach a proof of concept.
>

+1

Copying Oleh, as I believe he would also have some interest in this.
-- 

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 2782 bytes --]

Re: [RFC] New "kbd" macro?

[Kaushal Modi]

[-- Attachment #1: Type: text/plain, Size: 785 bytes --]

Oh, and the reference to [1] that I forgot to paste..

[1]:
https://github.com/kaushalmodi/ox-hugo/blob/a486141e4e2c3f9f67e799e20af150611d77f850/ox-hugo.el#L535-L542

On Wed, Sep 13, 2017 at 10:03 AM Kaushal Modi <kaushal.modi@gmail.com>
wrote:

> On Wed, Sep 13, 2017 at 9:23 AM Nicolas Goaziou <mail@nicolasgoaziou.fr>
> wrote:
>
>>
>> The "kbd" macro focuses on normalizing keybinding during export. For
>> example, during Texinfo export, {{{kbd(v SPC)}}} becomes
>>
>>   @kbd{v @key{SPC}}
>>
>> whereas in another back-end, it becomes
>>
>>   v <SPC>
>>
>
> Can we have {{{kbd(v SPC)}}} export to below for HTML?
>
> <kbd>v <span class="key">SPC</span></kbd>
>
> It will be tremendously useful for blog posts. At the moment, I use this
> hack[1] in ox-hugo.el.
>
-- 

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 1992 bytes --]

Re: [RFC] New "kbd" macro?

[Eric S Fraga]

[-- Attachment #1: Type: text/plain, Size: 533 bytes --]

On Wednesday, 13 Sep 2017 at 15:22, Nicolas Goaziou wrote:
> Hello,
>
> I would like to submit a new minor macro for integration within Org: the
> "kbd" macro.

My first inclination was to say that something like this belongs in
org-contrib (or on Worg, I guess) but if there is a need for this for
the texinfo exporter, why not include it?  It has no impact on anything
else as far as I can tell?  And it seems that others would find it
useful in any case.

eric

-- 
: Eric S Fraga via Emacs 26.0.50, Org release_9.0.9-573-g09e612

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 194 bytes --]

Re: [RFC] New "kbd" macro?

[Nicolas Goaziou]

[-- Attachment #1: Type: text/plain, Size: 384 bytes --]

Hello,

Kaushal Modi <kaushal.modi@gmail.com> writes:

> Can we have {{{kbd(v SPC)}}} export to below for HTML?
>
> <kbd>v <span class="key">SPC</span></kbd>

Good idea. New patch follows.

> *Also stuff within angle brackets will hide in HTML if you choose to leave
> the export as "v <SPC>" for HTML too!*

Indeed. This is fixed per the change above.

Regards,

-- 
Nicolas Goaziou

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: implement kbd macro --]
[-- Type: text/x-diff, Size: 3271 bytes --]

From 7caa7028ac496354fbe8a20eb98f63e306b9e021 Mon Sep 17 00:00:00 2001
From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
Date: Wed, 13 Sep 2017 13:01:59 +0200
Subject: [PATCH] org-macro: Implement kbd macro

* lisp/org-macro.el (org-macro--special-keys-re): New variable.
(org-macro--kbd): New function.
(org-macro-initialize-templates): Use new function.
---
 lisp/org-macro.el | 47 +++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 45 insertions(+), 2 deletions(-)

diff --git a/lisp/org-macro.el b/lisp/org-macro.el
index 3453e5e07..3da09910a 100644
--- a/lisp/org-macro.el
+++ b/lisp/org-macro.el
@@ -64,6 +64,8 @@
 (declare-function vc-call "vc-hooks" (fun file &rest args) t)
 (declare-function vc-exec-after "vc-dispatcher" (code))
 
+(defvar org-export-current-backend)
+
 ;;; Variables
 
 (defvar-local org-macro-templates nil
@@ -164,6 +166,9 @@ function installs the following ones: \"property\",
     (org-macro--counter-initialize)
     (funcall update-templates
 	     (cons "n" "(eval (org-macro--counter-increment \"$1\" \"$2\"))"))
+    ;; Install "kbd" macro.
+    (funcall update-templates
+	     (cons "kbd" "(eval (org-macro--kbd \"$1\" \"$2\"))"))
     (setq org-macro-templates templates)))
 
 (defun org-macro-expand (macro templates)
@@ -294,6 +299,16 @@ Return a list of arguments, as strings.  This is the opposite of
 \f
 ;;; Helper functions and variables for internal macros
 
+(defvar org-macro--counter-table nil
+  "Hash table containing counter value per name.")
+
+(defconst org-macro--special-keys-re
+  (regexp-opt
+   '("SPC" "RET" "LFD" "TAB" "BS" "ESC" "DELETE" "SHIFT" "CTRL" "META"
+     "up" "left" "right" "down")
+   'words)
+  "Regexp matching special keyboard keys.")
+
 (defun org-macro--vc-modified-time (file)
   (save-window-excursion
     (when (vc-backend file)
@@ -318,8 +333,36 @@ Return a list of arguments, as strings.  This is the opposite of
 	  (kill-buffer buf))
 	date))))
 
-(defvar org-macro--counter-table nil
-  "Hash table containing counter value per name.")
+(defun org-macro--kbd (kbd wrap)
+  "Return normalized keyboard sequence KBD.
+
+KBD is a string.  Within KBD, the following case-sensitive keys
+are wrapped within angle brackets: SPC, RET, LFD, TAB, BS, ESC,
+DELETE, SHIFT, CTRL, META, up, down, left, right.
+
+When WRAP is \"code\", the whole sequence is surrounded with
+\"~\" markers.  If WRAP is \"verbatim\", the sequence is
+surrounded with \"=\" markers."
+  (let* ((case-fold-search nil)
+	 (template
+	  (pcase (org-trim wrap)
+	    ("code" "~%s~")
+	    ("verbatim" "=%s=")
+	    (_ "%s"))))
+    (format template
+	    (cond
+	     ((org-export-derived-backend-p org-export-current-backend 'texinfo)
+	      (format "@@texinfo:@kbd{%s}@@"
+		      (replace-regexp-in-string
+		       org-macro--special-keys-re "@key{\\&}" kbd t)))
+	     ((org-export-derived-backend-p org-export-current-backend 'html)
+	      (format "@@html:<kbd>%s</kbd>@@"
+		      (replace-regexp-in-string
+		       org-macro--special-keys-re
+		       "<span class=\"key\">\\&</span>" kbd t)))
+	     (t
+	      (replace-regexp-in-string
+	       org-macro--special-keys-re "<\\&>" kbd t))))))
 
 (defun org-macro--counter-initialize ()
   "Initialize `org-macro--counter-table'."
-- 
2.14.1

Re: [RFC] New "kbd" macro?

[Marcin Borkowski]

On 2017-09-13, at 16:03, Kaushal Modi <kaushal.modi@gmail.com> wrote:

> On Wed, Sep 13, 2017 at 9:23 AM Nicolas Goaziou <mail@nicolasgoaziou.fr>
> wrote:
>
>> Hello,
>>
>> I would like to submit a new minor macro for integration within Org: the
>> "kbd" macro.
>>
>
> Awesome!

+1, I really missed such a feature!!!

> It will be tremendously useful for blog posts.

And technical writing.

> Granted, this is probably only useful for Texinfo export, but defining
>> it as a global macro makes Org documents a bit more portable across
>> export back-ends.
>
> For HTML too! :)

Don't forget about LaTeX!!!  It could use the menukeys package
(https://ctan.org/pkg/menukeys).

I could actually add some code to support that, do you want me to start
working on it?

Thanks a lot,

-- 
Marcin Borkowski

Re: [RFC] New "kbd" macro?

[Rasmus]

Hi Nicolas,

Thanks for looking into this.

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> I would like to submit a new minor macro for integration within Org: the
> "kbd" macro.
>
> The "kbd" macro focuses on normalizing keybinding during export. For
> example, during Texinfo export, {{{kbd(v SPC)}}} becomes 
>
>   @kbd{v @key{SPC}}
>
> whereas in another back-end, it becomes
>
>   v <SPC>
>
> More specifically:
>
>   Within {{{kbd(...)}}}, the following case-sensitive keys are wrapped
>   within angle brackets: SPC, RET, LFD, TAB, BS, ESC, DELETE, SHIFT,
>   CTRL, META, up, down, left, right.

(I wish there was a more light-weight syntax for macros...  Maybe we
should provide something similar to C-c C-l for inserting them...)

> With an optional argument, it can wrap the key-binding within verbatim
> or code markup:
>
>   {{{kbd(v SPC,code)}}}      =>  ~v <SPC>~
>
>   {{{kbd(v SPC,verbatim)}}}  =>  =v <SPC>=
>
> Other markup is not implemented because, in that case, you can wrap
> appropriate characters around the macro.

I am not sure where it makes sense to print in "plain" text as opposed to
code or verbatim by default.  Anyway, I think it makes sense to add
specific export mechanisms for several backends, which might make it
possible to remove that argument.

- HTML, MD :: as Kaushal points out, please use <kbd>.</kbd>.

- LaTeX :: it’s complicated, as e.g. keys needs to be translated in a specific
  way, depending on the package that is being used, e.g. "libertinekey",
  "menukeys" or whatnot.  We should not add new default packages IMO.  We
  could always support a couple of different packages, but default to
  something like "\fbox{\ttfamily %s}".  Adding support for other packages
  reduces to mapping specific sequences, like "SPC" to something like
  "\LKeySpace".

- ODT :: it should be possible to use something like Biolinium or
  Libertinus keyboard fonts if we just have an alist mapping sequences
  like CTRL to the right unicode symbol (E.g. U+E173 here), but the place
  in the font would probably depend on the font. So unless there’s a
  standard it would be risky.  Since fonts aren’t (typically?) embedded in
  ODT it might be better to add a new odt style that prints the words in
  the mono font inside a box, i.e. the equivalent of "\fbox{\ttfamily %s}".

- Texinfo :: already supported.

Rasmus

-- 
Bang bang

Re: [RFC] New "kbd" macro?

[Oleh Krehel]

> Copying Oleh, as I believe he would also have some interest in this.

Thanks for the info. I still prefer to denote keys as ~C-x C-f~, and
code as =forward-char=:
1. It looks good in text.
2. It looks good on Github/Gitlab render.
3. It still exports as <kbd>C-x C-f</kbd> for HTML, and @kbd{C-x C-f}
for Texinfo.

See for example:
https://github.com/abo-abo/swiper/blob/master/doc/ivy.org#writing-this-manual

regards,
Oleh

Re: [RFC] New "kbd" macro?

[Nicolas Goaziou]

Hello,

Rasmus <rasmus@gmx.us> writes:

> I am not sure where it makes sense to print in "plain" text as opposed to
> code or verbatim by default.  Anyway, I think it makes sense to add
> specific export mechanisms for several backends, which might make it
> possible to remove that argument.

Plain text allows user to define its own environment. I'm not against
forcing ~...~ on keybindings when no specific syntax is required.

> - HTML, MD :: as Kaushal points out, please use <kbd>.</kbd>.

This is (almost) already the case.
>
> - LaTeX :: it’s complicated, as e.g. keys needs to be translated in a specific
>   way, depending on the package that is being used, e.g. "libertinekey",
>   "menukeys" or whatnot.  We should not add new default packages IMO.  We
>   could always support a couple of different packages, but default to
>   something like "\fbox{\ttfamily %s}".  Adding support for other packages
>   reduces to mapping specific sequences, like "SPC" to something like
>   "\LKeySpace".
>
> - ODT :: it should be possible to use something like Biolinium or
>   Libertinus keyboard fonts if we just have an alist mapping sequences
>   like CTRL to the right unicode symbol (E.g. U+E173 here), but the place
>   in the font would probably depend on the font. So unless there’s a
>   standard it would be risky.  Since fonts aren’t (typically?) embedded in
>   ODT it might be better to add a new odt style that prints the words in
>   the mono font inside a box, i.e. the equivalent of "\fbox{\ttfamily %s}".

For those back-ends, I think, e.g., ~M-<RET>~ is a good default. It is
very close to what Texinfo can produce. The "fbox" thing seems a bit
heavy.

WDYT?

Regards,

-- 
Nicolas Goaziou

Re: [RFC] New "kbd" macro?

[Rasmus]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Hello,
>
> Rasmus <rasmus@gmx.us> writes:
>
>> I am not sure where it makes sense to print in "plain" text as opposed to
>> code or verbatim by default.  Anyway, I think it makes sense to add
>> specific export mechanisms for several backends, which might make it
>> possible to remove that argument.
>
> Plain text allows user to define its own environment. I'm not against
> forcing ~...~ on keybindings when no specific syntax is required.
>
>> - HTML, MD :: as Kaushal points out, please use <kbd>.</kbd>.
>
> This is (almost) already the case.
>>
>> - LaTeX :: it’s complicated, as e.g. keys needs to be translated in a specific
>>   way, depending on the package that is being used, e.g. "libertinekey",
>>   "menukeys" or whatnot.  We should not add new default packages IMO.  We
>>   could always support a couple of different packages, but default to
>>   something like "\fbox{\ttfamily %s}".  Adding support for other packages
>>   reduces to mapping specific sequences, like "SPC" to something like
>>   "\LKeySpace".
>>
>> - ODT :: it should be possible to use something like Biolinium or
>>   Libertinus keyboard fonts if we just have an alist mapping sequences
>>   like CTRL to the right unicode symbol (E.g. U+E173 here), but the place
>>   in the font would probably depend on the font. So unless there’s a
>>   standard it would be risky.  Since fonts aren’t (typically?) embedded in
>>   ODT it might be better to add a new odt style that prints the words in
>>   the mono font inside a box, i.e. the equivalent of "\fbox{\ttfamily %s}".
>
> For those back-ends, I think, e.g., ~M-<RET>~ is a good default. It is
> very close to what Texinfo can produce. The "fbox" thing seems a bit
> heavy.

I quite like the fbox look, but it would — perhaps – be rather heavy
inline!

How about making it a format-string for LaTeX and a separate style for
ODT?  Then you could change it on a document-basis if needed.

Rasmus

-- 
Dung makes an excellent fertilizer

Re: [RFC] New "kbd" macro?

[Nicolas Goaziou]

Hello,

Rasmus <rasmus@gmx.us> writes:

> I quite like the fbox look, but it would — perhaps – be rather heavy
> inline!
>
> How about making it a format-string for LaTeX and a separate style for
> ODT?  Then you could change it on a document-basis if needed.

Could you elaborate? Where would the format string be specified? 

Also, you need two format strings: one for the whole keybinding, one for
special keys (respectively @kbd and @key in Texinfo).

I'm not much into ODT styles, but if you have an example, I will merrily
add it.

Regards,

-- 
Nicolas Goaziou

Re: [RFC] New "kbd" macro?

[Rasmus]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Hello,
>
> Rasmus <rasmus@gmx.us> writes:
>
>> I quite like the fbox look, but it would — perhaps – be rather heavy
>> inline!
>>
>> How about making it a format-string for LaTeX and a separate style for
>> ODT?  Then you could change it on a document-basis if needed.
>
> Could you elaborate? Where would the format string be specified?
> 
> Also, you need two format strings: one for the whole keybinding, one for
> special keys (respectively @kbd and @key in Texinfo).

You are right, for LaTeX, you would probably want two.  So

    {{{kbd(CTRL-x-f)}}}

would be initiated for org-latex-kdb-format string, which would default to

    \texttt{%s}

Whether a key is needed depends on what it exactly entrails.  If each of
"CTRL", "x" and "f" is a key, then perhaps it makes sense to have a
separate formating-string to e.g. denote "\fbox{%s}", allowing output
like, if desired.

    \texttt{\fbox{Ctrl}-\fbox{x}-\fbox{f}}


> I'm not much into ODT styles, but if you have an example, I will merrily
> add it.

I guess the most straight forward way would be just add a new style to
OrgOdtStyles.xml,

    <style:style style:name="OrgKbd" style:family="text" style:parent-style-name="Source_20_Text"/>

And output it as,

    <text:span text:style-name="OrgKbd">Ctrl-x-f</text:span>

According to this thread,

    https://lists.freedesktop.org/archives/libreoffice/2011-November/021281.html

LO even supports nested text:span, so it could probably even have a
seperate style for KBD.


    <text:span text:style-name="OrgKbd">
    <text:span text:style-name="OrgKey">Ctrl</text:span>-
    <text:span text:style-name="OrgKey">x</text:span>-
    <text:span text:style-name="OrgKey">f</text:span>
    </text:span>

Maybe it’s unnecessary complexity, with little benefit...

Rasmus

-- 
Not everything that goes around comes back around, you know

Re: [RFC] New "kbd" macro?

[Nicolas Goaziou]

Rasmus <rasmus@gmx.us> writes:

> You are right, for LaTeX, you would probably want two.  So
>
>     {{{kbd(CTRL-x-f)}}}
>
> would be initiated for org-latex-kdb-format string, which would default to
>
>     \texttt{%s}
>
> Whether a key is needed depends on what it exactly entrails.  If each of
> "CTRL", "x" and "f" is a key, then perhaps it makes sense to have a
> separate formating-string to e.g. denote "\fbox{%s}", allowing output
> like, if desired.
>
>     \texttt{\fbox{Ctrl}-\fbox{x}-\fbox{f}}

Note that, per (info "(texinfo) @key"), this should still be

  \texttt{Ctrl-x-f}

@key is only applied to the modifier key in isolation.

Another idea could be to allow second argument to implement styles, e.g.

  {{{kbd(C-x-f, menukeys)}}}

We need to implement a couple of them, tho. Marcin offered some help
here.

>> I'm not much into ODT styles, but if you have an example, I will merrily
>> add it.
>
> I guess the most straight forward way would be just add a new style to
> OrgOdtStyles.xml,
>
>     <style:style style:name="OrgKbd" style:family="text" style:parent-style-name="Source_20_Text"/>
>
> And output it as,
>
>     <text:span text:style-name="OrgKbd">Ctrl-x-f</text:span>
>
> According to this thread,
>
>     https://lists.freedesktop.org/archives/libreoffice/2011-November/021281.html
>
> LO even supports nested text:span, so it could probably even have a
> seperate style for KBD.
>
>
>     <text:span text:style-name="OrgKbd">
>     <text:span text:style-name="OrgKey">Ctrl</text:span>-
>     <text:span text:style-name="OrgKey">x</text:span>-
>     <text:span text:style-name="OrgKey">f</text:span>
>     </text:span>
>
> Maybe it’s unnecessary complexity, with little benefit...

I think I like it because it is closer to Texinfo syntax.

Regards,

Re: [RFC] New "kbd" macro?

[Kaushal Modi]

[-- Attachment #1: Type: text/plain, Size: 443 bytes --]

On Thu, Sep 14, 2017 at 6:03 PM Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

>
> > - HTML, MD :: as Kaushal points out, please use <kbd>.</kbd>.
>
> This is (almost) already the case.
>

Thanks. I tried the second version of the patch and it works great. About
the /almost/, the same <kbd>..</kbd> export worked for MD exports too.. as
ox-md is derived from ox-html, and also as all Markdown renderers allow
inline HTML.
-- 

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 855 bytes --]

Re: [RFC] New "kbd" macro?

[Kaushal Modi]

[-- Attachment #1: Type: text/plain, Size: 910 bytes --]

On Fri, Sep 15, 2017, 8:54 AM Kaushal Modi <kaushal.modi@gmail.com> wrote:

> On Thu, Sep 14, 2017 at 6:03 PM Nicolas Goaziou <mail@nicolasgoaziou.fr>
> wrote:
>
>>
>> > - HTML, MD :: as Kaushal points out, please use <kbd>.</kbd>.
>>
>> This is (almost) already the case.
>>
>
> Thanks. I tried the second version of the patch and it works great. About
> the /almost/, the same <kbd>..</kbd> export worked for MD exports too.. as
> ox-md is derived from ox-html, and also as all Markdown renderers allow
> inline HTML.
>

Makes me think.. instead of hard-codng the kbd export forms in the macro,
wouldn't it be better to define those in the respective exporter backends?

That way I can easily override the behavior I want using :translate-alist
in my custom backend.

Can a mechanism be put in place so that we can have a 'kbd' element
behavior that can be defined in the :translate-alist?
-- 

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 1705 bytes --]

Re: [RFC] New "kbd" macro?

[Nicolas Goaziou]

Hello,

Kaushal Modi <kaushal.modi@gmail.com> writes:

> Makes me think.. instead of hard-codng the kbd export forms in the macro,
> wouldn't it be better to define those in the respective exporter
> backends?

We don't have a syntax for these. 

> Can a mechanism be put in place so that we can have a 'kbd' element
> behavior that can be defined in the :translate-alist?

See above.

Regards,

-- 
Nicolas Goaziou

Re: [RFC] New "kbd" macro?

[Nicolas Goaziou]

Completing myself:

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Kaushal Modi <kaushal.modi@gmail.com> writes:
>
>> Makes me think.. instead of hard-codng the kbd export forms in the macro,
>> wouldn't it be better to define those in the respective exporter
>> backends?
>
> We don't have a syntax for these. 
>
>> Can a mechanism be put in place so that we can have a 'kbd' element
>> behavior that can be defined in the :translate-alist?

There is a (convoluted) way, though.

The macro can expand to something specific, like a "kbd" export snippet
(i.e., @@kbd:...@@). "ox.el" can then turn these snippets into nested
(kbd ...) and (key ...) objects.

Pros:

- Every back-end can have total control over how "kbd" and "key" objects
  are transformed.

- Export back-ends that inherit from ours benefit from the
  transformation without additional work (like a regular macro).

Cons:

- It's less straightforward than a regular macro.

- Back-ends built from scratch (i.e., that do not inherit from any
  existing back-end) need to define handlers for those pseudo-objects
  (unlike to a regular macro). I'm not sure about where to document
  that.


I'm not sure it is worth it, considering, so far, only "latex" back-end
has no obvious default value.

WDYT?

Regards,