emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed

• * Proposal: references from code to text.
         [not found] <800808596.465327.1526131788117.ref@mail.yahoo.com>
  @ 2018-05-12 13:29 ` ZHUO QL (KDr2)
    2018-05-14  5:48   ` Eric S Fraga
    0 siblings, 1 reply; 17+ messages in thread
  From: ZHUO QL (KDr2) @ 2018-05-12 13:29 UTC (permalink / raw)
    To: emacs-orgmode
  
  [-- Attachment #1: Type: text/plain, Size: 5140 bytes --]
  
  Hi all, I just post a proposal for orgmode on my website(generated by orgmode):
  http://kdr2.com/tech/emacs/1805-proposal-org-ref-code-to-text.html .
  Here is the source of the proposal:
  # -*- mode: org; mode: auto-fill; -*-
  #+TITLE: Proposal for Orgmode: references from code to text.
  #+AUTHOR: KDr2
  
  #+OPTIONS: toc:nil
  #+OPTIONS: num:nil
  
  #+BEGIN: inc-file :file "common.inc.org"
  #+END:
  #+CALL: dynamic-header() :results raw
  #+CALL: meta-keywords(kws='("orgmode" "literate programming")) :results raw
  
  # - DATE
  <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:
  
  - *Text refers to text* \\
    In the exported/woven documentation, these references act as links,
    make interconnections between relevant topics.
  - *Text refers to code* \\
    The links in the exported/woven documentation can also link to a
    line of code if the code blocks are also included in the
    exported/woven documentation.
  - *Code refers to code* \\
    That's the most important part of the literate programming. This
    kind of references act as placeholders or something like macro in
    the C-programming language. With it, literate programming provides
    an ability to change the order of the source code from a
    machine-imposed sequence to one convenient to the human mind. [[https://en.wikipedia.org/wiki/Literate_programming#Example][Here
    is a simple Example depicts this concept]].
  - *Code refers to text* \\
    So far as I know, no literate programming tool has this kind of
    references. However, this kind of references could be very benifical
    too. Many programming languages have a mechanism to support
    embedding documentation(usually as comments) in the source code, AKA
    [[https://en.wikipedia.org/wiki/Docstring][Docstring]]. These embedded documentations are widely and conveniently
    used in editor, REPL and IDE. For instance, the docs of any elisp
    function that we can read in Emacs are from the elisp source.
  
    But in literate programming we seldom embed comments into the code
    blocks, as an impliaction the extracted/tangled code has no docs
    embeded. If we can refer to chunks of text in the code blocks, we
    will have the chance to include these chunks of text as embeded docs
    in the code in the tangling process, which results in
    well-documented source code. This is useful especially while the
    programmer are authoring reusable source code, like libraries or
    frameworks.
  
  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:
  
  #+BEGIN_SRC org
    ,#+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
  #+END_SRC
  
  The Org file above will produce the code below:
  
  #+BEGIN_SRC elisp
    (defun add (x y)
      "We use the function add to calculate the sum of two numbers."
      (+ x y))
  #+END_SRC
  
  - Beside the ~NAME~, we could also support reference via the
    ~CUSTOM_ID~ property or anything else that can locate a text chunk.
  - In the tangling process, we should do some kind of transformation of
    the target text, for example, escape the quote mark. A hook may be
    needed to let the user customize the transformation too.
  
  What do you think?
  
  * References
    - https://en.wikipedia.org/wiki/Literate_programming
    - https://en.wikipedia.org/wiki/Noweb
    - https://en.wikipedia.org/wiki/Docstring
    - http://orgmode.org/manual/Extracting-source-code.html#Extracting-source-code
    - http://orgmode.org/manual/Noweb-reference-syntax.html#Noweb-reference-syntax
    - http://orgmode.org/manual/Literal-examples.html#Literal-examples
    - https://orgmode.org/worg/dev/org-syntax.html
  
  * Discuss and Comment
    #+BEGIN: inc-file :file "comment.inc.org"
    #+END:
  
  [-- Attachment #2: Type: text/html, Size: 5484 bytes --]
  
  ^ permalink raw reply	[flat|nested] 17+ messages in thread

• • * Re: Proposal: references from code to text.
      2018-05-12 13:29 ` Proposal: references from code to text ZHUO QL (KDr2)
    @ 2018-05-14  5:48   ` Eric S Fraga
      2018-05-14 15:05     ` John Kitchin
      0 siblings, 1 reply; 17+ messages in thread
    From: Eric S Fraga @ 2018-05-14  5:48 UTC (permalink / raw)
      To: ZHUO QL (KDr2); +Cc: emacs-orgmode
    
    [-- Attachment #1: Type: text/plain, Size: 1158 bytes --]
    
    On Saturday, 12 May 2018 at 13:29, ZHUO QL (KDr2) wrote:
    > Hi all, I just post a proposal for orgmode on my website(generated by orgmode):
    > http://kdr2.com/tech/emacs/1805-proposal-org-ref-code-to-text.html .
    > Here is the source of the proposal:
    > # -*- mode: org; mode: auto-fill; -*-
    >
    > #+TITLE: Proposal for Orgmode: references from code to text.
    > #+AUTHOR: KDr2
    
    [...]
    
    > - Beside the ~NAME~, we could also support reference via the
    >   ~CUSTOM_ID~ property or anything else that can locate a text chunk.
    > - In the tangling process, we should do some kind of transformation of
    >   the target text, for example, escape the quote mark. A hook may be
    >   needed to let the user customize the transformation too.
    >
    > What do you think?
    
    I like the symmetry of having src reference text.  I guess, in what you
    propose above, that the text that would be incorporated would be a
    single element (in org parsing parlance) or else we would have to
    specify an extent in the link information.
    
    Are you able to implement something?  I would definitely help test it.
    
    -- 
    Eric S Fraga via Emacs 27.0.50, Org release_9.1.6-591-gee336b
    
    [-- Attachment #2: signature.asc --]
    [-- Type: application/pgp-signature, Size: 194 bytes --]
    
    ^ permalink raw reply	[flat|nested] 17+ messages in thread

  • • * Re: Proposal: references from code to text.
        2018-05-14  5:48   ` Eric S Fraga
      @ 2018-05-14 15:05     ` John Kitchin
        2018-05-14 17:06       ` Eric S Fraga
                               ` (2 more replies)
        0 siblings, 3 replies; 17+ messages in thread
      From: John Kitchin @ 2018-05-14 15:05 UTC (permalink / raw)
        To: ZHUO QL (KDr2), org-mode-email
      
      [-- Attachment #1: Type: text/plain, Size: 2404 bytes --]
      
      It seems like this is nearly all possible already (see below). It is a
      little wonky that you have to put text in a src txt block to achieve it,
      but otherwise what is missing?
      
      * 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).
      
      #+NAME: DOC-OF-ADD
      #+BEGIN_SRC txt
      "We use the function add to calculate the sum of two numbers."
      #+END_SRC
      
      #+NAME: ADD
      #+BEGIN_SRC emacs-lisp -n -r :noweb yes :tangle test.el
      (defun add (x y)
        <<DOC-OF-ADD>> ;; 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)
        )
      #+END_SRC
      
      #+RESULTS: ADD
      : add
      
      
      ** 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 Sun, May 13, 2018 at 10:48 PM, Eric S Fraga <esflists@gmail.com> wrote:
      
      > On Saturday, 12 May 2018 at 13:29, ZHUO QL (KDr2) wrote:
      > > Hi all, I just post a proposal for orgmode on my website(generated by
      > orgmode):
      > > http://kdr2.com/tech/emacs/1805-proposal-org-ref-code-to-text.html .
      > > Here is the source of the proposal:
      > > # -*- mode: org; mode: auto-fill; -*-
      > >
      > > #+TITLE: Proposal for Orgmode: references from code to text.
      > > #+AUTHOR: KDr2
      >
      > [...]
      >
      > > - Beside the ~NAME~, we could also support reference via the
      > >   ~CUSTOM_ID~ property or anything else that can locate a text chunk.
      > > - In the tangling process, we should do some kind of transformation of
      > >   the target text, for example, escape the quote mark. A hook may be
      > >   needed to let the user customize the transformation too.
      > >
      > > What do you think?
      >
      > I like the symmetry of having src reference text.  I guess, in what you
      > propose above, that the text that would be incorporated would be a
      > single element (in org parsing parlance) or else we would have to
      > specify an extent in the link information.
      >
      > Are you able to implement something?  I would definitely help test it.
      >
      > --
      > Eric S Fraga via Emacs 27.0.50, Org release_9.1.6-591-gee336b
      >
      
      [-- Attachment #2: Type: text/html, Size: 3666 bytes --]
      
      ^ permalink raw reply	[flat|nested] 17+ messages in thread

    • • * Re: Proposal: references from code to text.
          2018-05-14 15:05     ` John Kitchin
        @ 2018-05-14 17:06       ` Eric S Fraga
          2018-05-14 17:11       ` Eric S Fraga
          2018-05-15  4:49       ` ZHUO QL (KDr2)
          2 siblings, 0 replies; 17+ messages in thread
        From: Eric S Fraga @ 2018-05-14 17:06 UTC (permalink / raw)
          To: John Kitchin; +Cc: ZHUO QL (KDr2), org-mode-email
        
        [-- Attachment #1: Type: text/plain, Size: 341 bytes --]
        
        On Monday, 14 May 2018 at 08:05, John Kitchin wrote:
        > It seems like this is nearly all possible already (see below). It is a
        > little wonky that you have to put text in a src txt block to achieve it,
        > but otherwise what is missing?
        
        Ah, yes, quite nice.  Thanks!
        
        -- 
        Eric S Fraga via Emacs 27.0.50, Org release_9.1.6-591-gee336b
        
        [-- Attachment #2: signature.asc --]
        [-- Type: application/pgp-signature, Size: 194 bytes --]
        
        ^ permalink raw reply	[flat|nested] 17+ messages in thread

      • * Re: Proposal: references from code to text.
          2018-05-14 15:05     ` John Kitchin
          2018-05-14 17:06       ` Eric S Fraga
        @ 2018-05-14 17:11       ` Eric S Fraga
          2018-05-15  4:49       ` ZHUO QL (KDr2)
          2 siblings, 0 replies; 17+ messages in thread
        From: Eric S Fraga @ 2018-05-14 17:11 UTC (permalink / raw)
          To: John Kitchin; +Cc: ZHUO QL (KDr2), org-mode-email
        
        [-- Attachment #1: Type: text/plain, Size: 818 bytes --]
        
        ... continued ...
        
        although I found a strange bug in the tangling and noweb syntax.  I
        didn't want to have quotes in the text so I removed them and put them in
        the lisp src block instead:
        
        #+begin_src org
          ,#+NAME: ADD
          ,#+BEGIN_SRC emacs-lisp -n -r :noweb yes :tangle test.el
        
          (defun add (x y)
            "<<DOC-OF-ADD>>" ;; code to code
            (+ x y) (ref:add)
            )
          ,#+END_SRC
        #+end_src
        
        which when exported or tangled resulted in some strange quoting:
        
        #+begin_src emacs-lisp
          (defun add (x y)
            "
            "We use the function add to calculate the sum of two numbers." ;; code to code
            (+ x y) 
            )
        #+end_src
        
        I'm probably not supposed to put a <<...>> link within quotes but the
        output is surprising in any case.
        
        -- 
        Eric S Fraga via Emacs 27.0.50, Org release_9.1.6-591-gee336b
        
        [-- Attachment #2: signature.asc --]
        [-- Type: application/pgp-signature, Size: 194 bytes --]
        
        ^ permalink raw reply	[flat|nested] 17+ messages in thread

      • * Re: Proposal: references from code to text.
          2018-05-14 15:05     ` John Kitchin
          2018-05-14 17:06       ` Eric S Fraga
          2018-05-14 17:11       ` Eric S Fraga
        @ 2018-05-15  4:49       ` ZHUO QL (KDr2)
          2018-05-15 10:04         ` Eric S Fraga
          2 siblings, 1 reply; 17+ messages in thread
        From: ZHUO QL (KDr2) @ 2018-05-15  4:49 UTC (permalink / raw)
          To: John Kitchin, Emacs-org List
        
        [-- Attachment #1: Type: text/plain, Size: 1644 bytes --]
        
        Well, it's a nice approach.
        But it has a few cons:
        1. Putting text in a source block is not a very natural way. It may disturb the fluidity, both for writing the Org source and reading the exported document(e.g. html);2. The bug Eric just found while putting a <<...>> link within quotes, although, it may be easy to fix. 
        
         Greetings.
        
        ZHUO QL (KDr2, http://kdr2.com)
        
         
        
           On Monday, May 14, 2018, 11:06:34 PM GMT+8, John Kitchin <jkitchin@andrew.cmu.edu> wrote: 
         
         It seems like this is nearly all possible already (see below). It is a little wonky that you have to put text in a src txt block to achieve it, but otherwise what is missing?
        * 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).
        #+NAME: DOC-OF-ADD#+BEGIN_SRC txt"We use the function add to calculate the sum of two numbers."#+END_SRC
        #+NAME: ADD#+BEGIN_SRC emacs-lisp -n -r :noweb yes :tangle test.el(defun add (x y)  <<DOC-OF-ADD>> ;; 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)  )#+END_SRC
        #+RESULTS: ADD: add
        
        ** 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
        
          
        
        [-- Attachment #2: Type: text/html, Size: 3720 bytes --]
        
        ^ permalink raw reply	[flat|nested] 17+ messages in thread

      • • * Re: Proposal: references from code to text.
            2018-05-15  4:49       ` ZHUO QL (KDr2)
          @ 2018-05-15 10:04         ` Eric S Fraga
            2018-05-16  7:04           ` ZHUO QL (KDr2)
            0 siblings, 1 reply; 17+ messages in thread
          From: Eric S Fraga @ 2018-05-15 10:04 UTC (permalink / raw)
            To: ZHUO QL (KDr2); +Cc: Emacs-org List, John Kitchin
          
          [-- Attachment #1: Type: text/plain, Size: 510 bytes --]
          
          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
          
          [-- Attachment #2: signature.asc --]
          [-- Type: application/pgp-signature, Size: 194 bytes --]
          
          ^ permalink raw reply	[flat|nested] 17+ messages in thread

        • • * Re: Proposal: references from code to text.
              2018-05-15 10:04         ` Eric S Fraga
            @ 2018-05-16  7:04           ` ZHUO QL (KDr2)
              2018-05-16 14:25             ` John Kitchin
              0 siblings, 1 reply; 17+ messages in thread
            From: ZHUO QL (KDr2) @ 2018-05-16  7:04 UTC (permalink / raw)
              To: Eric S Fraga; +Cc: Emacs-org List, John Kitchin
            
            [-- Attachment #1: Type: text/plain, Size: 1128 bytes --]
            
            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  
            
            [-- Attachment #2: Type: text/html, Size: 2248 bytes --]
            
            ^ permalink raw reply	[flat|nested] 17+ messages in thread

          • • * Re: Proposal: references from code to text.
                2018-05-16  7:04           ` ZHUO QL (KDr2)
              @ 2018-05-16 14:25             ` John Kitchin
                2018-05-16 19:37               ` Samuel Wales
                                               ` (2 more replies)
                0 siblings, 3 replies; 17+ messages in thread
              From: John Kitchin @ 2018-05-16 14:25 UTC (permalink / raw)
                To: ZHUO QL (KDr2); +Cc: Eric S Fraga, Emacs-org List
              
              [-- Attachment #1: Type: text/plain, Size: 3955 bytes --]
              
              * 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
              @johnkitchin
              http://kitchingroup.cheme.cmu.edu
              
              
              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
              >
              
              [-- Attachment #2: Type: text/html, Size: 7040 bytes --]
              
              ^ permalink raw reply	[flat|nested] 17+ messages in thread

            • • * Re: Proposal: references from code to text.
                  2018-05-16 14:25             ` John Kitchin
                @ 2018-05-16 19:37               ` Samuel Wales
                  2018-05-17  2:29                 ` John Kitchin
                  2018-05-17  2:58               ` ZHUO QL (KDr2)
                  2018-06-15 18:07               ` Grant Rettke
                  2 siblings, 1 reply; 17+ messages in thread
                From: Samuel Wales @ 2018-05-16 19:37 UTC (permalink / raw)
                  To: John Kitchin; +Cc: ZHUO QL (KDr2), Eric S Fraga, Emacs-org List
                
                i'm not sure if i understand the goal.  is it babel-only?
                
                this email might be off-topic.
                
                what i want is links, using something like org-id,
                
                  - from non-org [for example, a link in file.el in a comment]
                  - to non-org [for example, a named or id'ed location in the same file]
                  - or to org [e.g. an org-id'ed org entry, or a named or id'ed
                location in a babel block]
                
                that can be, if needed, effectively, bidirectional.  thus, you could
                document a function in file.el using a subtree in main.org and bounce
                between the function and the documentation because there is a link for
                each.
                
                non-org [e.g. file.el] can be an original file [i.e. no babel
                anywhere] or the result of tangling from babel.
                
                i find that org-link-minor-mode is /highly/ useful for the non-org
                part of this, but it doesn't support all of the above functionality
                automatically.
                
                i'd want a general package that is like org-link-minor-mode, but takes
                care of supporting the user by creating good ids and links as needed.
                
                -- 
                The Kafka Pandemic: <http://thekafkapandemic.blogspot.com>
                
                The disease DOES progress. MANY people have died from it. And ANYBODY
                can get it at any time.
                
                ^ permalink raw reply	[flat|nested] 17+ messages in thread

              • • * Re: Proposal: references from code to text.
                    2018-05-16 19:37               ` Samuel Wales
                  @ 2018-05-17  2:29                 ` John Kitchin
                    2018-05-17  2:40                   ` Samuel Wales
                    0 siblings, 1 reply; 17+ messages in thread
                  From: John Kitchin @ 2018-05-17  2:29 UTC (permalink / raw)
                    To: Samuel Wales; +Cc: ZHUO QL (KDr2), Eric S Fraga, Emacs-org List
                  
                  [-- Attachment #1: Type: text/plain, Size: 1651 bytes --]
                  
                  You might want to check out linkd: https://www.emacswiki.org/emacs/linkd.el
                  
                  It does a lot of what you describe independently of org-mode.
                  
                  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:37 PM, Samuel Wales <samologist@gmail.com> wrote:
                  
                  > i'm not sure if i understand the goal.  is it babel-only?
                  >
                  > this email might be off-topic.
                  >
                  > what i want is links, using something like org-id,
                  >
                  >   - from non-org [for example, a link in file.el in a comment]
                  >   - to non-org [for example, a named or id'ed location in the same file]
                  >   - or to org [e.g. an org-id'ed org entry, or a named or id'ed
                  > location in a babel block]
                  >
                  > that can be, if needed, effectively, bidirectional.  thus, you could
                  > document a function in file.el using a subtree in main.org and bounce
                  > between the function and the documentation because there is a link for
                  > each.
                  >
                  > non-org [e.g. file.el] can be an original file [i.e. no babel
                  > anywhere] or the result of tangling from babel.
                  >
                  > i find that org-link-minor-mode is /highly/ useful for the non-org
                  > part of this, but it doesn't support all of the above functionality
                  > automatically.
                  >
                  > i'd want a general package that is like org-link-minor-mode, but takes
                  > care of supporting the user by creating good ids and links as needed.
                  >
                  > --
                  > The Kafka Pandemic: <http://thekafkapandemic.blogspot.com>
                  >
                  > The disease DOES progress. MANY people have died from it. And ANYBODY
                  > can get it at any time.
                  >
                  
                  [-- Attachment #2: Type: text/html, Size: 2639 bytes --]
                  
                  ^ permalink raw reply	[flat|nested] 17+ messages in thread

                • • * Re: Proposal: references from code to text.
                      2018-05-17  2:29                 ` John Kitchin
                    @ 2018-05-17  2:40                   ` Samuel Wales
                      0 siblings, 0 replies; 17+ messages in thread
                    From: Samuel Wales @ 2018-05-17  2:40 UTC (permalink / raw)
                      To: John Kitchin; +Cc: ZHUO QL (KDr2), Eric S Fraga, Emacs-org List
                    
                    interesting package!  but i'm not sure it would work with org as well
                    as org-link-minor-mode does.
                    
                    On 5/16/18, John Kitchin <jkitchin@andrew.cmu.edu> wrote:
                    > You might want to check out linkd: https://www.emacswiki.org/emacs/linkd.el
                    >
                    > It does a lot of what you describe independently of org-mode.
                    >
                    > 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:37 PM, Samuel Wales <samologist@gmail.com>
                    > wrote:
                    >
                    >> i'm not sure if i understand the goal.  is it babel-only?
                    >>
                    >> this email might be off-topic.
                    >>
                    >> what i want is links, using something like org-id,
                    >>
                    >>   - from non-org [for example, a link in file.el in a comment]
                    >>   - to non-org [for example, a named or id'ed location in the same file]
                    >>   - or to org [e.g. an org-id'ed org entry, or a named or id'ed
                    >> location in a babel block]
                    >>
                    >> that can be, if needed, effectively, bidirectional.  thus, you could
                    >> document a function in file.el using a subtree in main.org and bounce
                    >> between the function and the documentation because there is a link for
                    >> each.
                    >>
                    >> non-org [e.g. file.el] can be an original file [i.e. no babel
                    >> anywhere] or the result of tangling from babel.
                    >>
                    >> i find that org-link-minor-mode is /highly/ useful for the non-org
                    >> part of this, but it doesn't support all of the above functionality
                    >> automatically.
                    >>
                    >> i'd want a general package that is like org-link-minor-mode, but takes
                    >> care of supporting the user by creating good ids and links as needed.
                    >>
                    >> --
                    >> The Kafka Pandemic: <http://thekafkapandemic.blogspot.com>
                    >>
                    >> The disease DOES progress. MANY people have died from it. And ANYBODY
                    >> can get it at any time.
                    >>
                    >
                    
                    
                    -- 
                    The Kafka Pandemic: <http://thekafkapandemic.blogspot.com>
                    
                    The disease DOES progress. MANY people have died from it. And ANYBODY
                    can get it at any time.
                    
                    "You’ve really gotta quit this and get moving, because this is murder
                    by neglect." ---
                    <http://www.meaction.net/2017/02/03/pwme-people-with-me-are-being-murdered-by-neglect>.
                    
                    ^ permalink raw reply	[flat|nested] 17+ messages in thread

              • * Re: Proposal: references from code to text.
                  2018-05-16 14:25             ` John Kitchin
                  2018-05-16 19:37               ` Samuel Wales
                @ 2018-05-17  2:58               ` ZHUO QL (KDr2)
                  2018-05-17  3:10                 ` John Kitchin
                  2018-06-15 18:07               ` Grant Rettke
                  2 siblings, 1 reply; 17+ messages in thread
                From: ZHUO QL (KDr2) @ 2018-05-17  2:58 UTC (permalink / raw)
                  To: John Kitchin; +Cc: Eric S Fraga, Emacs-org List
                
                [-- Attachment #1: Type: text/plain, Size: 4265 bytes --]
                
                
                Hooray!
                Do we have a way to make that piece of code a predefined and callable code block that can be seen and called in any Org file? 
                 Greetings.
                
                ZHUO QL (KDr2, http://kdr2.com)
                
                 
                
                    On Wednesday, May 16, 2018, 10:26:41 PM GMT+8, John Kitchin <jkitchin@andrew.cmu.edu> wrote:  
                 
                 * 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-ADDWe 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@johnkitchin
                http://kitchingroup.cheme.cmu.edu
                
                
                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  
                
                  
                
                [-- Attachment #2: Type: text/html, Size: 9245 bytes --]
                
                ^ permalink raw reply	[flat|nested] 17+ messages in thread

              • • * Re: Proposal: references from code to text.
                    2018-05-17  2:58               ` ZHUO QL (KDr2)
                  @ 2018-05-17  3:10                 ` John Kitchin
                    2018-05-17  9:33                   ` ZHUO QL (KDr2)
                    0 siblings, 1 reply; 17+ messages in thread
                  From: John Kitchin @ 2018-05-17  3:10 UTC (permalink / raw)
                    To: ZHUO QL (KDr2); +Cc: Eric S Fraga, Emacs-org List
                  
                  [-- Attachment #1: Type: text/plain, Size: 4870 bytes --]
                  
                  I believe you can do that with the Library of Babel (
                  https://orgmode.org/worg/org-contrib/babel/library-of-babel.html)
                  
                  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 7:58 PM, ZHUO QL (KDr2) <zhuoql@yahoo.com> wrote:
                  
                  >
                  > Hooray!
                  >
                  > Do we have a way to make that piece of code a predefined and callable code
                  > block that can be seen and called in any Org file?
                  >
                  > Greetings.
                  >
                  > ZHUO QL (KDr2, http://kdr2.com)
                  >
                  >
                  >
                  > On Wednesday, May 16, 2018, 10:26:41 PM GMT+8, John Kitchin <
                  > jkitchin@andrew.cmu.edu> wrote:
                  >
                  >
                  > * 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
                  > @johnkitchin
                  > http://kitchingroup.cheme.cmu.edu
                  >
                  >
                  > 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
                  >
                  >
                  >
                  
                  [-- Attachment #2: Type: text/html, Size: 10704 bytes --]
                  
                  ^ permalink raw reply	[flat|nested] 17+ messages in thread

                • • * Re: Proposal: references from code to text.
                      2018-05-17  3:10                 ` John Kitchin
                    @ 2018-05-17  9:33                   ` ZHUO QL (KDr2)
                      2018-06-15 21:44                     ` John Kitchin
                      0 siblings, 1 reply; 17+ messages in thread
                    From: ZHUO QL (KDr2) @ 2018-05-17  9:33 UTC (permalink / raw)
                      To: John Kitchin; +Cc: Eric S Fraga, Emacs-org List
                    
                    [-- Attachment #1: Type: text/plain, Size: 670 bytes --]
                    
                    Thanks, that works perfectly. I made a simple summary of this thread on my site: http://kdr2.com/tech/emacs/1805-approach-org-ref-code-to-text.html
                    
                     Greetings.
                    
                    ZHUO QL (KDr2, http://kdr2.com)
                    
                     
                    
                       On Thursday, May 17, 2018, 11:11:39 AM GMT+8, John Kitchin <jkitchin@andrew.cmu.edu> wrote: 
                     
                     I believe you can do that with the Library of Babel (https://orgmode.org/worg/org-contrib/babel/library-of-babel.html)
                    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
                    
                      
                    
                    [-- Attachment #2: Type: text/html, Size: 2243 bytes --]
                    
                    ^ permalink raw reply	[flat|nested] 17+ messages in thread

                  • • * Re: Proposal: references from code to text.
                        2018-05-17  9:33                   ` ZHUO QL (KDr2)
                      @ 2018-06-15 21:44                     ` John Kitchin
                        0 siblings, 0 replies; 17+ messages in thread
                      From: John Kitchin @ 2018-06-15 21:44 UTC (permalink / raw)
                        To: ZHUO QL (KDr2); +Cc: Eric S Fraga, Emacs-org List
                      
                      [-- Attachment #1: Type: text/plain, Size: 1292 bytes --]
                      
                      Cool! I was inspired by this to try it with Python doctests. Check out the
                      result here: http://kitchingroup.cheme.cmu.edu/blog/2018/05/17/
                      Literate-programming-with-python-doctests/
                      
                      Note: I thought I had sent this email before, but it appeared as a draft
                      just now, so I am just sending it again.
                      
                      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 Thu, May 17, 2018 at 2:33 AM, ZHUO QL (KDr2) <zhuoql@yahoo.com> wrote:
                      
                      > Thanks, that works perfectly. I made a simple summary of this thread on my
                      > site: http://kdr2.com/tech/emacs/1805-approach-org-ref-code-to-text.html
                      >
                      >
                      > Greetings.
                      >
                      > ZHUO QL (KDr2, http://kdr2.com)
                      >
                      >
                      >
                      > On Thursday, May 17, 2018, 11:11:39 AM GMT+8, John Kitchin <
                      > jkitchin@andrew.cmu.edu> wrote:
                      >
                      >
                      > I believe you can do that with the Library of Babel (
                      > https://orgmode.org/worg/org-contrib/babel/library-of-babel.html)
                      >
                      > 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
                      >
                      >
                      
                      [-- Attachment #2: Type: text/html, Size: 3834 bytes --]
                      
                      ^ permalink raw reply	[flat|nested] 17+ messages in thread

              • * Re: Proposal: references from code to text.
                  2018-05-16 14:25             ` John Kitchin
                  2018-05-16 19:37               ` Samuel Wales
                  2018-05-17  2:58               ` ZHUO QL (KDr2)
                @ 2018-06-15 18:07               ` Grant Rettke
                  2 siblings, 0 replies; 17+ messages in thread
                From: Grant Rettke @ 2018-06-15 18:07 UTC (permalink / raw)
                  To: John Kitchin; +Cc: ZHUO QL (KDr2), Eric S Fraga, Emacs-org List
                
                On Wed, May 16, 2018 at 9:25 AM, John Kitchin <jkitchin@andrew.cmu.edu> wrote:
                > #+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
                
                This thread is great. Got me thinking about "true" one-time
                documentation definitions in the file itself. The blog post laid it
                all out very nicely.
                
                It got me wondering if I (or anybody) would like something like this
                style of use where you write your documentation in-line of the
                document using a macro that might look like this:
                
                Add a macro that you could use in the documentation like this both to
                define the string and include it in the export
                
                "The document adding function is pretty important to the doc function Add. .
                
                #+MACRO: add-string (eval (add-string "$1" "$2")
                
                Add a file buffer-local variable of key/value pairs for strings named 'strings'.
                
                Add helper functions with the same names here "get-string, add-string"
                to use it (pseudo code follows)
                
                #+name: add-string
                #+begin_src emacs-lisp :var key="default" :var value="default
                ;; if the key doesn't exist in the hashmap then add it and return the value
                ;; otherwise just return the value so it doesn't stomp on the existing value
                #+end_src
                
                Add would return the string, and that would get inserted in the export.
                
                Get-string would just get they key's value from the hashmap
                
                #+name: get-string
                #+begin_src emacs-lisp :var key="default"
                ;; if the key exists then return its value
                ;; otherwise return "UNDEFINED"
                #+end_src
                
                To use that documentation in the source block it would work the same as above
                
                It would be easy to add prettification to cut down on the "noise" of
                the syntax to use the macro and do the literate call, too that people
                might like.
                
                This is all pseudo code but I think it is in the same spirit of this
                thread. Do you?
                
                ^ permalink raw reply	[flat|nested] 17+ messages in thread

end of thread, other threads:[~2018-06-15 21:44 UTC | newest]

Thread overview: 17+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
     [not found] <800808596.465327.1526131788117.ref@mail.yahoo.com>
2018-05-12 13:29 ` Proposal: references from code to text ZHUO QL (KDr2)
2018-05-14  5:48   ` Eric S Fraga
2018-05-14 15:05     ` John Kitchin
2018-05-14 17:06       ` Eric S Fraga
2018-05-14 17:11       ` Eric S Fraga
2018-05-15  4:49       ` ZHUO QL (KDr2)
2018-05-15 10:04         ` Eric S Fraga
2018-05-16  7:04           ` ZHUO QL (KDr2)
2018-05-16 14:25             ` John Kitchin
2018-05-16 19:37               ` Samuel Wales
2018-05-17  2:29                 ` John Kitchin
2018-05-17  2:40                   ` Samuel Wales
2018-05-17  2:58               ` ZHUO QL (KDr2)
2018-05-17  3:10                 ` John Kitchin
2018-05-17  9:33                   ` ZHUO QL (KDr2)
2018-06-15 21:44                     ` John Kitchin
2018-06-15 18:07               ` Grant Rettke

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).