5

I'm thinking of using literate programming to investigate large amount, or hard to understand source code. For the purpose, I'd like refactor the source code into literate programming text with org-mode/babel, so that I can add annotations of my study, questions, and comments freely, while I can tangle back to get the original source code.

I just wondering if any kind soul has already done something similar? At the moment, it could be simple as:

  1. Input the source code into org-mode/babel buffer, and wrap the whole source code into an initial code chunk;
  2. Provide a command to extract a region, or a sub-expression into separate code chunk with proper arrangement in terms of chunk name, headers, etc. so that the relationship in the source code can be expressed, and preserved, such as having another code check to aggregate those separated code chunk. (the name of the extracted code chunk may be automated as the first expression in the region, or something semantically making sense, and feasible)
  3. For more advance application, the tool can scan the source code directory, and generate an initial org-mode file with the source code being parsed into literate programming chunks for each major programming constructs, for each file, the header declaration, and each function/subroutine, etc., with proper arrangement to tangle back the original source code directories, and files.

The essence is to automate the manual operations in refactoring as much as possible.

I feel that this might be a tremendous help to study source code.

Please share pointers, thought, contributions.

Thanks, Yu

Improve this question

1 Answer 1

Reset to default
3

Your initial steps are a good starting point. You can implement #2 using Babel Templates and sessions. Having all the source blocks run in one sessions means you can easily split them into multiple chunks with the same result. Just make sure when you split it, it is not inside a loop. That would be OK for when you tangle, but it wouldn't let you execute the blocks inside the Org file.

Here are two Python Babel Templates that I use for this type of work:

(add-to-list 'org-structure-template-alist
             '("p" "#+BEGIN_SRC python :results output :exports none\n?\n#+END_SRC\n#+RESULTS:" "<src lang=\"python\">\n?\n</src>"))
(add-to-list 'org-structure-template-alist
             '("pe" "#+END_SRC\n#+RESULTS:\n?\n#+BEGIN_SRC python :results output :exports none\n" "</src>\n<src lang=\"python\">"))

The first one lets me type <pTAB and it expands to the default Python setup I want, and puts the cursor in between the #+BEGIN_SRC and #+END_SRC blocks. The second one will be more useful to you. Instead of beginning and ending a source block, it ends and then begins (that is, splits one block into two), and places the cursor between the two blocks where you can enter your thoughts on the code above and below.

You should expand the templates to include the session name in the header, and possible non-Babel text, such as section headings and sub-headings (**) assuming you want each block in a sub-section...

Improve this answer
4
  • Thanks for very good pointer. Your Babel template example, especially the second one definite will help my requirement 2. I'll see how much more I can leverage Babel template to implement the rest of the automation to reassemble to the original source code after splitting one more chunk.
    – Yu Shen
    Mar 23, 2015 at 23:04
  • You reassemble by adding :tangle foo.py to each block, and then org-babel-tangle. You might also want to have :session bar so you can execute each block and then inspect the results interactively.
    – mankoff
    Mar 24, 2015 at 0:31
  • My assumed model of using checks would be diffierent, I'd like to put all the decomposed chunks tangled into one big original file, hopefully no different than the orignial source code. To achieve this.I currently have a chunck collecting all the individual chunks decomposed from the original source code, in this collecting chunk, I have noweb yes in the header, and refers all those decomposed check by noweb reference, and tangle the collecting chunk :tangle source.py. That's why I wish to have the updating of the noweb reference in the collecting chunk automated once a new chunk is extracted.
    – Yu Shen
    Mar 24, 2015 at 2:31
  • Maybe, there is better way to achieve the purpose of tangle all those extracted chunks back into one common file.
    – Yu Shen
    Mar 24, 2015 at 2:31

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.