Function: org-export-get-reference

org-export-get-reference is a byte-compiled function defined in ox.el.gz.

Signature

(org-export-get-reference DATUM INFO)

Documentation

Return a unique reference for DATUM, as a string.

DATUM is either an element or an object. INFO is the current export state, as a plist.

References for the current document are stored in
:internal-references property. Its value is an alist with
associations of the following types:

  (REFERENCE . DATUM) and (SEARCH-CELL . ID)

REFERENCE is the reference string to be used for object or element DATUM. SEARCH-CELL is a search cell, as returned by org-export-search-cells. ID is a number or a string uniquely identifying DATUM within the document.

This function also checks :crossrefs property for search cells matching DATUM before creating a new reference.

Source Code

;; Defined in /usr/src/emacs/lisp/org/ox.el.gz
(defun org-export-get-reference (datum info)
  "Return a unique reference for DATUM, as a string.

DATUM is either an element or an object.  INFO is the current
export state, as a plist.

References for the current document are stored in
`:internal-references' property.  Its value is an alist with
associations of the following types:

  (REFERENCE . DATUM) and (SEARCH-CELL . ID)

REFERENCE is the reference string to be used for object or
element DATUM.  SEARCH-CELL is a search cell, as returned by
`org-export-search-cells'.  ID is a number or a string uniquely
identifying DATUM within the document.

This function also checks `:crossrefs' property for search cells
matching DATUM before creating a new reference."
  (let ((cache (plist-get info :internal-references)))
    (or (car (rassq datum cache))
	(let* ((crossrefs (plist-get info :crossrefs))
	       (cells (org-export-search-cells datum))
	       ;; Preserve any pre-existing association between
	       ;; a search cell and a reference, i.e., when some
	       ;; previously published document referenced a location
	       ;; within current file (see
	       ;; `org-publish-resolve-external-link').
	       ;;
	       ;; However, there is no guarantee that search cells are
	       ;; unique, e.g., there might be duplicate custom ID or
	       ;; two headings with the same title in the file.
	       ;;
	       ;; As a consequence, before re-using any reference to
	       ;; an element or object, we check that it doesn't refer
	       ;; to a previous element or object.
	       (new (or (cl-some
			 (lambda (cell)
			   (let ((stored (cdr (assoc cell crossrefs))))
			     (when stored
			       (let ((old (org-export-format-reference stored)))
				 (and (not (assoc old cache)) stored)))))
			 cells)
			(org-export-new-reference cache)))
	       (reference-string (org-export-format-reference new)))
	  ;; Cache contains both data already associated to
	  ;; a reference and in-use internal references, so as to make
	  ;; unique references.
	  (dolist (cell cells) (push (cons cell new) cache))
	  ;; Retain a direct association between reference string and
	  ;; DATUM since (1) not every object or element can be given
	  ;; a search cell (2) it permits quick lookup.
	  (push (cons reference-string datum) cache)
	  (plist-put info :internal-references cache)
	  reference-string))))