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:

#+NAME: DOC-OF-ADD
We use the function add to calculate the sum of two numbers.

#+BEGIN_SRC elisp
(defun add (x y)
  "(ref:text:DOC-OF-ADD)"
  (+ x y))
#+END_SRC

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?

Updates:

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

References

Discuss and Comment

Have few questions or feedback? Feel free to send me(killian.zhuo📧gmail.com) an email!

Copyright © KDr2, SOME RIGHTS RESERVED UNDER CC BY-NC 4.0.

Built with Emacs 28.2 (Org mode 9.5.5).

Last updated: 2022-01-28 Fri 13:42.