[RFC] Syntax for macros

[RFC] Syntax for macros

[Sebastien Vauban]

Hello,

I know this question can be a sensible one, but I wonder whether we
couldn't "remove some fat" from the macro "call" syntax?

When trying to convince colleagues and friends to use macros, I get
kind of allergic reactions because of the many accolades.

Example:

--8<---------------cut here---------------start------------->8---
  #+MACRO: hlt @@html:<span style="background-color: yellow;">$1</span>@@

  This {{{hlt(information)}}} is important.
--8<---------------cut here---------------end--------------->8---

I wondered whether we could reduce the number of accolades to 2 or 1?

This would be much more easy to read, IMO:

--8<---------------cut here---------------start------------->8---
  This {hlt(information)} is important.
--8<---------------cut here---------------end--------------->8---

Would this be possible?  If so, would you want that as well?

Best regards,
  Seb

-- 
Sebastien Vauban

Re: [RFC] Syntax for macros

[Bastien]

"Sebastien Vauban" <sva-news-D0wtAvR13HarG/iDocfnWg@public.gmane.org>
writes:

> This would be much more easy to read, IMO:
>
>   This {hlt(information)} is important.

But more prone to false positives.

> Would this be possible?  If so, would you want that as well?

Reducing to {{...}} could be better, but I'm not sure this is
what will make your friends happy :)

-- 
 Bastien

Re: [RFC] Syntax for macros

[Sebastien Vauban]

Hi Bastien,

Bastien wrote:
> "Sebastien Vauban" writes:
>
>> This would be much more easy to read, IMO:
>>
>>   This {hlt(information)} is important.
>
> But more prone to false positives.

Because of the grouping for sub/super-scripts?

>> Would this be possible?  If so, would you want that as well?
>
> Reducing to {{...}} could be better, but I'm not sure this is
> what will make your friends happy :)

Not entirely, no!  But I think that'd be already a good simplification.

Best regards,
  Seb

-- 
Sebastien Vauban

Re: [RFC] Syntax for macros

[Bastien]

"Sebastien Vauban" <sva-news-D0wtAvR13HarG/iDocfnWg@public.gmane.org>
writes:

>>> Would this be possible?  If so, would you want that as well?
>>
>> Reducing to {{...}} could be better, but I'm not sure this is
>> what will make your friends happy :)
>
> Not entirely, no!  But I think that'd be already a good
> simplification.

Added to my "will-silently-see-if-this-makes-progress" list :)

-- 
 Bastien

Re: [RFC] Syntax for macros

[Sebastien Vauban]

Bastien wrote:
> "Sebastien Vauban" writes:
>> Bastien wrote:
>>
>>> Reducing to {{...}} could be better, but I'm not sure this is
>>> what will make your friends happy :)
>>
>> Not entirely, no!  But I think that'd be already a good
>> simplification.
>
> Added to my "will-silently-see-if-this-makes-progress" list :)

Isn't it just changing those occurrences?

--8<---------------cut here---------------start------------->8---
./org-element.el:3177:    (looking-at "{{{\\([a-zA-Z][-a-zA-Z0-9_]*\\)\\(([ \t\n]*\\([^\000]*?\\))\\)?}}}")
./org-element.el:3217:	   "{{{\\([a-zA-Z][-a-zA-Z0-9_]*\\)\\(([ \t\n]*\\([^\000]*?\\))\\)?}}}"
./org-macro.el:35:;; {{{time(format-string)}}}, {{{property(node-property)}}},
./org-macro.el:36:;; {{{input-file}}} and {{{modification-time(format-string)}}}.
./org-macro.el:38:;; Upon exporting, "ox.el" will also provide {{{author}}}, {{{date}}},
./org-macro.el:39:;; {{{email}}} and {{{title}}} macros.
./org-macro.el:165:      (while (re-search-forward "{{{[-A-Za-z0-9_]" nil t)
./org.el:6263:	   '("{{{.+?}}}" (0 'org-macro t))
./ox.el:3092:	 ;; Expand export-specific set of macros: {{{author}}},
./ox.el:3093:	 ;; {{{date}}}, {{{email}}} and {{{title}}}.  It must be done
--8<---------------cut here---------------end--------------->8---

Best regards,
  Seb

-- 
Sebastien Vauban

Re: [RFC] Syntax for macros

[Nick Dokos]

"Sebastien Vauban" <sva-news@mygooglest.com>
writes:

> Bastien wrote:
>> "Sebastien Vauban" writes:
>>> Bastien wrote:
>>>
>>>> Reducing to {{...}} could be better, but I'm not sure this is
>>>> what will make your friends happy :)
>>>
>>> Not entirely, no!  But I think that'd be already a good
>>> simplification.
>>
>> Added to my "will-silently-see-if-this-makes-progress" list :)
>
> Isn't it just changing those occurrences?
>
> ./org-element.el:3177:    (looking-at "{{{\\([a-zA-Z][-a-zA-Z0-9_]*\\)\\(([ \t\n]*\\([^\000]*?\\))\\)?}}}")
> ./org-element.el:3217:	   "{{{\\([a-zA-Z][-a-zA-Z0-9_]*\\)\\(([ \t\n]*\\([^\000]*?\\))\\)?}}}"
> ./org-macro.el:35:;; {{{time(format-string)}}}, {{{property(node-property)}}},
> ./org-macro.el:36:;; {{{input-file}}} and {{{modification-time(format-string)}}}.
> ./org-macro.el:38:;; Upon exporting, "ox.el" will also provide {{{author}}}, {{{date}}},
> ./org-macro.el:39:;; {{{email}}} and {{{title}}} macros.
> ./org-macro.el:165:      (while (re-search-forward "{{{[-A-Za-z0-9_]" nil t)
> ./org.el:6263:	   '("{{{.+?}}}" (0 'org-macro t))
> ./ox.el:3092:	 ;; Expand export-specific set of macros: {{{author}}},
> ./ox.el:3093:	 ;; {{{date}}}, {{{email}}} and {{{title}}}.  It must be done
>
> Best regards,
>   Seb

There is also backwards compatibility to consider.
-- 
Nick

Re: [RFC] Syntax for macros

[Sebastien Vauban]

Hello Nick,

Nick Dokos wrote:
> "Sebastien Vauban" writes:
>> Bastien wrote:
>>> "Sebastien Vauban" writes:
>>>> Bastien wrote:
>>>>
>>>>> Reducing to {{...}} could be better, but I'm not sure this is
>>>>> what will make your friends happy :)
>>>>
>>>> Not entirely, no!  But I think that'd be already a good
>>>> simplification.
>>>
>>> Added to my "will-silently-see-if-this-makes-progress" list :)
>>
>> Isn't it just changing those occurrences?
>>
>> ./org-element.el:3177: (looking-at
>> "{{{\\([a-zA-Z][-a-zA-Z0-9_]*\\)\\(([ \t\n]*\\([^\000]*?\\))\\)?}}}")
>> ./org-element.el:3217:
>> "{{{\\([a-zA-Z][-a-zA-Z0-9_]*\\)\\(([ \t\n]*\\([^\000]*?\\))\\)?}}}"
>> ./org-macro.el:35:;; {{{time(format-string)}}}, {{{property(node-property)}}},
>> ./org-macro.el:36:;; {{{input-file}}} and {{{modification-time(format-string)}}}.
>> ./org-macro.el:38:;; Upon exporting, "ox.el" will also provide {{{author}}}, {{{date}}},
>> ./org-macro.el:39:;; {{{email}}} and {{{title}}} macros.
>> ./org-macro.el:165:      (while (re-search-forward "{{{[-A-Za-z0-9_]" nil t)
>> ./org.el:6263:	   '("{{{.+?}}}" (0 'org-macro t))
>> ./ox.el:3092:	 ;; Expand export-specific set of macros: {{{author}}},
>> ./ox.el:3093:	 ;; {{{date}}}, {{{email}}} and {{{title}}}.  It must be done
>
> There is also backwards compatibility to consider.

How?  You know, when many, many, many keywords or options changed
between Org 7.9 and Org 8.0, there was nothing to support backward
compatibility: much too complex, I guess.

As a reminder, some of the changes:

  #+STYLE: ...                             ->  #+HTML_HEAD: ...
  #+BEAMER_HEADER_EXTRA: \usetheme{Madrid} ->  #+BEAMER_THEME: Madrid
  #+ATTR_LaTeX: width=1.1cm                ->  #+ATTR_LaTeX: :width 1.1cm
  #+ATTR_LaTeX: align=lrrrr                ->  #+ATTR_LaTeX: :align lrrrr

Add a variable "org-support-old-macro-syntax" seems overkill to me. But,
yes, I know, that's something that will have to be clearly mentioned in
the NEWS as something that did change, and as some consequences.

Best regards,
  Seb

-- 
Sebastien Vauban

Re: [RFC] Syntax for macros

[Nick Dokos]

"Sebastien Vauban" <sva-news@mygooglest.com>
writes:

>> There is also backwards compatibility to consider.
>
> How?  You know, when many, many, many keywords or options changed
> between Org 7.9 and Org 8.0, there was nothing to support backward
> compatibility: much too complex, I guess.
>

Yes, indeed: OTOH there was widespread recognition that the ad-hoc
nature of certain things and creeping featuritis in org-mode was causing
problems and there was a consensus (at least on the list) that having
the pain concentrated in one (major) release was the way to go. I think
in general org-mode is better because of the changes, but that does not
mean that there have not been problems, as you no doubt have noticed.

That does not mean that we can push changes that break peoples'
workflows (yes, I know: http://xkcd.com/1172/ ) willy nilly. They either
have to come at major releases with plenty of warning, or they have to
be backwards compatible or there has to be widespread consensus that
that is a desirable course of action - and I'd raise the bar very high
on this last case.

Are you advocating that the macro syntax should be changed without
worrying about backwards compatibility? That might work if almost nobody
uses macros currently[fn:1], but my impression is that they are used fairly
widely.

> Add a variable "org-support-old-macro-syntax" seems overkill to me. But,
> yes, I know, that's something that will have to be clearly mentioned in
> the NEWS as something that did change, and as some consequences.
>

No: I'm saying that if this change is implemented, {{{foo}}} should be
deprecated (probably raising a deprecation warning when encountered) and
that both {{foo}} and {{{foo}}} should work identically, at least until
the next major release (we can debate whether that's 8.3 or 8.4 or
9.0). At that point and forever after, the old syntax starts raising
errors instead of warnings.

Footnotes:

[fn:1] E.g. QUOTE was an example of a change that could go through,
       precisely because nobody was using it. COMMENT could not go
       quietly into oblivion in the same way however: it was used
       widely.

-- 
Nick

Re: [RFC] Syntax for macros

[Thorsten Jolitz]

Nick Dokos <ndokos@gmail.com> writes:

> "Sebastien Vauban" <sva-news@mygooglest.com>
> writes:
>
>>> There is also backwards compatibility to consider.

Not only that, probability of false positives matters
too. E.g. inserting text snippets in PicoLisp Wiki Syntax into an Org
file could easily cause errors given the frequent use of {}:

,-----------------------------------------------------------------------
| 1{Contrived Example}
| 
| In /{picolisp-wiki-mode} braces are !{very} important, and in PicoLisp
| itself Database objects are identified like this: 
| 
| :{{36}}
| 
| denotes Object 36.
| 
| Here is a list of objects in the DB:
| 
| 
| *{
|    -{{11}}
|    -{{36}}
|    -{{45}}
| }
`-----------------------------------------------------------------------

This might be contrived, but is actually not that exotic.

-- 
cheers,
Thorsten

Re: [RFC] Syntax for macros

[Bastien]

Nick Dokos <ndokos@gmail.com> writes:

> No: I'm saying that if this change is implemented, {{{foo}}} should be
> deprecated (probably raising a deprecation warning when encountered) and
> that both {{foo}} and {{{foo}}} should work identically, at least until
> the next major release (we can debate whether that's 8.3 or 8.4 or
> 9.0). At that point and forever after, the old syntax starts raising
> errors instead of warnings.

Agreed.  Also, the whole issue is not that important IMO.
If the {{{...}}} are visually annoying, we can as well rely
on text properties to hide them and on faces to display
them in a different way (as we do already.)

-- 
 Bastien

Re: [RFC] Syntax for macros

[Achim Gratz]

Sebastien Vauban writes:
> When trying to convince colleagues and friends to use macros, I get
> kind of allergic reactions because of the many accolades.
>
> Example:
>
>   #+MACRO: hlt @@html:<span style="background-color: yellow;">$1</span>@@
>
>   This {{{hlt(information)}}} is important.
>
> I wondered whether we could reduce the number of accolades to 2 or 1?

Why not just fontify them away entirely?  I'm not too enamored with
these three braces in and out myself, but anything less is going to
cause trouble elsewhere, I'd think.


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

Wavetables for the Terratec KOMPLEXER:
http://Synth.Stromeko.net/Downloads.html#KomplexerWaves

Re: [RFC] Syntax for macros

[Florian Beck]

On 30.01.2014 17:59, Nick Dokos wrote:

> Are you advocating that the macro syntax should be changed without
> worrying about backwards compatibility? That might work if almost nobody
> uses macros currently[fn:1], but my impression is that they are used fairly
> widely.

The main problem is that this will affect org files in weeks, months or 
years in the future, which then mysteriously fail to work as expected. I 
agree, however, with Sebastien that the current syntax is a bit heavy. 
Two brackets would be better, but still ugly.

A couple of alternative ideas:

1. How about using unicode characters? This would solve the problem of 
false positives and allow for light markup. E.g.:

(looking-at "\\(?:「\\|{{{\\)\\([a-zA-Z][-a-zA-Z0-9_]*\\)\\(([ \t\n]* 
\\([^\000]*?\\))\\)?\\(?:」\\|}}}\\)")

2. On the other hand a function to insert a macro might be all we need, 
e.g.:

(defun org-macro-insert ()
   (interactive)
   (let* ((macros (org-macro--collect-macros))
	 (macro (completing-read "Insert macro: " (mapcar 'car macros)))
	 (args (string-match "$[[:digit:]]" (cdr (assoc macro macros))))
	 pos)
     (insert (format  "{{{%s" macro))
     (when args (insert "(") (setq pos (point)) (insert ")"))
     (insert "}}}")
     (when pos (goto-char pos))))

Maybe even hide the brackets during fontification?

3. Of course, since macros are only relevant when exporting, it should 
be easy to write an export filter that translates arbitrary chars to 
brackets.

-- 
Florian Beck

Re: [RFC] Syntax for macros

[Thomas S. Dye]

Florian Beck <fb@miszellen.de> writes:

> 3. Of course, since macros are only relevant when exporting, it should
> be easy to write an export filter that translates arbitrary chars to
> brackets.

I think this might be the way forward for Org mode users who don't like
the look of the current macro syntax.

Backwards compatibility is an issue for my work with Org mode. I'm happy
to track changes that result from enhanced capabilities, but unhappy to
track changes that are cosmetic, like this suggestion to change the
syntax for macros.

All the best,
Tom

-- 
Thomas S. Dye
http://www.tsdye.com

[PATCH] Font-lock: allow hiding of brackets surrounding macros

[Florian Beck]

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

Hi,

I gave it a try. Well, I spend most of my time on formatting this patch. 
Hope it works.

-- 
Florian Beck

[-- Attachment #2: 0001-Font-lock-allow-hiding-of-brackets-surrounding-macro.patch --]
[-- Type: text/x-patch, Size: 2733 bytes --]

From 7980ee3ab9e048c1bdeddfaa6f7dbe984c469171 Mon Sep 17 00:00:00 2001
From: Florian Beck <fb@miszellen.de>
Date: Fri, 31 Jan 2014 22:42:04 +0100
Subject: [PATCH] Font-lock: allow hiding of brackets surrounding macros

* lisp/org.el (org-hide-macro-markers): new option
  (org-fontify-macros): new function
  (org-set-font-lock-defaults): call `org-fontify-macros'

* doc/org.texi: Document user option `org-hide-macro-markers'

TINYCHANGE
---
 doc/org.texi |  3 +++
 lisp/org.el  | 21 ++++++++++++++++++++-
 2 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/doc/org.texi b/doc/org.texi
index 9c7a6a7..792315c 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -10019,6 +10019,9 @@ and to the modification time of the file being exported, respectively.
 @var{FORMAT} should be a format string understood by
 @code{format-time-string}.
 
+The surrounding brackets can be made invisible by setting 
+@code{org-hide-macro-markers} to @code{t}.
+
 Macro expansion takes place during export.
 
 
diff --git a/lisp/org.el b/lisp/org.el
index 20dcb92..5844daf 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -4145,6 +4145,11 @@ following symbols:
   :group 'org-appearance
   :type 'boolean)
 
+(defcustom org-hide-macro-markers nil
+  "Non-nil mean font-lock should hide the brackets marking macro calls."
+  :group 'org-appearance
+  :type 'boolean)
+
 (defcustom org-pretty-entities nil
   "Non-nil means show entities as UTF8 characters.
 When nil, the \\name form remains in the buffer."
@@ -5949,6 +5954,20 @@ by a #."
     (org-remove-flyspell-overlays-in (match-beginning 0) (match-end 0))
     t))
 
+  (defun org-fontify-macros (limit)
+    "Fontify macros."
+    (when (re-search-forward "\\({{{\\).+?\\(}}}\\)" limit t)
+      (add-text-properties
+       (match-beginning 0) (match-end 0)
+       '(font-lock-fontified t face org-macro))
+      (when org-hide-macro-markers
+        (add-text-properties (match-end 2) (match-beginning 2)
+                             '(invisible t))
+        (add-text-properties (match-beginning 1) (match-end 1)
+                             '(invisible t)))
+      (org-remove-flyspell-overlays-in (match-beginning 0) (match-end 0))
+      t))
+
 (defun org-activate-angle-links (limit)
   "Run through the buffer and add overlays to links."
   (if (and (re-search-forward org-angle-link-re limit t)
@@ -6260,7 +6279,7 @@ needs to be inserted at a specific position in the font-lock sequence.")
 	   ;; Diary sexps.
 	   '("^&?%%(.*\\|<%%([^>\n]*?>" (0 'org-sexp-date t))
 	   ;; Macro
-	   '("{{{.+?}}}" (0 'org-macro t))
+	   '(org-fontify-macros)
 	   '(org-hide-wide-columns (0 nil append))
 	   ;; TODO keyword
 	   (list (format org-heading-keyword-regexp-format
-- 
1.8.3.2

Re: [PATCH] Font-lock: allow hiding of brackets surrounding macros

[Bastien]

Hi Florian,

Florian Beck <fb@miszellen.de> writes:

> I gave it a try. Well, I spend most of my time on formatting this
> patch. Hope it works.

Works well, thanks.  Unless someone is against this change, I'll apply
it next week.

-- 
 Bastien

Re: [PATCH] Font-lock: allow hiding of brackets surrounding macros

[Bastien]

Hi Florian,

Bastien <bzg@gnu.org> writes:

> Florian Beck <fb@miszellen.de> writes:
>
>> I gave it a try. Well, I spend most of my time on formatting this
>> patch. Hope it works.
>
> Works well, thanks.  Unless someone is against this change, I'll apply
> it next week.

This is now in master -- thanks!

-- 
 Bastien

Re: [PATCH] Font-lock: allow hiding of brackets surrounding macros

[Sebastien Vauban]

Hello Florian and Bastien,

Bastien wrote:
> Bastien <bzg-mXXj517/zsQ@public.gmane.org> writes:
>> Florian Beck <fb-ZlLO5Ova5IRn68oJJulU0Q@public.gmane.org> writes:
>>
>>> I gave it a try. Well, I spend most of my time on formatting this
>>> patch. Hope it works.
>>
>> Works well, thanks.  Unless someone is against this change, I'll apply
>> it next week.
>
> This is now in master -- thanks!

I just tested it.

I think that I would have left one pair of {} visible around macro calls
(for making it clear that it's something special, even if we can play
with the face `org-macro'); but, anyway, I find this to be a nice
improvement. Thanks for it!

Best regards,
  Seb

-- 
Sebastien Vauban

Re: [PATCH] Font-lock: allow hiding of brackets surrounding macros

[Bastien]

Hi Sébastien,

"Sebastien Vauban" <sva-news-D0wtAvR13HarG/iDocfnWg@public.gmane.org>
writes:

> I think that I would have left one pair of {} visible around macro calls
> (for making it clear that it's something special, even if we can play
> with the face `org-macro');

Playing with the face is the right thing to do I guess.

-- 
 Bastien