emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* extensible syntax
@ 2009-01-04 20:33 Samuel Wales
  2009-01-05 16:19 ` Samuel Wales
  0 siblings, 1 reply; 3+ messages in thread
From: Samuel Wales @ 2009-01-04 20:33 UTC (permalink / raw)
  To: emacs-orgmode

A general idea, which might or might not be useful.

There are occasionally questions about syntax, like this:

  Also, I'm afraid definition matching regexp won't play
  nicely with text indentation, ... -- Paul

Or this:

  What would be safer?  -- Carsten

I like the footnote implementation, so this is for future
features, not necessarily footnotes.

One issue when implementing new syntax (or changing existing
syntax or cleaning up code) is parsing risk, which I will
define as the risk that the syntax and the regexp or
matching code:

  1) conflicts with user text
  2) conflicts with existing features
  3) will be hard to maintain
  4) constrains future features by making them conflict
     syntactically
  5) makes you run out of syntax to use in the future
  6) will require complicated regexps
  7) doesn't readily handle stuff you might want in the
     future, like being combined with another feature
  8) will be hard to quote, escape, comment, *boldify*, etc.
  9) doesn't handle nestability, print-readability,
     pretty-printability, syntax coloring, etc.
  10) will be inefficient when called in a loop
  11) isn't factored out
  12) etc.

For example, one of the many reasons for using org-IDs (:))
in the conversation manager (as proposed) is that there are
already functions to parse org-IDs, so a new syntax is not
necessary and therefore parsing risk is minimized.

In case parsing risk is a concern when adding a new feature
to org, here is one idea: have a generic syntax that is
extensible with keywords.

The idea is to have a bracketing syntax with a reserved
keyword as the first element that says what you are doing.

To use footnotes as an example (this is not a suggestion to
change footnote syntax, just an example that can be used for
future syntax):

You might use something like "here is some text to be
footnoted $[fn apple]" to specify the footnote link, and
"$[fn-target apples are delicious]" to specify the target.

The general point I want to make is that once such a syntax
is decided on, many future features are possible without
introducing parsing risk.

For example, you can implement a new feature as
"$[my-new-feature ...]".  Then there is no parsing risk,
even though you have just added a new feature.

For modifications of features, you can use keywords:
"$[my-new-feature ... :myparameter ...]".  These are easily
parsed by standard functions for parsing lists.

You can develop ways to boldify, quote, nest, prettily
print, etc. this syntax, and those ways will work well with
all future features that use it.

Of course, the dollar sign and brackets are not the only
possibility; it could be percent sign and parentheses, for
example.

You will not be starting from scratch.  Lisp has already
worked out many of these issues.

I will leave it to those who write massive amounts of org
code to decide whether an extensible syntax might be useful
to reduce parsing risk for future features.

But I thought that I would propose the idea in case it is of
interest.

-- 
For personal gain, myalgic encephalomyelitis denialists are knowingly
causing further suffering and death by grossly corrupting science.  Do
you care about the world?
http://www.meactionuk.org.uk/What_Is_ME_What_Is_CFS.htm

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

* Re: extensible syntax
  2009-01-04 20:33 extensible syntax Samuel Wales
@ 2009-01-05 16:19 ` Samuel Wales
  2009-01-06 10:08   ` Carsten Dominik
  0 siblings, 1 reply; 3+ messages in thread
From: Samuel Wales @ 2009-01-05 16:19 UTC (permalink / raw)
  To: emacs-orgmode

Hello again :),

Let me provide examples -- using footnotes.

All footnote references and definitions would be inside
$[...].  (As mentioned in my previous post.)

There was a concern about keeping code executable.  You can
use a parameter to specify whether you want the footnote to:

  - disappear in the code (thus keeping the code executable
    without having to use comments, so that the reference is
    at the correct position in the line, yet keeping the
    link pointing to the correct position)
  - or show up as a numbered or labeled reference

The reference can look like:

  (defun my-example-defun $[fn "defun name" :invisible t] ()
    (interactive "P") ;$[fn "interactive"]
    ...

The second reference is visible, but the first is not.  Note
that this allows references with spaces (or anything else).
No need to worry about syntax conflicts within org.

There was also a concern about conflicting with code syntax.
Your decision as a user is whether you want $[...] to be
interpreted as code or footnote.  You could want either one.

To make it be interpreted as code, you simply prefix the $
with a \.  That takes away org's special handling of the
syntax.  org's footnote code merely checks for a \ in front
of the $ and then it knows not to do anything except remove
the \.

In fact, the footnote code doesn't even have to do that.
The org extensible syntax code (the code for $[...]) is what
does it.  The footnote code simply calls the extensible
syntax code.

To make it be a footnote, you don't do anything.

This will work for all code examples you can dream up.
There is no need to worry about which languages have $[...]
in them.

The advantage is that for future features, the same
solutions will work.  And since the syntax is extensible, it
will work for completely new features.

Finally, the escaping scheme should be familiar to users, as
it is a common method in programming languages.

Is this idea possibly of interest?

-- 
For personal gain, myalgic encephalomyelitis denialists are knowingly
causing further suffering and death by grossly corrupting science.  Do
you care about the world?
http://www.meactionuk.org.uk/What_Is_ME_What_Is_CFS.htm

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

* Re: Re: extensible syntax
  2009-01-05 16:19 ` Samuel Wales
@ 2009-01-06 10:08   ` Carsten Dominik
  0 siblings, 0 replies; 3+ messages in thread
From: Carsten Dominik @ 2009-01-06 10:08 UTC (permalink / raw)
  To: Samuel Wales; +Cc: emacs-orgmode


On Jan 5, 2009, at 5:19 PM, Samuel Wales wrote:

> Hello again :),
>
> Let me provide examples -- using footnotes.
>
> All footnote references and definitions would be inside
> $[...].  (As mentioned in my previous post.)
>
> There was a concern about keeping code executable.  You can
> use a parameter to specify whether you want the footnote to:
>
>  - disappear in the code (thus keeping the code executable
>    without having to use comments, so that the reference is
>    at the correct position in the line, yet keeping the
>    link pointing to the correct position)
>  - or show up as a numbered or labeled reference
>
> The reference can look like:
>
>  (defun my-example-defun $[fn "defun name" :invisible t] ()
>    (interactive "P") ;$[fn "interactive"]
>    ...
>
> The second reference is visible, but the first is not.  Note
> that this allows references with spaces (or anything else).
> No need to worry about syntax conflicts within org.
>
> There was also a concern about conflicting with code syntax.
> Your decision as a user is whether you want $[...] to be
> interpreted as code or footnote.  You could want either one.
>
> To make it be interpreted as code, you simply prefix the $
> with a \.  That takes away org's special handling of the
> syntax.  org's footnote code merely checks for a \ in front
> of the $ and then it knows not to do anything except remove
> the \.
>
> In fact, the footnote code doesn't even have to do that.
> The org extensible syntax code (the code for $[...]) is what
> does it.  The footnote code simply calls the extensible
> syntax code.
>
> To make it be a footnote, you don't do anything.
>
> This will work for all code examples you can dream up.
> There is no need to worry about which languages have $[...]
> in them.
>
> The advantage is that for future features, the same
> solutions will work.  And since the syntax is extensible, it
> will work for completely new features.
>
> Finally, the escaping scheme should be familiar to users, as
> it is a common method in programming languages.
>
> Is this idea possibly of interest?

Hi Samuel,

this is interesting and I will keep it in mind for the next
syntax change we will need.

Thanks.

- Carsten


>
>
> -- 
> For personal gain, myalgic encephalomyelitis denialists are knowingly
> causing further suffering and death by grossly corrupting science.  Do
> you care about the world?
> http://www.meactionuk.org.uk/What_Is_ME_What_Is_CFS.htm
>
>
> _______________________________________________
> Emacs-orgmode mailing list
> Remember: use `Reply All' to send replies to the list.
> Emacs-orgmode@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode

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

end of thread, other threads:[~2009-01-06 10:08 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2009-01-04 20:33 extensible syntax Samuel Wales
2009-01-05 16:19 ` Samuel Wales
2009-01-06 10:08   ` Carsten Dominik

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).