Re: [RFC] org-noweb: org-tangle + org-weave for literate programming using Org

[Grant Rettke <gcr@wisdomandwonder.com>]

Use Emacs to run Emacs Lisp and set
org-babel-use-quick-and-dirty-noweb-expansion to nil.
Grant Rettke | AAAS, ACM, ASA, FSF, IEEE, SIAM, Sigma Xi
gcr@wisdomandwonder.com | http://www.wisdomandwonder.com/
“Wisdom begins in wonder.” --Socrates
((λ (x) (x x)) (λ (x) (x x)))
“Life has become immeasurably better since I have been forced to stop
taking it seriously.” --Thompson


On Tue, Jun 10, 2014 at 9:46 AM, Nicolas Girard
<girard.nicolas@gmail.com> wrote:
> Hi folks,
>
> I've released today a couple of tools named "org-tangle" and
> "org-weave" in a public GitHub repository:
> https://github.com/ngirard/org-noweb
>
> I thought that Org's literate programming abilities deserved to be
> made accessible non-interactively from the command-line via "official"
> commands, and I hope this repository will help establish them.
>
> The benefits of such an approach I can think of are:
> - to provide people with reference tools they can refer to;
> - to isolate common behavior from people's customization that can be
> repeated consistently and reliably;
> - to lower the entry barrier for newcomers;
> - to attract the people who might just be interested in Org as a
> literate programming tool first, before grasping other areas of the
> Org "platform".
>
> Now, I'd be very glad if we could use this code as a starting point
> and discuss about it.
>
> For instance:
>
> - What should these tools do, and how ? It seemed to me that they
> should only glue functionality from external tools and libraries,
> rather than embedding functionality in their cores.
>
>   For instance, if org-weave ever had to gain cross-indexing and
> referencing features similar to its oldest siblings (weave, noweave),
> it should be achieved by leveraging some dedicated elisp package,
> LaTeX style file, or whatever, rather than implementing them itself.
>
>   What do you think ?
>
> - Into which language should these tools be written ? I've chosen the
> Bash shell because it's available almost everywhere. Does it seem ok
> for you ? Would it be useful to write them in POSIX-compliant code ?
>
> - About =org-tangle=: should it take only one org file, or several
> files, as an argument ?
>
>   I gave =org-tangle= the same behaviour than the code snippet that
> can be found in Org manual
> ([[info:org#Batch%20execution][info:org#Batch execution]]), so for now
> you can type
>
>   #+begin_src sh
>     org-tangle file1.org file2.org
>   #+end_src
>
>   But it makes more sense to me, that org-tangle takes only one file,
> and optionally the name of a source code block to be extracted, like
>
>   #+begin_src sh
>     org-tangle file.org [chunkname]
>   #+end_src
>
>   What do you think ?
>
> - About =org-babel-use-quick-and-dirty-noweb-expansion=: should it be
> set to 't' by default ? I'd be tempted to say yes, given the dramatic
> performance gain
>
> - etc, etc...
>
> Also, while not necessary, I thought it would be nice if org-noweb
> tools ate their own dogfoot and extracted themselves ; so I've written
> them in literate programming style and I have to say I really enjoyed
> the process.
>
> The tools are a mix of elisp and shell code, and it seems to me like
> Org + literate style really shine here at making the code readable and
> understandable.
>
> That said, there are a few quirks into the code I'd be glad to see disappear:
>
> 1. It made sense for me to write the command line options as an Org
> table (look at =#tblname: options= in
> https://raw.githubusercontent.com/ngirard/org-noweb/master/org-tangle.org)
> ; but if you see the docstring for the =-E= option, I wanted to write
> "Default value is <<emacs>>" but couldn't find a way to get this
> reference to expand ; so I had to manually write "Default value is
> xxxxx". Any hints ?
> 2. The boilerplate fonctions =escape-quotes= and =format-options= :
> could it be done in a better way ?
>
> Cheers,
>
> Nicolas
>