From mboxrd@z Thu Jan 1 00:00:00 1970 From: John Kitchin Subject: Re: Proposal: references from code to text. Date: Wed, 16 May 2018 07:25:33 -0700 Message-ID: References: <800808596.465327.1526131788117.ref@mail.yahoo.com> <800808596.465327.1526131788117@mail.yahoo.com> <871seebxdt.fsf@gmail.com> <385386647.1304827.1526359774932@mail.yahoo.com> <87wow5s0a4.fsf@gmail.com> <408787171.1793110.1526454275347@mail.yahoo.com> Mime-Version: 1.0 Content-Type: multipart/alternative; boundary="000000000000e655fa056c537d42" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:41817) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fIxN8-0001g2-MH for emacs-orgmode@gnu.org; Wed, 16 May 2018 10:25:45 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fIxN2-0008PZ-82 for emacs-orgmode@gnu.org; Wed, 16 May 2018 10:25:42 -0400 Received: from mail-wr0-x230.google.com ([2a00:1450:400c:c0c::230]:44872) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1fIxN1-0008No-Br for emacs-orgmode@gnu.org; Wed, 16 May 2018 10:25:35 -0400 Received: by mail-wr0-x230.google.com with SMTP id y15-v6so1502185wrg.11 for ; Wed, 16 May 2018 07:25:35 -0700 (PDT) In-Reply-To: <408787171.1793110.1526454275347@mail.yahoo.com> List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: "Emacs-orgmode" To: "ZHUO QL (KDr2)" Cc: Eric S Fraga , Emacs-org List --000000000000e655fa056c537d42 Content-Type: text/plain; charset="UTF-8" * 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. <> ;; code to code <>" ;; [[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 @johnkitchin http://kitchingroup.cheme.cmu.edu On Wed, May 16, 2018 at 12:04 AM, ZHUO QL (KDr2) 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 > --000000000000e655fa056c537d42 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
* Main document

See [[id:BAD= 97113-3561-4A4A-BA07-0CD5BF6BA35F][There is a reason we only support two ar= gs]] (text to text) for notes about this function. The addition is done in = line [[(add)]] (text to code).

Here we put names o= n 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: a= dd-options
- one
- two
- three
- an= d 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 escap= e 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 i= sn't in the middle of your document like this.

#+name: get-string
#+BEGIN_SRC emacs-lisp :var name=3D"add-= options"
(let ((el (org-element-map (org-element-parse-buffe= r) org-element-all-elements
=C2=A0 =C2=A0 (lambda (el)
=C2=A0 =C2=A0 =C2=A0 (when (string=3D (org-element-property :name el) = name)
el))
=C2=A0 =C2=A0 nil t)))
=C2= =A0 (let ((s (buffer-substring (org-element-property :contents-begin el)
=C2=A0 =C2=A0 =C2=A0(org-= element-property :contents-end el))))
=C2=A0 =C2=A0 (replace-rege= xp-in-string "\\\"" "\\\\\"" s)))
#= +END_SRC


Now, we can use those elem= ents in a src-block like this.

#+NAME: ADD
#+BEGIN_SRC emacs-lisp -n -r :noweb yes :tangle test.el
(defun= add (x y)
=C2=A0 "One line description of adding X and Y.
=C2=A0 <<get-string("DOC-OF-ADD")>> ;; code = to code
=C2=A0 <<get-string("add-options")>>= ;"
=C2=A0 ;; [[id:BAD97113-3561-4A4A-BA07-0CD5BF6BA35F][Ther= e is a reason we only support two args]] code to text
=C2=A0 (+ x= y) (ref:add)
=C2=A0 ;; it appears the coderef needs to be on it&= #39;s own line, otherwise you get a org-link-search: No match for coderef: = add when you click on the link.
=C2=A0 )
#+END_SRC

#+RESULTS: ADD
: add

The above block tangles to this for me:

#+BEGIN_= SRC emacs-lisp
(defun add (x y)
=C2=A0 "One line d= escription of adding X and Y.
=C2=A0 We use the function add to c= alculate the sum of two numbers.
=C2=A0 =C2=A0;; code to code
=C2=A0 - one
=C2=A0 - two
=C2=A0 - three
=C2=A0 - and of course \"optional things\"
=C2=A0 &q= uot;
=C2=A0 ;; [[id:BAD97113-3561-4A4A-BA07-0CD5BF6BA35F][There i= s a reason we only support two args]] code to text
=C2=A0 (+ x y)= =C2=A0
=C2=A0 ;; it appears the coderef needs to be on it's o= wn line, otherwise you get a org-link-search: No match for coderef: add whe= n you click on the link.
=C2=A0 )

#+END_= SRC


** Notes

*** There is a reason we only support two args
=C2=A0 =C2=A0 := PROPERTIES:
=C2=A0 =C2=A0 :ID:=C2=A0 =C2=A0 =C2=A0 =C2=A0BAD97113= -3561-4A4A-BA07-0CD5BF6BA35F
=C2=A0 =C2=A0 :END:


John

-----------------------------------
Professor= John Kitchin=C2=A0
Doherty Hall A207F
Department of Chemical Enginee= ring
Carnegie Mellon University
Pittsburgh, PA 15213
412-268-7803<= /div>

On Wed, May 16, 2018 at 12:04 AM, ZHUO QL (K= Dr2) <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=C2=A0javadoc format).=C2=A0=C2=A0

=
I think the direct reference from code to text is better. I will= try to implement=C2=A0it, but I'm not very familiar=C2=A0with 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=C2=A0 :)

Greetings.

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



=20
=20
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.=C2=A0

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

--
Eric S Fraga via Ema= cs 27.0.50, Org release_9.1.6-591-gee336b

--000000000000e655fa056c537d42--