Re: [O] Conditional link export?

[Oleh Krehel]

Aaron Ecay <address@hidden> writes:

> Extra elisp inside the org file is an important way of extending the
> power of org markup.  Why don’t you want to use it?

Including boilerplate Elisp, all subtly different into each markup
document, just to extend the markup with the syntax that it should have
in the first place anyway. Doesn't that sound bad to you?

One-off Elisp inclusions relevant to a single document are great and
powerful, but adding boilerplate code, usually more of it that the whole
sum of the markup, doesn't sound great at all.  This could be rectified
somewhat by using `require', but then we don't have a self-contained
document any more. Which is important to facilitate sharing and re-use
of Org-mode documents.

> Not in general.  For small pieces of text, you can use macros.
> Something like:
>
> #+macro: ifinfo (eval (if (org-export-derived-backend 
> org-export-current-backend 'info) "$1" "$2"))
>
> {{{ifinfo([[info:emacs#Pachages]],[[https://....]])}}}

The macro definition and call syntax looks very ugly.
Why can't we add inline Elisp calls with the following rules:

1. Any amount of Elisp code can be embedded.
2. The result of the last expression is interpreted either as "%s" or
"%S" appropriately.

I tried this:

    For more package manager details, see 
    #+begin_src emacs-lisp :exports results
    (defun ox-link (link &optional description)
      (cond ((equal org-export-current-backend 'html)
             (format "<a href=\"%s\">%s</a>"
                     link
                     (or description link)))
            (t
             link)))
    (cond
      ((equal org-export-current-backend 'texinfo+)
       (ox-link "info:emacs#Packages"))
      (t
       (ox-link 
"https://www.gnu.org/software/emacs/manual/html_node/emacs/Packages.html";)))
    #+end_src
    .

Here are the problems that I see here:

1. The results aren't embedded and are instead quoted. Extra newlines
are added around the result.
2. Something like `ox-link' isn't built-in.
3. The boundaries are rather verbose, maybe "#+begin_src inline" or
something even shorter would look better.

I think fixing the above three issues would really improve Org-mode's
markup, make it much more powerful. We already have `org-edit-src-code'
which allows us to edit Elisp natively, it only remains to un-constrain
the results from being quoted in a <pre></pre> block, and provide the
standard API (e.g. `ox-link', `ox-src', `ox-tbl') that would work
for all export back ends.

Here's how my example would look, once the above changes are
implemented:

!(cl-case org-export-current-backend
   (texinfo+
    (ox-link
     "info:emacs#Packages"))
   (t
    (ox-link
     
"https://www.gnu.org/software/emacs/manual/html_node/emacs/Packages.html";)))

Now note that the above is meant to be exported inline, instead of into
a <pre></pre> block. If I wanted such a block, I would Paredit-wrap that
sexp with (ox-pre) - a very quick and simple modification.  And to
remove (ox-pre), simply Paredit-raise. Now this would be a powerful
markup indeed. One very important advantage is that each block can be
efficiently debugged in its native Elisp mode, maybe even ERT-tested,
because all API functions would be bound all the time, not just during
the export.

> Note that the solution I gave you allows the links to be clickable in
> the buffer, whereas a macro does not (sort of).

I think we should completely get rid of macros and simply use inline
Elisp, which is both more powerful and more simple.

> See, even you can’t resist putting elisp in.  :P  You could give the
> your pseudocode a #+name and then call it as an inline babel call.

The #+name thing is powerful because if I understood correctly it allows
to call /any/ language not just Elisp. As I mentioned above, I think
Elisp should be privileged and we should be able to call any bound Elisp
function inline without having to declare it.

>> 2. Does Org-mode support the kbd markup for denoting keyboard shortcuts?
>> I'm guessing that the answer is no, which is a shame since both Texinfo
>> and Github/StackExchange-flavored Markdown support it.
>
> No.  There was recently a thread on small caps syntax:
> <http://mid.gmane.org/address@hidden>
> where many of the same themes come up.
>
> There’s not enough consensus at present to add any new markup types to
> org syntax.  Macros can be made to serve many of the same functions,
> though.

I see. I understand why Nicolas is reluctant to modify the actual syntax
for every small thing. And macros could indeed be a solution. My issues
with the macros are the following:

1. They're awkward to define.
2. They're awkward to call.

Using inline Elisp instead of macros would solve both problems.  The
first problem is solved by having a standard library e.g. ox-inline.el
bundled with Org. That would include, e.g. `ox-kbd'. Additionally the
users can write their own libraries and simply `require' them.

Here's how it might look like:

    To install a package, use !(ox-kbd "M-x") =package-install=.

It doesn't look too awkward, and "C-x C-e" would still work simply
inside the Org document. Here's a simple implementation of `ox-kbd':

(defun ox-kbd (str)
  (cl-case org-export-current-backend
    (html (format "<kbd>%s</kbd>" str))
    (texinfo+ (format "@kbd{%s}" str))
    (t str)))

Here's another example of the proposed inline Elisp syntax:

    This document's last revision is !(substring (shell-command-to-string "git 
rev-parse HEAD") 0 -1).

It should be fairly easy to add this to the syntax, since the "!("
string is very unique, and `forward-sexp' can be used to find the ending
of the inline block.

I'd appreciate everyone's thoughts on the proposed addition.  Best case
scenario, Nicolas agrees and it's actually easy to add the new "!()"
inline Elisp syntax. Mid case, everyone's indifferent and I can add the
code myself. Worst case, people are opposed to this change and I'm sad.

regards,
Oleh