Re: [babel] Painless integration of source blocks with language

From: "Eric Schulte" <schulte.eric@gmail.com>
To: Seth Burleigh <wburle@gmail.com>
Cc: emacs-orgmode@gnu.org
Subject: Re: [babel] Painless integration of source blocks with language
Date: Sat, 08 Jan 2011 18:54:31 -0700	[thread overview]
Message-ID: <87lj2ukfia.fsf@gmail.com> (raw)
In-Reply-To: AANLkTikJdwe11ndjHw=wGVG7W9tC6G2Jm8sZHECAaK9y@mail.gmail.com

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

Hi Seth,

Thanks for the thoughtful comments.  I especially like the method of
literate programming described in your second proposal.  Over the last
months I have switched from working mainly in code blocks to working
mainly in pure source files due to issues along the lines of those
mentioned in your first proposal.

It seems to me that working in two frames as you suggest -- e.g. writing
code in the pure code buffer, documentation in the Org-mode buffer, and
maintaining a constant mapping between the two -- would resolve the
issues mentioned in your first, and should be sufficient.  With some
elisp code it should be possible to support no-web in such a scheme
allowing the code buffer to be automatically re-organized based on
changes to the .org buffer.

A crude version of the above is already possible using the
`org-babel-detangle' function.  For example, follow the instructions in
the attached org-mode file (which uses elisp rather than clojure code
blocks simply for wider portability to non-clojure users).

Ultimately I think that more code support (possibly implemented using a
minor mode) allowing things like easy navigation, interactive
tangling/arrangement, noweb support, and (possibly) removing the need
for comment markers would be the preferred solution.

Cheers -- Eric

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: detangle.org --]
[-- Type: text/org, Size: 1514 bytes --]

#+Title: Detangle Example
#+Babel: :comments link :tangle detangle.el

This file demonstrates detangling of source files with Org-mode.

1. Evaluate this elisp code block to customize the behavior of link
   creation on your system -- in the future this could be folded into
   ob-tangle.
   #+begin_src emacs-lisp :results silent :tangle no
     (setq org-link-to-org-use-id nil)
   #+end_src
2. Tangle out this file by calling `[[elisp:(org-babel-tangle)]]' bound to
   =C-c C-v t=, notice the buffer-wide =:comments= and =:tangle=
   header arguments at the top of the file.
3. Open up the [[file:detangle.el][detangle.el]] file to find the tangled source code.
   Notice the comments which are used to associate parts of the source
   file with this org file.
4. Call the `org-babel-tangle-jump-to-org' function from one of the
   =message= lines in the elisp file to jump back to the related
   portion of this org file.
5. Navigate back to [[file:detangle.el][detangle.el]] and edit part of the elisp code
   (e.g. change the text of one of the messages), then call the
   `org-babel-detangle' function from inside of the elisp code
   buffer.  Notice that your edits have now been propagated back to
   the original Org-mode buffer.

* first
A first section.

#+source: a-named-block
#+begin_src emacs-lisp
  (message "this is the contents of the first code block.")
#+end_src

* second
A second section.

#+begin_src emacs-lisp
  (message "this block has no name -- it is the second code block")
#+end_src

[-- Attachment #3: Type: text/plain, Size: 3480 bytes --]

Seth Burleigh <wburle@gmail.com> writes:

> Preface: I hope attachments show up, i dont know if they are allowed ....
>

The attachments did make it through.

>
> Im currently interested in using babel for a medium size clojure project. I
> think the below propositions would greatly benefit babel in accomplishing
> literate programming.
>
> First part of the proposal to make this painless:
>
> In a literate document, you might very well have small chunks of code for
> one ns scattered around and then finally combined using noweb into one file
> and tangle the output. Currently, keys like
> compile-file (C-c C-k), goto function definition (M-.), do not work at all
> in the source blocks. This is unfortunate, and makes life very painful. So,
> first we need to get these keys to work.
> Heres how it can possibly be done.
>
> Lets say we want to compile the code in block A. Block B uses noweb syntax
> to import block A, and then tangles to file src/B.clj. So we need to search
> for  the presence of <<A>> in a tangled code chunk , tangle the chunk to a
> file, go to the file buffer and position the cursor at the correct relative
> position, and then invoke the appropriate function (in this case,
> slime-compile-and-load-file).
>
> Ive attached two files which do this, the first one is an example org file
> in which you can use the compile keystrokes on (after opening a slime server
> for clojure). However, it doesnt position the cursor in the tangled file
> correctly, but this is not needed for compile/load file. Its not a very good
> implementation, but it works for this case. Also, it doesn't work when the
> indirect buffer created by C-c '  is open. The advantage of this method is
> that it can easily be generalized to any language, since the compiler gets
> what it expects - a file of code to operate on.
>
> Second part of proposal:
>
> Literate documents are good for documentation, but if you're the author, you
> dont need the documentation and it will certainly get in the way of you
> writing code to keep having to type C-c ' to open various chunks of code.
> Ideally, we would like to have our file of code (that is, the tangled file
> output for one ns in clojure) as the top buffer, and our documentation at
> the bottom. Changes to the code will automatically reflect itself in the
> documentation (after a save). In order to accomplish this, there has to be a
> method to map from tangled file line number, to the correct chunk name and
> line number in the .org file. This might be accomplished by tangling code
> like this:
> ;;#chunk-name
> ..code
> ;;#
>
> I think this would be much more natural than editing each chunk separately.
> Of course, the ;;# might become an annoyance, but im sure there might  be a
> better way.
> With this mapping , we can develop the code until we get it right. Then we
> can hit a keystroke and have our documentation jump to the correct line
> number in the .org file, and then do all the documentation for that.
>
> With the line mapping ability also comes the ability to map errors in the
> line number to numbers in the org file. Although, this probably wouldn't be
> necessary, since we would be looking at the combined chunk file.
>
>
> Any thoughts/ideas how to implement this?
>
>
> _______________________________________________
> Emacs-orgmode mailing list
> Please use `Reply All' to send replies to the list.
> Emacs-orgmode@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode

[-- Attachment #4: Type: text/plain, Size: 201 bytes --]

_______________________________________________
Emacs-orgmode mailing list
Please use `Reply All' to send replies to the list.
Emacs-orgmode@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode