* Main document
See [[id:BAD97113-3561-4A4A-BA07-0CD5BF6BA35F][There is a reason we only support two args]] (text to text) for notes about this function. The addition is done in line [[(add)]] (text to code).
Here we put names on different kinds of elements so we can put them into a tangled file later.
#+NAME: DOC-OF-ADD
We use the function add to calculate the sum of two numbers.
#+NAME: add-options
- one
- two
- three
- and of course "optional things"
We use a block like this to get the contents of an org-element by name as a string, and possibly transform it some how, e.g. in this case I escape quotes. I guess you could also use an exporter to convert it to what ever form you want. You might bury this block at the end in an appendix so it isn't in the middle of your document like this.
#+name: get-string
#+BEGIN_SRC emacs-lisp :var name="add-options"
(let ((el (org-element-map (org-element-parse-buffer) org-element-all-elements
(lambda (el)
(when (string= (org-element-property :name el) name)
el))
nil t)))
(let ((s (buffer-substring (org-element-property :contents-begin el)
(org-element-property :contents-end el))))
(replace-regexp-in-string "\\\"" "\\\\\"" s)))
#+END_SRC
Now, we can use those elements in a src-block like this.
#+NAME: ADD
#+BEGIN_SRC emacs-lisp -n -r :noweb yes :tangle test.el
(defun add (x y)
"One line description of adding X and Y.
<<get-string("DOC-OF-ADD")>> ;; code to code
<<get-string("add-options")>>"
;; [[id:BAD97113-3561-4A4A-BA07-0CD5BF6BA35F][There is a reason we only support two args]] code to text
(+ x y) (ref:add)
;; it appears the coderef needs to be on it's own line, otherwise you get a org-link-search: No match for coderef: add when you click on the link.
)
#+END_SRC
#+RESULTS: ADD
: add
The above block tangles to this for me:
#+BEGIN_SRC emacs-lisp
(defun add (x y)
"One line description of adding X and Y.
We use the function add to calculate the sum of two numbers.
;; code to code
- one
- two
- three
- and of course \"optional things\"
"
;; [[id:BAD97113-3561-4A4A-BA07-0CD5BF6BA35F][There is a reason we only support two args]] code to text
(+ x y)
;; it appears the coderef needs to be on it's own line, otherwise you get a org-link-search: No match for coderef: add when you click on the link.
)
#+END_SRC
** Notes
*** There is a reason we only support two args
:PROPERTIES:
:ID: BAD97113-3561-4A4A-BA07-0CD5BF6BA35F
:END: