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
This commit is contained in:
Ihor Radchenko 2022-08-05 18:09:02 +08:00
parent 2dfdc89535
commit 5184c4382d
No known key found for this signature in database
GPG Key ID: 6470762A7DA11D8B
2 changed files with 36 additions and 4 deletions

View File

@ -18369,6 +18369,36 @@ file is exported to, say, HTML or LaTeX formats.
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]]).

View File

@ -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
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."
@ -4323,7 +4323,8 @@ ignores white spaces and statistics cookies, if applicable."
(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)))
@ -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 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.