FW: [RFC] Link-type for attachments, more attach options

["Gustav Wikström" <gustav@whil.se>]

[-- Attachment #1.1: Type: text/plain, Size: 1056 bytes --]

Hi,

I’ve attached a patch with some suggested additions to org-attach. Patch comments below. Please review.

Kind regards
Gustav
___
Patch comments:
* Add new linktype "attached" for attachments

A new linktype "attached" is added in order to reduce link-duplication
when wanting to link to files in attached folders of nodes. This works
for both ID-based attachments and ATTACH_DIR.  Inline images will
trigger also for attachments, as well as search-decorations in the
links.  The goal is to make the functionality for attached-links
mirror file-links.

* Add further options for ATTACH_DIR

When working with ATTACH_DIR there are now a couple of new options available:
- org-attach-dir-inherit-by-default
- org-attach-dir-create-if-not-exist
- org-attach-dir-relative

Descriptions of them can be found in the commit for each new customization.

* Documentation in org-manual

Org-manual is updated with the new link-type as well as some minor
cleanup in the documentation related to external links and attachments.



[-- Attachment #1.2: Type: text/html, Size: 5038 bytes --]

[-- Attachment #2: 0001-org-attach-org-manual-org-New-link-type-more-attach-.patch --]
[-- Type: application/octet-stream, Size: 21974 bytes --]

From fe676033f871466493a9584972c3b110f4c55363 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gustav=20Wikstr=C3=B6m?= <gustav.erik@gmail.com>
Date: Sun, 23 Sep 2018 02:43:16 +0200
Subject: [PATCH] org-attach, org-manual, org: New link-type, more attach
 options

* Add new linktype "attached" for attachments

A new linktype "attached" is added in order to reduce link-duplication
when wanting to link to files in attached folders of nodes. This works
for both ID-based attachments and ATTACH_DIR.  Inline images will
trigger also for attachments, as well as search-decorations in the
links.  The goal is to make the functionality for attached-links
mirror file-links.

* Add further options for ATTACH_DIR

When working with ATTACH_DIR there are now a couple of new options available:
- org-attach-dir-inherit-by-default
- org-attach-dir-create-if-not-exist
- org-attach-dir-relative

Descriptions of them can be found in the commit for each new customization.

* Documentation in org-manual

Org-manual is updated with the new link-type as well as some minor
cleanup in the documentation related to external links and attachments.
---
 doc/org-manual.org | 144 +++++++++++++++++++++++++++------------------
 lisp/org-attach.el | 138 +++++++++++++++++++++++++++++++++++--------
 lisp/org.el        |  17 ++++--
 3 files changed, 212 insertions(+), 87 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 7945b7333..144f5993e 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -3137,6 +3137,7 @@ point on or at a target.
 #+cindex: irc links
 #+cindex: URL links
 #+cindex: file links
+#+cindex: attached links
 #+cindex: Rmail links
 #+cindex: MH-E links
 #+cindex: Usenet links
@@ -3148,38 +3149,63 @@ Org supports links to files, websites, Usenet and email messages, BBDB
 database entries and links to both IRC conversations and their logs.
 External links are URL-like locators.  They start with a short
 identifying string followed by a colon.  There can be no space after
-the colon.  The following list shows examples for each link type.
-
-| =http://www.astro.uva.nl/=dominik=        | on the web                     |
-| =doi:10.1000/182=                         | DOI for an electronic resource |
-| =file:/home/dominik/images/jupiter.jpg=   | file, absolute path            |
-| =/home/dominik/images/jupiter.jpg=        | same as above                  |
-| =file:papers/last.pdf=                    | file, relative path            |
-| =./papers/last.pdf=                       | same as above                  |
-| =file:/ssh:me@some.where:papers/last.pdf= | file, path on remote machine   |
-| =/ssh:me@some.where:papers/last.pdf=      | same as above                  |
-| =file:sometextfile::NNN=                  | file, jump to line number      |
-| =file:projects.org=                       | another Org file               |
-| =file:projects.org::some words=           | text search in Org file[fn:28] |
-| =file:projects.org::*task title=          | heading search in Org file     |
-| =file+sys:/path/to/file=                  | open via OS, like double-click |
-| =file+emacs:/path/to/file=                | force opening by Emacs         |
-| =docview:papers/last.pdf::NNN=            | open in doc-view mode at page  |
-| =id:B7423F4D-2E8A-471B-8810-C40F074717E9= | link to heading by ID          |
-| =news:comp.emacs=                         | Usenet link                    |
-| =mailto:adent@galaxy.net=                 | mail link                      |
-| =mhe:folder=                              | MH-E folder link               |
-| =mhe:folder#id=                           | MH-E message link              |
-| =rmail:folder=                            | Rmail folder link              |
-| =rmail:folder#id=                         | Rmail message link             |
-| =gnus:group=                              | Gnus group link                |
-| =gnus:group#id=                           | Gnus article link              |
-| =bbdb:R.*Stallman=                        | BBDB link (with regexp)        |
-| =irc:/irc.com/#emacs/bob=                 | IRC link                       |
-| =info:org#External links=                 | Info node link                 |
-| =shell:ls *.org=                          | shell command                  |
-| =elisp:org-agenda=                        | interactive Elisp command      |
-| =elisp:(find-file "Elisp.org")=           | Elisp form to evaluate         |
+the colon.
+
+This list shows the full set of built-in external link types:
+| http       | web                                 |
+| https      | secure web                          |
+| doi        | DOI for electronic resources        |
+| file       | file-links                          |
+| file+sys   | file-links forced to open via OS    |
+| file+emacs | file-links forced to open via emacs |
+| attached   | links to attachments for nodes      |
+| docview    | doc-view mode                       |
+| id         | Link to heading by id               |
+| news       | Usenet link                         |
+| mailto     | mail link                           |
+| mhe        | MH-E folder link                    |
+| rmail      | Rmail link                          |
+| gnus       | Gnus link                           |
+| bbdb       | BBDB link                           |
+| irc        | IRC link                            |
+| info       | Info link                           |
+| shell      | shell command                       |
+| elisp      | interactive elisp command link      |
+
+The following list shows examples for each link type.
+
+| =http://www.astro.uva.nl/=dominik=        | on the web                          |
+| =doi:10.1000/182=                         | DOI for an electronic resource      |
+| =file:/home/dominik/images/jupiter.jpg=   | file, absolute path                 |
+| =/home/dominik/images/jupiter.jpg=        | same as above                       |
+| =file:papers/last.pdf=                    | file, relative path                 |
+| =./papers/last.pdf=                       | same as above                       |
+| =file:/ssh:me@some.where:papers/last.pdf= | file, path on remote machine        |
+| =/ssh:me@some.where:papers/last.pdf=      | same as above                       |
+| =file:sometextfile::NNN=                  | file, jump to line number           |
+| =file:projects.org=                       | another Org file                    |
+| =file:projects.org::some words=           | text search in Org file[fn:28]      |
+| =file:projects.org::*task title=          | heading search in Org file          |
+| =file+sys:/path/to/file=                  | open via OS, like double-click      |
+| =file+emacs:/path/to/file=                | force opening by Emacs              |
+| =attached:projects.org=                   | file in folder attached to headline |
+| =attached:projects.org::some words=       | text search in attached file        |
+| =docview:papers/last.pdf::NNN=            | open in doc-view mode at page       |
+| =id:B7423F4D-2E8A-471B-8810-C40F074717E9= | link to heading by ID               |
+| =news:comp.emacs=                         | Usenet link                         |
+| =mailto:adent@galaxy.net=                 | mail link                           |
+| =mhe:folder=                              | MH-E folder link                    |
+| =mhe:folder#id=                           | MH-E message link                   |
+| =rmail:folder=                            | Rmail folder link                   |
+| =rmail:folder#id=                         | Rmail message link                  |
+| =gnus:group=                              | Gnus group link                     |
+| =gnus:group#id=                           | Gnus article link                   |
+| =bbdb:R.*Stallman=                        | BBDB link (with regexp)             |
+| =irc:/irc.com/#emacs/bob=                 | IRC link                            |
+| =info:org#External links=                 | Info node link                      |
+| =shell:ls *.org=                          | shell command                       |
+| =elisp:org-agenda=                        | interactive Elisp command           |
+| =elisp:(find-file "Elisp.org")=           | Elisp form to evaluate              |
 
 #+cindex: VM links
 #+cindex: Wanderlust links
@@ -3532,24 +3558,26 @@ the link completion function like this:
 :END:
 #+cindex: search option in file links
 #+cindex: file links, searching
+#+cindex: attached links, searching
 
-File links can contain additional information to make Emacs jump to
-a particular location in the file when following a link.  This can be
-a line number or a search option after a double colon[fn:35].  For
-example, when the command ~org-store-link~ creates a link (see
-[[*Handling Links]]) to a file, it encodes the words in the current line
-as a search string that can be used to find this line back later when
-following the link with {{{kbd(C-c C-o)}}}.
+File links and attached file links can contain additional information
+to make Emacs jump to a particular location in the file when following
+a link.  This can be a line number or a search option after a double
+colon[fn:35].  For example, when the command ~org-store-link~ creates
+a link (see [[*Handling Links]]) to a file, it encodes the words in the
+current line as a search string that can be used to find this line
+back later when following the link with {{{kbd(C-c C-o)}}}.
 
 Here is the syntax of the different ways to attach a search to a file
 link, together with explanations for each:
 
 #+begin_example
-[[file:~/code/main.c::255]]
-[[file:~/xx.org::My Target]]
-[[file:~/xx.org::*My Target]]
-[[file:~/xx.org::#my-custom-id]]
-[[file:~/xx.org::/regexp/]]
+  [[file:~/code/main.c::255]]
+  [[file:~/xx.org::My Target]]
+  [[file:~/xx.org::*My Target]]
+  [[file:~/xx.org::#my-custom-id]]
+  [[file:~/xx.org::/regexp/]]
+  [[attached:~/code/main.c::255]]
 #+end_example
 
 - =255= ::
@@ -7527,18 +7555,22 @@ node/task.  Small chunks of plain text can simply be stored in the
 subtree of a project.  Hyperlinks (see [[*Hyperlinks]]) can establish
 associations with files that live elsewhere on your computer or in the
 cloud, like emails or source code files belonging to a project.
-Another method is /attachments/, which are files located in
-a directory belonging to an outline node.  Org uses directories named
-by the unique ID of each entry.  These directories are located in the
-~data~ directory which lives in the same directory where your Org file
-lives[fn:86].  If you initialize this directory with =git init=, Org
-automatically commits changes when it sees them.  The attachment
-system has been contributed to Org by John Wiegley.
-
-In cases where it seems better to do so, you can attach a directory of
-your choice to an entry.  You can also make children inherit the
-attachment directory from a parent, so that an entire subtree uses the
-same attached directory.
+Another method is /attachments/, which are files located in a
+directory belonging to an outline node.  Org uses directories either
+named by the unique ID of each entry, or by the =ATTACH_DIR= property.
+ID-based directories are by default located in the ~data~ directory
+which lives in the same directory where your Org file lives[fn:86].
+If you initialize this directory with =git init=, Org automatically
+commits changes when it sees them.  The attachment system has been
+contributed to Org by John Wiegley.
+
+In cases where =ATTACH_DIR= property is used to declare attachments,
+you can choose to either use absolute (default) or relative links.
+You can also make children inherit the attachment directory from a
+parent, so that an entire subtree uses the same attached directory.
+
+See customization group =Org Attach= if you want to change the default
+settings for attachments to fit your preferred style.
 
 The following commands deal with attachments:
 
diff --git a/lisp/org-attach.el b/lisp/org-attach.el
index 53389f782..daf8cf2dd 100644
--- a/lisp/org-attach.el
+++ b/lisp/org-attach.el
@@ -57,6 +57,25 @@ where the Org file lives."
   :type 'directory
   :safe #'stringp)
 
+(defcustom org-attach-dir-inherit-by-default nil
+  "Defines whether ATTACH_DIR-directories should be inherited by
+  subheadings by default when created. Defaults to not being
+  inherited."
+  :group 'org-attach
+  :type 'boolean)
+
+(defcustom org-attach-dir-create-if-not-exists t
+  "Choose whether ATTACH_DIR-directories should be created if
+they do not exist since before. Default is to create them."
+  :group 'org-attach
+  :type 'boolean)
+
+(defcustom org-attach-dir-relative nil
+  "Choose whether ATTACH_DIR-directories should be added as
+relative links or not. Defaults to not relative."
+  :group 'org-attach
+  :type 'boolean)
+
 (defcustom org-attach-commit t
   "If non-nil commit attachments with git.
 This is only done if the Org file is in a git repository."
@@ -280,20 +299,26 @@ Throw an error if we cannot root the directory."
   "Set the ATTACH_DIR node property and ask to move files there.
 The property defines the directory that is used for attachments
 of the entry.  When called with `\\[universal-argument]', reset \
-the directory to
-the default ID based one."
+the directory to the default ID based one. Creates relative links
+if ORG-ATTACH-DIR-RELATIVE is t, and sets inheritance based on
+ORG-ATTACH-DIR-INHERIT-BY-DEFAULT"
   (interactive "P")
-  (let ((old (org-attach-dir))
-        (new
-         (progn
-           (if arg (org-entry-delete nil "ATTACH_DIR")
-             (let ((dir (read-directory-name
-                         "Attachment directory: "
-                         (org-entry-get nil
-                                        "ATTACH_DIR"
-                                        (and org-attach-allow-inheritance t)))))
-               (org-entry-put nil "ATTACH_DIR" dir)))
-           (org-attach-dir t))))
+  (let ((old (org-attach-dir nil))
+	(new
+	 (progn
+	   (if arg (org-entry-delete nil "ATTACH_DIR")
+	     (let* ((attach-dir (read-directory-name
+				 "Attachment directory: "
+				 (org-entry-get nil
+						"ATTACH_DIR")))
+		    (current-dir (file-name-directory (or load-file-name
+							  buffer-file-name)))
+		    (attach-dir-relative (file-relative-name attach-dir current-dir)))
+	       (if org-attach-dir-relative
+		   (org-entry-put nil "ATTACH_DIR" attach-dir-relative)
+		 (org-entry-put nil "ATTACH_DIR" attach-dir))))
+	   (org-attach-dir t))))
+    (when org-attach-dir-inherit-by-default (org-attach-set-inherit))
     (unless (or (string= old new)
                 (not old))
       (when (yes-or-no-p "Copy over attachments from old directory? ")
@@ -527,14 +552,15 @@ This ignores files ending in \"~\"."
   "Show the attachment directory of the current task.
 This will attempt to use an external program to show the directory."
   (interactive "P")
-  (let ((attach-dir (org-attach-dir (not if-exists))))
-    (and attach-dir (org-open-file attach-dir))))
+  (let* ((create-if-not-exist (if if-exists nil org-attach-dir-create-if-not-exists))
+	 (attach-dir (org-attach-dir create-if-not-exist)))
+    (when attach-dir (org-open-file attach-dir))))
 
 (defun org-attach-reveal-in-emacs ()
   "Show the attachment directory of the current task in dired."
   (interactive)
-  (let ((attach-dir (org-attach-dir t)))
-    (dired attach-dir)))
+  (let ((attach-dir (org-attach-dir org-attach-dir-create-if-not-exists)))
+    (when attach-dir (dired attach-dir))))
 
 (defun org-attach-open (&optional in-emacs)
   "Open an attachment of the current task.
@@ -543,15 +569,17 @@ This command will open the file using the settings in `org-file-apps'
 and in the system-specific variants of this variable.
 If IN-EMACS is non-nil, force opening in Emacs."
   (interactive "P")
-  (let* ((attach-dir (org-attach-dir t))
-	 (files (org-attach-file-list attach-dir))
-	 (file (if (= (length files) 1)
-		   (car files)
-		 (completing-read "Open attachment: "
-				  (mapcar #'list files) nil t)))
-         (path (expand-file-name file attach-dir)))
-    (org-attach-annex-get-maybe path)
-    (org-open-file path in-emacs)))
+  (let ((attach-dir (org-attach-dir org-attach-dir-create-if-not-exists)))
+    (if attach-dir
+	(let* ((files (org-attach-file-list attach-dir))
+	       (file (if (= (length files) 1)
+			 (car files)
+		       (completing-read "Open attachment: "
+					(mapcar #'list files) nil t)))
+	       (path (expand-file-name file attach-dir)))
+	  (org-attach-annex-get-maybe path)
+	  (org-open-file path in-emacs))
+      (message "No attachment exists!"))))
 
 (defun org-attach-open-in-emacs ()
   "Open attachment, force opening in Emacs.
@@ -570,6 +598,64 @@ Basically, this adds the path to the attachment directory, and a \"file:\"
 prefix."
   (concat "file:" (org-attach-expand file)))
 
+(defun org-attach-open-link (link &optional in-emacs)
+  "LINK is expanded with the attached directory and opened the same
+way as file-links are."
+  (interactive "P")
+  (let (line search)
+    (if (string-match "::\\([0-9]+\\)\\'" link)
+        (setq line (string-to-number (match-string 1 link))
+              link (substring link 0 (match-beginning 0)))
+      (if (string-match "::\\(.+\\)\\'" link)
+          (setq search (match-string 1 link)
+                link (substring link 0 (match-beginning 0)))))
+    (if (string-match "[*?{]" (file-name-nondirectory link))
+        (dired (org-attach-expand link))
+      (org-open-file (org-attach-expand link) in-emacs line search))))
+
+(defun org-attach-complete-link ()
+  "Advise the user with the available files in the attachment
+directory."
+  (let (file link attached-dir)
+    (setq attached-dir (expand-file-name (org-attach-dir)))
+    (setq file (read-file-name "File: " attached-dir))
+    (let ((pwd (file-name-as-directory attached-dir))
+          (pwd1 (file-name-as-directory (abbreviate-file-name
+                                         attached-dir))))
+      (cond
+       ((string-match (concat "^" (regexp-quote pwd1) "\\(.+\\)") file)
+        (setq link  (concat "attached:" (match-string 1 file))))
+       ((string-match (concat "^" (regexp-quote pwd) "\\(.+\\)")
+                      (expand-file-name file))
+        (setq link  (concat
+                     "attached:" (match-string 1 (expand-file-name file)))))
+       (t (setq link (concat "attached:" file)))))
+    link))
+
+(defun org-attach-export-link (link description format)
+  "Export an \"attached\" link from Org files."
+  (save-excursion
+    (let (path desc)
+      (if (string-match "::\\([0-9]+\\)\\'" link)
+          (setq link (substring link 0 (match-beginning 0)))
+        (if (string-match "::\\(.+\\)\\'" link)
+            (setq link (substring link 0 (match-beginning 0)))))
+      (search-forward (concat "attached:" (org-link-escape link)))
+      (setq path (file-relative-name (org-attach-expand link))
+            desc (or description link))
+      (pcase format
+        (`html (format "<a target=\"_blank\" href=\"%s\">%s</a>" path desc))
+        (`latex (format "\\href{%s}{%s}" path desc))
+        (`texinfo (format "@uref{%s,%s}" path desc))
+        (`ascii (format "%s (%s)" desc path))
+        (`md (format "[%s](%s)" desc path))
+        (_ path)))))
+
+(org-link-set-parameters "attached"
+                         :follow 'org-attach-open-link
+                         :export 'org-attach-export-link
+                         :complete 'org-attach-complete-link)
+
 (defun org-attach-archive-delete-maybe ()
   "Maybe delete subtree attachments when archiving.
 This function is called by `org-archive-hook'.  The option
diff --git a/lisp/org.el b/lisp/org.el
index c0eaecdab..1eac53e0a 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -4427,6 +4427,7 @@ This is needed for font-lock setup.")
 		  (beg end))
 (declare-function org-agenda-set-restriction-lock "org-agenda" (&optional type))
 (declare-function org-agenda-skip "org-agenda" ())
+(declare-function org-attach-expand "org-attach" (&optional if-exists))
 (declare-function org-attach-reveal "org-attach" (&optional if-exists))
 (declare-function org-gnus-follow-link "org-gnus" (&optional group article))
 (declare-function org-indent-mode "org-indent" (&optional arg))
@@ -18759,7 +18760,7 @@ boundaries."
 	    ;; Check absolute, relative file names and explicit
 	    ;; "file:" links.  Also check link abbreviations since
 	    ;; some might expand to "file" links.
-	    (file-types-re (format "[][]\\[\\(?:file\\|[./~]%s\\)"
+	    (file-types-re (format "[][]\\[\\(?:file\\|attached\\|[./~]%s\\)"
 				   (if (not link-abbrevs) ""
 				     (format "\\|\\(?:%s:\\)"
 					     (regexp-opt link-abbrevs))))))
@@ -18768,14 +18769,20 @@ boundaries."
 	   ;; Check if we're at an inline image, i.e., an image file
 	   ;; link without a description (unless INCLUDE-LINKED is
 	   ;; non-nil).
-	   (when (and (equal "file" (org-element-property :type link))
+	   (when (and (or (equal "file" (org-element-property :type link))
+                          (equal "attached" (org-element-property :type link)))
 		      (or include-linked
 			  (null (org-element-contents link)))
 		      (string-match-p file-extension-re
 				      (org-element-property :path link)))
-	     (let ((file (expand-file-name
-			  (org-link-unescape
-			   (org-element-property :path link)))))
+	     (let ((file (if (equal "attached" (org-element-property :type link))
+			     (require 'org-attach)
+                             (org-attach-expand
+                              (org-link-unescape
+			       (org-element-property :path link)))
+			   (expand-file-name
+			    (org-link-unescape
+			     (org-element-property :path link))))))
 	       (when (file-exists-p file)
 		 (let ((width
 			;; Apply `org-image-actual-width' specifications.
-- 
2.19.1.windows.1