* 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:


John

-----------------------------------
Professor John Kitchin 
Doherty Hall A207F
Department of Chemical Engineering
Carnegie Mellon University
Pittsburgh, PA 15213
412-268-7803

On Wed, May 16, 2018 at 12:04 AM, ZHUO QL (KDr2) <zhuoql@yahoo.com> wrote:
Oh, that makes sense.

So in this way, we must put the text into quotes, and then into a txt code block. And also we don't have a chance to do any transformation of the text(e.g. org-mode list to javadoc format).  

I think the direct reference from code to text is better. I will try to implement it, but I'm not very familiar with the code base and don't have much time, so I can't give any commitment. But once I have anything to show, I'll be back here  :)

Greetings.

ZHUO QL (KDr2, http://kdr2.com)



On Tuesday, May 15, 2018, 6:05:31 PM GMT+8, Eric S Fraga <esflists@gmail.com> wrote:


On Tuesday, 15 May 2018 at 04:49, ZHUO QL (KDr2) wrote:

> 2. The bug Eric just found while putting a <> link within
> quotes, although, it may be easy to fix. 


I realised afterwards that it is not a bug but is a feature: org assumes
that anything before the << start of the link should be repeated on each
line of the incorporated src block.  This allows for easy incorporation
of code into a comment block, e.g. for C or sh etc.

--
Eric S Fraga via Emacs 27.0.50, Org release_9.1.6-591-gee336b