Function: org-link-precise-link-target

org-link-precise-link-target is a byte-compiled function defined in ol.el.gz.

Signature

(org-link-precise-link-target)

Documentation

Determine search string and description for storing a link.

If a search string (see org-link-search) is found, return list (SEARCH-STRING DESC POSITION). Otherwise, return nil.

If there is an active region, the contents (or a part of it, see org-link-context-for-files) is used as the search string.

In Org buffers, if point is at a named element (such as a source block), the name is used for the search string. If at a heading, its CUSTOM_ID is used to form a search string of the form
"#id", if present, otherwise the current heading text is used
in the form "*Heading".

If none of those finds a suitable search string, the current line is used as the search string.

The description DESC is nil (meaning the user will be prompted for a description when inserting the link) for search strings based on a region or the current line. For other cases, DESC is a cleaned-up version of the name or heading at point.

POSITION is the buffer position at which the search string matches.

Source Code

;; Defined in /usr/src/emacs/lisp/org/ol.el.gz
(defun org-link-precise-link-target ()
  "Determine search string and description for storing a link.

If a search string (see `org-link-search') is found, return
list (SEARCH-STRING DESC POSITION).  Otherwise, return nil.

If there is an active region, the contents (or a part of it, see
`org-link-context-for-files') is used as the search string.

In Org buffers, if point is at a named element (such as a source
block), the name is used for the search string.  If at a heading,
its CUSTOM_ID is used to form a search string of the form
\"#id\", if present, otherwise the current heading text is used
in the form \"*Heading\".

If none of those finds a suitable search string, the current line
is used as the search string.

The description DESC is nil (meaning the user will be prompted
for a description when inserting the link) for search strings
based on a region or the current line.  For other cases, DESC is
a cleaned-up version of the name or heading at point.

POSITION is the buffer position at which the search string
matches."
  (let* ((region (org-link--context-from-region))
         (result
          (cond
           (region
            (list (org-link--normalize-string region t)
                  nil
                  (region-beginning)))

           ((derived-mode-p 'org-mode)
            (let* ((element (org-element-at-point))
                   (name (org-element-property :name element))
                   (heading (org-element-lineage element '(headline inlinetask) t))
                   (custom-id (org-entry-get heading "CUSTOM_ID")))
              (cond
               (name
                (list name
                      name
                      (org-element-begin element)))
               ((org-before-first-heading-p)
                (list (org-link--normalize-string (org-current-line-string) t)
                      nil
                      (line-beginning-position)))
               (heading
                (list (if custom-id (concat "#" custom-id)
                        (org-link-heading-search-string))
                      (org-link--normalize-string
                       (org-get-heading t t t t))
                      (org-element-begin heading))))))

           ;; Not in an org-mode buffer, no region
           (t
            (list (org-link--normalize-string (org-current-line-string) t)
                  nil
                  (line-beginning-position))))))

    ;; Only use search option if there is some text.
    (when (org-string-nw-p (car result))
      result)))