From 0a0dda33cee7355602feb954e0645ed8652e0983 Mon Sep 17 00:00:00 2001 Message-Id: <0a0dda33cee7355602feb954e0645ed8652e0983.1659694297.git.yantar92@gmail.com> From: Ihor Radchenko Date: Fri, 5 Aug 2022 18:09:02 +0800 Subject: [PATCH] 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 --- doc/org-manual.org | 30 ++++++++++++++++++++++++++++++ lisp/ox.el | 10 ++++++---- 2 files changed, 36 insertions(+), 4 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index 466718e6e..e03fd059a 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -18283,6 +18283,36 @@ ** Exporting Code Blocks exported file. Whether the code is evaluated at all depends on 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 To stop Org from evaluating code blocks to speed exports, use the header argument =:eval never-export= (see [[*Evaluating Code Blocks]]). diff --git a/lisp/ox.el b/lisp/ox.el index 57d375b35..433272915 100644 --- a/lisp/ox.el +++ b/lisp/ox.el @@ -4312,7 +4312,7 @@ (defun org-export-search-cells (datum) - target's or radio-target's name as a list of strings if 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 ignores white spaces and statistics cookies, if applicable." @@ -4330,7 +4330,8 @@ (defun org-export-search-cells (datum) (and custom-id (cons 'custom-id custom-id))))))) (`target (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)) (list (cons 'other (split-string name)))) (_ nil))) @@ -4362,8 +4363,9 @@ (defun org-export-resolve-fuzzy-link (link info &rest pseudo-types) - If LINK path matches a target object (i.e. <>) 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 element. -- 2.35.1