Archives | Categories

Proposal for Orgmode: references from code to text.

<2018-05-12 Sat>

Literate programming is writing out the program logic in a human language with included (separated by a primitive markup) code snippets and macros. A preprocessor is used to substitute arbitrary hierarchies, or rather "interconnected 'webs' of macros", to produce the compilable source code with one command ("tangle"), and documentation with another ("weave").

So in a literate programming source file, any chunk is either a block of code or a block of document in a human language, I'll call them code and text below.

In my opinion, code and text should be able to reference each other:

Here is the implementation status of these kinds of references of noweb and Org mode (-> means 'has the ability to make reference to'):

tool text -> text code -> code text -> code code -> text
noweb No Yes No No
Org mode Yes, links Yes, noweb style Yes, (ref:*) No

As we saw, both noweb and Org mode do not implement the reference from code to text. Could we provide this feature in Org mode – the best and widely used literate programming tool?

As a proposal, in Org mode, we can mimic the labels in code blocks(i.e. text -> code reference), use something like (ref:text:<REF-NAME>) as the reference from code to text:

We use the function add to calculate the sum of two numbers.

#+BEGIN_SRC elisp
(defun add (x y)
  (+ x y))

The Org file above will produce the code below:

(defun add (x y)
  "We use the function add to calculate the sum of two numbers."
  (+ x y))

What do you think?


<2018-05-15 Tue> I also posted this article on the Orgmode mail list and Reddit, you can join the discussion there.


Discuss and Comment

Have few questions or feedback? Feel free to send me(zhuoql📧 an email!


Built with Emacs 25.2.2 (Org mode 9.0.5).

Last updated: 2018-05-15 Tue 16:37.

Green Web Hosting! This site hosted by DreamHost.