[Orgmode] [BABEL][PROPOSAL] headlines as executable srcnames

[Jambunathan K]

Jambu> I think there is a strong case for making headlines act as babel
Jambu> srcnames with their body providing content for noweb expansion
Jambu> [3]. This behaviour could be controlled by a buffer local
Jambu> variable.

Eric> This is an interesting suggestion.  Next time I have time I will
Eric> but together a trail implementation to see how naturally this fits
Eric> into the rest of the Babel system.  There could be issues
Eric> (e.g. how to do set header arguments for the headline).

Good to hear this.

I am attaching a mail that I had (accidentally) unicast to Sebastien
elaborating on the possibilities. This could be of interest to the list.

Jambu> If babel supports headlines as srcnames, without requiring additional
Jambu> begin/end directives one could just write,
Jambu>
Jambu> * org-list
Jambu>   - one
Jambu>   - two
Jambu>   - three
Jambu>
Jambu> #+begin_src emacs-lisp :tangle yes :noweb yes
Jambu>   "
Jambu>   <<org-list(:fmt latex)>>
Jambu>   "
Jambu> #+end_src
Jambu>
Jambu> and achieve similar results.
Jambu>

Eric> Yes, however the syntax you've used above to pass a header
Eric> argument to the org-lisp code block violates the existing noweb
Eric> syntax.  The place where you've inserted ":fmt latex" is reserved
Eric> for passing regular arguments to code blocks.

That is precisely my point. 

If org headlines are srcnames there is every reason that they take
arguments. See my attached mail that talks of implicit 'this' and ':fmt'
parameters.

I am not as concerned about the existing syntax, as the possibilities
that could potentially unfold with this mind-twister.

Eric> There has been discussion of allowing post-processing forms for
Eric> code blocks which would take the results of a code block as an
Eric> argument every time the code block has been called and whose
Eric> results would replace the actual code block results, however this
Eric> has not yet been implemented.

If headlines are considered as code blocks one actually inflate
headlines and execute them for interesting side-effects. The attached
mail elaborates on this point.

Thanks,
Jambunathan K.

Attachment: 

From: Jambunathan K <address@hidden>
Subject: Re: Composing letters using Org mode and the LaTeX isodoc class
To: Sébastien Vauban <address@hidden>
Date: Wed, 08 Sep 2010 21:07:26 +0530
Message-ID: <address@hidden>


Sébastien Vauban <address@hidden>
writes:

> Hi Jambunathan,
>
> Jambunathan K wrote:
>> Honoring spaces would be a pre-requisite if one were to allow org's
>> headlines as implicit srcnames.
>
> Or you would have to impose titles without spaces, which is acceptable as well
> for such a usage...
>

Org is for humans. We need spaces (pun intended).

This is why I find CamelCase words in a text document quite awkward. On
the otherhand, I don't find it awkward as variable and function names in
source code.

Read on ... More comments down below.

>
>> If babel supports headlines as srcnames, without requiring additional
>> begin/end directives one could just write,
>>
>> * org-list
>>   - one
>>   - two
>>   - three
>>
>> #+begin_src emacs-lisp :tangle yes :noweb yes
>>   "
>>   <<org-list(:fmt latex)>>
>>   "
>> #+end_src
>>
>> and achieve similar results.
>>
>> Based on my earlier efforts at letter-writing, I have the following
>> observation.
>>
>> Letters have a To address and they could be pulled from bbdb. So one
>> could say,
>>
>> * To
>>   [[a bbdb link]]
>>
>>
>> #+begin_src emacs-lisp :tangle yes :noweb yes
>>   "
>>   <<To(:fmt custom)>>
>>   "
>> #+end_src
>>
>> The string custom could be a elisp form or a function pointer that takes
>> the body of the headline as an argument and does the needful.
>>
>> Specifically in the above example, 'custom' handler would visit the bbdb
>> record, fetch the address and return the formatted address (with line
>> breaks etc etc) as the noweb expansion. [Custom handler would be
>> implemented by the user himself]
>>
>> Any thoughts on how this could be achieved ...
>
> That's going (really) far... But would that be do-able, waaoow!

Yes it is going far. 

Sometimes going far makes us feel elated while at other times it makes
us feel down and out ;-). In the present case, the experience would be
of the first kind. Otherwise would I dare suggest it?

I would provide an example and later summarize what the implications
are.

Before proceeding ahead we need to remember the following:

1. Headline in an org document is code.

   That is I can call it.  

   It always has an implicit 'this' parameter which is the 'content of
   the headline'. It could have additional parameters like :fmt as above
   (with :fmt text or :fmt org) being the default values.

2. (1) implies that I can 'execute' an org file.

Now an example.

* Isodoc 
  [[Link to page 9 of isodoc.pdf]]

* Extract of Isodoc for ready reference
  <Isodoc ()>>

Now if I execute the 'Extract ...' subtree I have essentially imported a
pdf page as text content. 

In the above example, the execution of headline would do some sort of
extract pdf pages and/or pdftotext. If the link were actually a gmane
thread it would amount to doing 'w3m -dump ...'.

Let's now take it even a bit further.

It seems that there are a good number of people who use 'one org file to
rule them all'. It also seems fairly common that one version controls an
agenda or a working file. Then it naturally follows that one would like
to import a git controlled file as a headline node in the master
file. 

This should be quite possible with the proposed enhancement.

* Agenda file
  [[git url]]

* Agenda Node
  <<Agenda file ()>>

Good thing is that I only need to tangle the headline to checkout the
agenda file on a remote server as a head line node. One could also think
of how one could git commit a headline node on the way out.

One could achieve Aliased Trees [1], Translations [2] and interesting
mashups like selective annotation [3] and agenda mashups[4]

[1] http://thread.gmane.org/gmane.emacs.orgmode/27108
    Plain import headline in another headline

[2] http://article.gmane.org/gmane.emacs.orgmode/27534/match=translation

    Tangling as language translation. Tangling a vocabulary node tangles
    the headline nodes to be translated which in turn 'pull' in the
    newly translation.

[3] http://thread.gmane.org/gmane.emacs.orgmode/24431/focus=24581
    
    Requests like a master TODO file that is 'shared' by teams,
    extracting text snippets from a file (that I don't have control
    over) and possibly view it side-by-side with my annotation etc etc
    have surfaced in the past in this mailing list.

[4] http://thread.gmane.org/gmane.emacs.orgmode/3273/focus=3274

Good thing is that all these workflows could be supported with little
effort and without impairing the simplicity and elegance of org-mode.

Jambunathan K.