;;; embark-org.el --- Embark targets and actions for Org Mode -*- lexical-binding: t; -*-
;; Copyright (C) 2022 Free Software Foundation, Inc.
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
;; along with this program. If not, see <https://www.gnu.org/licenses/>.
;;; Commentary:
;; This package configures the Embark package for use in Org Mode
;; buffers. It teaches Embark a number of Org related targets and
;; appropriate actions. Currently it has table cells, whole tables,
;; source blocks and links. Targets to add: headings (Embark already
;; has generic support for outlines, so we just nee to add Org
;; specific actions), timestamps, etc.
;;; Code:
;;; Basic target finder for Org
;; There are very many org element and objects types, we'll only
;; recognize those for which there are specific actions we can put in
;; a keymap, or for even if there aren't any specific actions, if it's
;; import to be able to kill, delete or duplicate (embark-insert) them
;; conveniently. I'll start conservatively and we can add more later
;;; Custom Org actions
; good idea?
;;; Tables
;;; Links
;; The link support has a slightly complicated design in order to
;; achieve the following goals:
;; 1. RET should simply be org-open-at-point
;; 2. When the link is to a file, URL, email address or elisp
;; expression or command, we want to offer the user actions for
;; that underlying type.
;; 3. Even in those cases, we still want some actions to apply to the
;; entire link including description: actions to copy the link as
;; markdown, or just the link description or target.
;; So the strategy is as follows (illustrated with file links):
;; - The target will be just the file, without the description and
;; also without the "file:" prefix nor the "::line-number or search"
;; suffix. That way, file actions will correctly apply to it.
;; - The type will not be 'file, but 'org-file-link that way we can
;; register a keymap for 'org-file-link that inherits from both
;; embark-org-link-map (with RET bound to org-open-at-point and a
;; few other generic link actions) and embark-file-map.
;; - The commands to copy the link at point in some format will be
;; written as commands that act on the Org link at point. This way
;; they are independently (plausibly) useful, and we circumvent the
;; problem that the whole Org link is not actually the target (just
;; the inner file is!).
;; Alternative design I considered: separate each target into two, a
;; whole link target which includes the description and brackets and
;; what not; and an "inner target" which is just the file or URL or
;; whatever. Cons of this approach: much target cycling is required!
;; First of all, an unadorned embark-dwim definitely should be
;; org-open-at-point, which means the whole link target would need
;; priority. That means that any file, URL, etc. actions would require
;; you to cycle first. This sounds very inconvenient, the above
;; slightly more complex design allows both whole-link and inner
;; target actions to work without cycling.
;; The reason for this is left as an exercise to the reader.
;; Solution: Na ryvfc gnetrg znl cebzcg gur hfre sbe fbzrguvat!
;;; Source blocks and babel calls
;;; List items
;;; Org plain lists
;;; "Encode" region using Org export in place
;;; embark-org.el ends here