emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* [RFC] Sloppy `org-element-context'?
@ 2014-03-27 15:28 Nicolas Goaziou
  2014-03-27 21:34 ` Rasmus
  2014-04-19  8:47 ` Bastien
  0 siblings, 2 replies; 10+ messages in thread
From: Nicolas Goaziou @ 2014-03-27 15:28 UTC (permalink / raw)
  To: Org Mode List

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

Hello,

As you may know, `org-element-context' returns the object under point,
according to Org Syntax. The questions are: should it be a little
sloppy, for convenience? And, if it should, what degree of sloppiness is
acceptable?

Note that, at the time being, the function is already somewhat sloppy,
because it will return an object right before point. In the following
example, "|" is point. Even though it is not on the bold object,
evaluating (org-element-context) there will give:

  "*bold*| text"  =>  (bold ...)

Should we go further? A recent discussion about opening links in node
properties suggests that some users expect to encounter Org syntax
there. I believe this is not generally desirable.

One reason is that contents of properties drawers are hidden most of the
time, and we may forget about them. So, for example, an entry could
appear in the agenda but the timestamp triggering it could be difficult
to find. This is why SCHEDULED and DEADLINE keywords were not turned
into node properties: they are always in sight.

Another reason is that properties can contain really anything, including
markup from other languages. For example, EXPORT_LATEX_HEADER property
contains LaTeX code. As such, they should be kept as general as
possible, that is as a pair of key and value, without any syntax
attached to value, much like keywords.

However, it is possible to still parse value of such properties, as
a convenience feature in `org-element-context', as the attached patch
does. Note that it has drawbacks. Let's consider the following idiomatic
example, meant to do something on every active timestamp below point in
the visible part of the buffer,

  (while (re-search-forward "<[0-9]\\{4\\}-" nil t)
    (let ((context (org-element-context)))
      (when (eq (org-element-type context) 'timestamp)
        ...)))

Used without care, it will be applied to non-existing timestamps (e.g.,
timestamps in a node property) and could lead to confusing behaviour,
like displaying an entry in the agenda because of an invisible
timestamp.

Anyway, here we are. I think it is important to define clearly what
belongs to the syntax (I think it is quite good at the moment), what can
be allowed for the sake of convenience, and what line should never be
crossed (I firmly believe, for example, that `org-element-context'
should never return objects in a comment, an example block, or
a fixed-width area).

Opinions?


Regards,

-- 
Nicolas Goaziou

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-org-element-Make-org-element-context-sloppy.patch --]
[-- Type: text/x-diff, Size: 2531 bytes --]

From ab72802ab90950d8edc2d415443f089a1208f5cc Mon Sep 17 00:00:00 2001
From: Nicolas Goaziou <n.goaziou@gmail.com>
Date: Thu, 27 Mar 2014 15:12:05 +0100
Subject: [PATCH] org-element: Make `org-element-context' sloppy

* lisp/org-element.el (org-element-context): Allow to parse node
  properties.
---
 lisp/org-element.el | 22 ++++++++++++++++++----
 1 file changed, 18 insertions(+), 4 deletions(-)

diff --git a/lisp/org-element.el b/lisp/org-element.el
index d94243b..a774528 100644
--- a/lisp/org-element.el
+++ b/lisp/org-element.el
@@ -5598,7 +5598,9 @@ object type, but always include `:begin', `:end', `:parent' and
 `:post-blank'.
 
 As a special case, if point is right after an object and not at
-the beginning of any other object, return that object.
+the beginning of any other object, return that object.  Also,
+parse Org syntax and return objects in planning lines and node
+properties, for convenience.
 
 Optional argument ELEMENT, when non-nil, is the closest element
 containing point, as returned by `org-element-at-point'.
@@ -5668,8 +5670,12 @@ Providing it allows for quicker computation."
 	   (if (and (>= pos (point)) (< pos (line-end-position)))
 	       (narrow-to-region (point) (line-end-position))
 	     (throw 'objects-forbidden element))))
-	;; At a planning line, if point is at a timestamp, return it,
-	;; otherwise, return element.
+	;; Convenience features.
+	;;
+	;; - At a planning line, if point is at a timestamp, return
+	;;   it, otherwise, return element.
+	;;
+	;; - Return objects in node properties values.
 	((eq type 'planning)
 	 (dolist (p '(:closed :deadline :scheduled))
 	   (let ((timestamp (org-element-property p element)))
@@ -5677,8 +5683,16 @@ Providing it allows for quicker computation."
 			(<= (org-element-property :begin timestamp) pos)
 			(> (org-element-property :end timestamp) pos))
 	       (throw 'objects-forbidden timestamp))))
-	 ;; All other locations cannot contain objects: bail out.
 	 (throw 'objects-forbidden element))
+	((eq type 'node-property)
+	 (beginning-of-line)
+	 (search-forward ":" (line-end-position) t 2)
+	 (skip-chars-forward " \t")
+	 (if (> (point) pos) (throw 'objects-forbidden element)
+	   (narrow-to-region (point) (line-end-position))
+	   ;; Do not limit object types in a node property.
+	   (setq type 'paragraph)))
+	;; All other locations cannot contain objects: bail out.
 	(t (throw 'objects-forbidden element)))
        (goto-char (point-min))
        (let ((restriction (org-element-restriction type))
-- 
1.9.1


^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: [RFC] Sloppy `org-element-context'?
  2014-03-27 15:28 [RFC] Sloppy `org-element-context'? Nicolas Goaziou
@ 2014-03-27 21:34 ` Rasmus
  2014-03-28  9:26   ` Nicolas Goaziou
  2014-04-19  8:47 ` Bastien
  1 sibling, 1 reply; 10+ messages in thread
From: Rasmus @ 2014-03-27 21:34 UTC (permalink / raw)
  To: emacs-orgmode

Hi,

Nicolas Goaziou <n.goaziou@gmail.com> writes:

> As you may know, `org-element-context' returns the object under point,
> according to Org Syntax. The questions are: should it be a little
> sloppy, for convenience? And, if it should, what degree of sloppiness is
> acceptable?

Would it make sense to make it optional?  For my personal hacks, I
much prefer to work with an element, if possible, and flexibility
could facility fast and easy hacks.  On the other hand in Org-core
clarity and strictness is (probably) preferable.  So something like
this

    (let (org-element-strict) (FUN (org-element-context) ...)).


> Note that, at the time being, the function is already somewhat sloppy,
> because it will return an object right before point. In the following
> example, "|" is point. Even though it is not on the bold object,
> evaluating (org-element-context) there will give:
>
>   "*bold*| text"  =>  (bold ...)

> Should we go further? A recent discussion about opening links in node
> properties suggests that some users expect to encounter Org syntax
> there. I believe this is not generally desirable.

I haven't seen this discussion.  I looked briefly at the suggested
patch; I don't understand why it would be necessary or desirable.  But
I will not rule out that I have yet to consider the correct case!

> Anyway, here we are. I think it is important to define clearly what
> belongs to the syntax (I think it is quite good at the moment), what can
> be allowed for the sake of convenience, and what line should never be
> crossed (I firmly believe, for example, that `org-element-context'
> should never return objects in a comment, an example block, or
> a fixed-width area).

As a user I have no problems with the syntax.

As a hacker (not quite a developer!), I do at time desire more
flexibility with org-context to temporarily evaluating an element
under alternative assumptions of its properties.  A recent example
evaluate $x^{z}$ as-if it isn't a latex-fragment.

—Rasmus

--
This space is left intentionally blank

^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: [RFC] Sloppy `org-element-context'?
  2014-03-27 21:34 ` Rasmus
@ 2014-03-28  9:26   ` Nicolas Goaziou
  0 siblings, 0 replies; 10+ messages in thread
From: Nicolas Goaziou @ 2014-03-28  9:26 UTC (permalink / raw)
  To: Rasmus; +Cc: emacs-orgmode

Hello,

Rasmus <rasmus@gmx.us> writes:

> Would it make sense to make it optional?

I thought about it. But adding an optional argument to determine if
`org-element-context' should be strict or sloppy doesn't help in
practice, since one will probably often wonder if he needs to switch to
sloppy mode or not.

Also, `org-element-context' is not needed for parsing a buffer (with
`org-element-parse-buffer'). Thus, strict behaviour is not mandatory.

> I haven't seen this discussion.  I looked briefly at the suggested
> patch; I don't understand why it would be necessary or desirable.  But
> I will not rule out that I have yet to consider the correct case!

For example, one may write

  :PROPERTIES:
  :SOME_LINK: [[my-link:destination]]
  :END:

and expect C-c C-o to open the link in the properties drawer. I can see
the practical use, but not at the syntax level, which defines it as
a plain string. Indeed, this can get worse:

  :PROPERTIES:
  :REMEMBER: <2014-03-28 Fri>
  :END:

introduces a timestamp hidden to the user but not to the agenda.

> As a hacker (not quite a developer!), I do at time desire more
> flexibility with org-context to temporarily evaluating an element
> under alternative assumptions of its properties.  A recent example
> evaluate $x^{z}$ as-if it isn't a latex-fragment.

I think this would go too far. Considering $x^{z}$ as anything else than
a latex fragment is not a good idea. What is the next step? Should the
snippet $a =b \qquad c= d$ be seen as strike-through?


Regards,

-- 
Nicolas Goaziou

^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: [RFC] Sloppy `org-element-context'?
  2014-03-27 15:28 [RFC] Sloppy `org-element-context'? Nicolas Goaziou
  2014-03-27 21:34 ` Rasmus
@ 2014-04-19  8:47 ` Bastien
  2014-04-19  9:15   ` Nicolas Richard
  2014-04-23 20:35   ` Nicolas Goaziou
  1 sibling, 2 replies; 10+ messages in thread
From: Bastien @ 2014-04-19  8:47 UTC (permalink / raw)
  To: Nicolas Goaziou; +Cc: Org Mode List

Hi Nicolas,

Nicolas Goaziou <n.goaziou@gmail.com> writes:

> As you may know, `org-element-context' returns the object under point,
> according to Org Syntax. The questions are: should it be a little
> sloppy, for convenience? And, if it should, what degree of sloppiness is
> acceptable?

I don't think `org-element-context' should be sloppy *at all*.

`org-element-context' and `org-element-at-point' should both stick to
the syntax as strictly defined -- that's where the value of your work
lies, and we should never dirty that.

IMHO the needed flexibility should be implemented at the level of what
users may want to do with the string at point, even if this means to
temporarily interpret this string in a different way than what the
syntax would do.

For example, on a comment, (eq 'comment (car (org-element-at-point)))
should always return `t'.  But if the user wants to open bracket links
from comments (or in a property), then something like this would do:

(defun org-open-links-in-comment-and-properties ()
  "Open links in a comment or in a property."
  (interactive)
  (let ((string-ahead (and (looking-at ".+") (match-string 0)))
	(value (org-element-property :value (org-element-at-point))))
    (with-temp-buffer
      (org-mode)
      (insert value)
      (goto-char (point-min))
      (search-forward string-ahead)
      (org-open-at-point))))

which do work right now.

Of course this could be generalized, provided the property to
consider is always named ":value", which is not the case IIUC:
sometimes it's :raw-data, right?

My point is that sloppiness at the syntax level would break the
separation of concerns.

If we try to apply the MVC scheme to an org-mode file: the syntax
would give us the model of a file, the buffer properties give us
the view of the file, and functions to render the model or to act
on the buffer are the controllers.  Flexibility should not be in
the model, but in the controllers.

Those distinctions were blurred away before your parser because
Org files are just text... and because we assumed the view (from
the text properties) gave us something like a "syntax".

Last but not least: the spirit of the solution shown above does
not prevent amending the syntax if we *really* need to amend it,
but that's where I'd be as conservative as possible -- that is,
as *you* :)

Hope this all makes sense -- let me know what you think.

-- 
 Bastien

^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: [RFC] Sloppy `org-element-context'?
  2014-04-19  8:47 ` Bastien
@ 2014-04-19  9:15   ` Nicolas Richard
  2014-04-19  9:30     ` Bastien
  2014-04-23 20:35   ` Nicolas Goaziou
  1 sibling, 1 reply; 10+ messages in thread
From: Nicolas Richard @ 2014-04-19  9:15 UTC (permalink / raw)
  To: Bastien; +Cc: Org Mode List, Nicolas Goaziou

Bastien <bzg@gnu.org> writes:
> I don't think `org-element-context' should be sloppy *at all*.
>
> Hope this all makes sense -- let me know what you think.

It makes sense to me, and I agree with you : org element should not
parse the syntax differently just because e.g. we put a link in a
comment and want to open it.

For comparison, AucTeX has a variable LaTeX-syntactic-comments which
controls that kind of thing : "If non-nil comments will be handled
according to LaTeX syntax."

-- 
Nico.

^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: [RFC] Sloppy `org-element-context'?
  2014-04-19  9:15   ` Nicolas Richard
@ 2014-04-19  9:30     ` Bastien
  0 siblings, 0 replies; 10+ messages in thread
From: Bastien @ 2014-04-19  9:30 UTC (permalink / raw)
  To: Nicolas Richard; +Cc: Nicolas Goaziou, Org Mode List

Nicolas Richard <theonewiththeevillook@yahoo.fr> writes:

> For comparison, AucTeX has a variable LaTeX-syntactic-comments which
> controls that kind of thing : "If non-nil comments will be handled
> according to LaTeX syntax."

That's interesting indeed, thanks for sharing.

-- 
 Bastien

^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: [RFC] Sloppy `org-element-context'?
  2014-04-19  8:47 ` Bastien
  2014-04-19  9:15   ` Nicolas Richard
@ 2014-04-23 20:35   ` Nicolas Goaziou
  2014-04-29 21:20     ` Nicolas Goaziou
  1 sibling, 1 reply; 10+ messages in thread
From: Nicolas Goaziou @ 2014-04-23 20:35 UTC (permalink / raw)
  To: Bastien; +Cc: Org Mode List

Hello,

Bastien <bzg@gnu.org> writes:

> I don't think `org-element-context' should be sloppy *at all*.

[...]

> For example, on a comment, (eq 'comment (car (org-element-at-point)))

*coughs* (eq 'comment (org-element-type (org-element-at-point)))

> should always return `t'.  But if the user wants to open bracket links
> from comments (or in a property), then something like this would do:
>
> (defun org-open-links-in-comment-and-properties ()
>   "Open links in a comment or in a property."
>   (interactive)
>   (let ((string-ahead (and (looking-at ".+") (match-string 0)))

  (buffer-substring (point) (line-end-position))
                        
> 	(value (org-element-property :value (org-element-at-point))))
>     (with-temp-buffer
>       (org-mode)

  (let ((org-inhibit-startup t)) (org-mode))

>       (insert value)
>       (goto-char (point-min))
>       (search-forward string-ahead)
>       (org-open-at-point))))
>
> which do work right now.

Indeed.

> Of course this could be generalized, provided the property to
> consider is always named ":value", which is not the case IIUC:
> sometimes it's :raw-data, right?

No, :raw-value are different and shouldn't get in the way in this case.

> Last but not least: the spirit of the solution shown above does
> not prevent amending the syntax if we *really* need to amend it,
> but that's where I'd be as conservative as possible -- that is,
> as *you* :)

Indeed.

> Hope this all makes sense -- let me know what you think.

I agree. We can ignore the patch.


Regards,

-- 
Nicolas Goaziou

^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: [RFC] Sloppy `org-element-context'?
  2014-04-23 20:35   ` Nicolas Goaziou
@ 2014-04-29 21:20     ` Nicolas Goaziou
  2014-05-06  9:25       ` Bastien
  0 siblings, 1 reply; 10+ messages in thread
From: Nicolas Goaziou @ 2014-04-29 21:20 UTC (permalink / raw)
  To: Bastien; +Cc: Org Mode List

Correcting myself: 

Nicolas Goaziou <n.goaziou@gmail.com> writes:

> Bastien <bzg@gnu.org> writes:
>
>> (defun org-open-links-in-comment-and-properties ()
>>   "Open links in a comment or in a property."
>>   (interactive)
>>   (let ((string-ahead (and (looking-at ".+") (match-string 0)))
>>         (value (org-element-property :value (org-element-at-point))))
>>     (with-temp-buffer
>>       (org-mode)
>>       (insert value)
>>       (goto-char (point-min))
>>       (search-forward string-ahead)
>>       (org-open-at-point))))
>>
>> which do work right now.
>
> Indeed.

Actually, it will not work in comments (point is X):

  # Some http://orgmode.org/file.html
  # and http://orgmode.org/other-fileX.html

The code will open the first link, not the second one.


Regards,

-- 
Nicolas Goaziou

^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: [RFC] Sloppy `org-element-context'?
  2014-04-29 21:20     ` Nicolas Goaziou
@ 2014-05-06  9:25       ` Bastien
  2014-05-26 15:50         ` Bastien
  0 siblings, 1 reply; 10+ messages in thread
From: Bastien @ 2014-05-06  9:25 UTC (permalink / raw)
  To: Nicolas Goaziou; +Cc: Org Mode List

Hi Nicolas,

Nicolas Goaziou <n.goaziou@gmail.com> writes:

> Actually, it will not work in comments (point is X):
>
>   # Some http://orgmode.org/file.html
>   # and http://orgmode.org/other-fileX.html
>
> The code will open the first link, not the second one.

Indeed -- but this can easily be fixed.  Thanks for the comment
on my dirty hack, I will implement something based on this idea
and we'll see if it fits.

-- 
 Bastien

^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: [RFC] Sloppy `org-element-context'?
  2014-05-06  9:25       ` Bastien
@ 2014-05-26 15:50         ` Bastien
  0 siblings, 0 replies; 10+ messages in thread
From: Bastien @ 2014-05-26 15:50 UTC (permalink / raw)
  To: Nicolas Goaziou; +Cc: Org Mode List

Hi Nicolas,

Bastien <bzg@gnu.org> writes:

> Indeed -- but this can easily be fixed.  Thanks for the comment
> on my dirty hack, I will implement something based on this idea
> and we'll see if it fits.

This is now implemented in
http://orgmode.org/cgit.cgi/org-mode.git/commit/?id=b11570

Best,

-- 
 Bastien

^ permalink raw reply	[flat|nested] 10+ messages in thread

end of thread, other threads:[~2014-05-26 15:51 UTC | newest]

Thread overview: 10+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2014-03-27 15:28 [RFC] Sloppy `org-element-context'? Nicolas Goaziou
2014-03-27 21:34 ` Rasmus
2014-03-28  9:26   ` Nicolas Goaziou
2014-04-19  8:47 ` Bastien
2014-04-19  9:15   ` Nicolas Richard
2014-04-19  9:30     ` Bastien
2014-04-23 20:35   ` Nicolas Goaziou
2014-04-29 21:20     ` Nicolas Goaziou
2014-05-06  9:25       ` Bastien
2014-05-26 15:50         ` Bastien

Code repositories for project(s) associated with this inbox:

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).