Browse Source

org-export: Make results of named code blocks a valid link target

* lisp/ox.el (org-export-search-cells): Use #+RESULTS keyword as
search cell when #+NAME is not provided.  Update the docstring
accordingly.
(org-export-resolve-fuzzy-link): Update the docstring.

* doc/org-manual.org (Exporting Code Blocks): Document the new
behavior and explain the details of exporting links to named code
blocks/results.

Fixes https://orgmode.org/list/010201826cb68597-bf75d596-7890-4dd0-b9ff-0c7b617b4dd4-000000@eu-west-1.amazonses.com
Ihor Radchenko 2 years ago
parent
commit
5184c4382d
2 changed files with 36 additions and 4 deletions
  1. 30 0
      doc/org-manual.org
  2. 6 4
      lisp/ox.el

+ 30 - 0
doc/org-manual.org

@@ -18369,6 +18369,36 @@ file is exported to, say, HTML or LaTeX formats.
   exported file.  Whether the code is evaluated at all depends on
   exported file.  Whether the code is evaluated at all depends on
   other options.  Example: =:exports none=.
   other options.  Example: =:exports none=.
 
 
+If a source block is named using =NAME= keyword, the same name will be
+assigned to the results of evaluation.  This way, fuzzy links pointing
+to the named source blocks exported using =:exports results= will
+remain valid and point to the results of evaluation.
+
+Results of evaluation of a named block can also be explicitly named
+using a separate =NAME= keyword.  The name value set via =NAME=
+keyword will be preferred over the parent source block.
+
+: #+NAME: code name
+: #+BEGIN_SRC emacs-lisp :exports both value
+: (+ 1 2)
+: #+END_SRC
+:
+: #+NAME: results name
+: #+RESULTS: code name
+: 3
+:
+: This [[code name][link]] will point to the code block.
+: Another [[results name][link]] will point to the results.
+
+Explicit setting of the result name may be necessary when a named code
+block is exported using =:exports both=.  Links to such block may
+arbitrarily point either to the code block or to its results when
+results do not have a distinct name.
+
+Note that all the links pointing to a source block exported using
+=:exports none= will be broken.  This will make export process fail,
+unless broken links are allowed during export (see [[*Export Settings]]). 
+
 #+vindex: org-export-use-babel
 #+vindex: org-export-use-babel
 To stop Org from evaluating code blocks to speed exports, use the
 To stop Org from evaluating code blocks to speed exports, use the
 header argument =:eval never-export= (see [[*Evaluating Code Blocks]]).
 header argument =:eval never-export= (see [[*Evaluating Code Blocks]]).

+ 6 - 4
lisp/ox.el

@@ -4305,7 +4305,7 @@ A search cell follows the pattern (TYPE . SEARCH) where
     - target's or radio-target's name as a list of strings if
     - target's or radio-target's name as a list of strings if
       TYPE is `target'.
       TYPE is `target'.
 
 
-    - NAME affiliated keyword if TYPE is `other'.
+    - NAME or RESULTS affiliated keyword if TYPE is `other'.
 
 
 A search cell is the internal representation of a fuzzy link.  It
 A search cell is the internal representation of a fuzzy link.  It
 ignores white spaces and statistics cookies, if applicable."
 ignores white spaces and statistics cookies, if applicable."
@@ -4323,7 +4323,8 @@ ignores white spaces and statistics cookies, if applicable."
 		(and custom-id (cons 'custom-id custom-id)))))))
 		(and custom-id (cons 'custom-id custom-id)))))))
     (`target
     (`target
      (list (cons 'target (split-string (org-element-property :value datum)))))
      (list (cons 'target (split-string (org-element-property :value datum)))))
-    ((and (let name (org-element-property :name datum))
+    ((and (let name (or (org-element-property :name datum)
+                        (car (org-element-property :results datum))))
 	  (guard name))
 	  (guard name))
      (list (cons 'other (split-string name))))
      (list (cons 'other (split-string name))))
     (_ nil)))
     (_ nil)))
@@ -4355,8 +4356,9 @@ Return value can be an object or an element:
 
 
 - If LINK path matches a target object (i.e. <<path>>) return it.
 - If LINK path matches a target object (i.e. <<path>>) return it.
 
 
-- If LINK path exactly matches the name affiliated keyword
-  (i.e. #+NAME: path) of an element, return that element.
+- If LINK path exactly matches the name or results affiliated keyword
+  (i.e. #+NAME: path or #+RESULTS: name) of an element, return that
+  element.
 
 
 - If LINK path exactly matches any headline name, return that
 - If LINK path exactly matches any headline name, return that
   element.
   element.