Custom IDs: Documentation and improvements

doc/ChangeLog

@@ -1,3 +1,8 @@
+2009-04-17  Carsten Dominik  <carsten.dominik@gmail.com>
+
+	* org.texi (Internal links): Document custom ids for links.
+	(Handling links): Document custom ids for links.
+
 2009-04-14  Carsten Dominik  <carsten.dominik@gmail.com>
 
 	* org.texi (CSS support): Document new class.

doc/org.texi

@@ -2660,14 +2660,23 @@ internal structure of all links, use the menu entry
 @cindex links, internal
 @cindex targets, for links
 
-If the link does not look like a URL, it is considered to be internal in
+If the link does not look like a URL, it is considered to be internal in the
-the current file.  Links such as @samp{[[My Target]]} or @samp{[[My
+current file.  The most important case is a link like
-Target][Find my target]]} lead to a text search in the current file.
+@samp{[[#my-custom-id]]} which will link to the entry with the
-The link can be followed with @kbd{C-c C-o} when the cursor is on the
+@code{CUSTOM_ID} property @samp{my-custom-id}.  Such custom IDs are very good
-link, or with a mouse click (@pxref{Handling links}).  The preferred
+for HTML export (@pxref{HTML export}) where they produce pretty section
-match for such a link is a dedicated target: the same string in double
+links.  You are responsible yourself to make sure these custom IDs are unique
-angular brackets.  Targets may be located anywhere; sometimes it is
+in a file.
-convenient to put them into a comment line. For example
+
+Links such as @samp{[[My Target]]} or @samp{[[My Target][Find my target]]}
+lead to a text search in the current file.
+
+The link can be followed with @kbd{C-c C-o} when the cursor is on the link,
+or with a mouse click (@pxref{Handling links}).  Links to custom IDs will
+point to the corresponding headline.  The preferred match for a text link is
+a @i{dedicated target}: the same string in double angular brackets.  Targets
+may be located anywhere; sometimes it is convenient to put them into a
+comment line. For example
 
 @example
 # <<My Target>>
@@ -2679,12 +2688,16 @@ text before the first headline is usually not exported, so the first such
 target should be after the first headline, or in the line directly before the
 first headline.}.
 
-If no dedicated target exists, Org will search for the words in the
+If no dedicated target exists, Org will search for the words in the link.  In
-link.  In the above example the search would be for @samp{my target}.
+the above example the search would be for @samp{my target}.  Links starting
-Links starting with a star like @samp{*My Target} restrict the search to
+with a star like @samp{*My Target} restrict the search to
-headlines.  When searching, Org mode will first try an exact match, but
+headlines@footnote{To insert a link targeting a headline, in-buffer
-then move on to more and more lenient searches.  For example, the link
+completion can be used.  Just type a star followed by a few optional letters
-@samp{[[*My Targets]]} will find any of the following:
+into the buffer and press @kbd{M-@key{TAB}}.  All headlines in the current
+buffer will be offered as completions.  @xref{Handling links}, for more
+commands creating links.}.  When searching, Org mode will first try an
+exact match, but then move on to more and more lenient searches.  For
+example, the link @samp{[[*My Targets]]} will find any of the following:
 
 @example
 ** My targets
@@ -2692,11 +2705,6 @@ then move on to more and more lenient searches.  For example, the link
 ** my 20 targets are
 @end example
 
-To insert a link targeting a headline, in-buffer completion can be used.
-Just type a star followed by a few optional letters into the buffer and
-press @kbd{M-@key{TAB}}.  All headlines in the current buffer will be
-offered as completions.  @xref{Handling links}, for more commands
-creating links.
 
 Following a link pushes a mark onto Org's own mark ring.  You can
 return to the previous position with @kbd{C-c &}.  Using this command
@@ -2814,23 +2822,43 @@ insert it into an Org file, and to follow the link.
 Store a link to the current location.  This is a @emph{global} command (you
 must create the key binding yourself) which can be used in any buffer to
 create a link.  The link will be stored for later insertion into an Org
-buffer (see below).
+buffer (see below).  What kind of link will be created depends on the current
+buffer: 
 
+@b{Org-mode buffers}@*
 @vindex org-link-to-org-use-id
 For Org files, if there is a @samp{<<target>>} at the cursor, the link points
-to the target.  Otherwise it points to the current headline, either by text
+to the target.  Otherwise it points to the current headline, which will also
-(unsafe), or, if @file{org-id.el} is loaded and @code{org-link-to-org-use-id}
+be the description.
-is set, by ID property.
 
+If the headline has a @code{CUSTOM_ID} property, a link to this custom ID
+will be stored.  In addition or alternatively (depending on the value of
+@code{org-link-to-org-use-id}), a globally unique @code{ID} property will be
+created and/or used to construct a link.  So using this command in Org
+buffers will potentially create two links: A human-readable from the custom
+ID, and one that is globally unique and works even if the entry is moved from
+file to file.  Later, when inserting the link, you need to decide which one
+to use.
+
+@b{Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus}@*
+Pretty much all Emacs mail clients are supported.  The link will point to the
+current article, or, in some GNUS buffers, to the group.  The description is
+constructed from the author and the subject.
+
+@b{Web browsers: W3 and W3M}@*
+Here the link will be the current URL, with the page title as description.
+
+@b{Contacts: BBDB}@*
+Links created in a BBDB buffer will point to the current entry.
+
+@b{Chat: IRC}@*
 @vindex org-irc-link-to-logs
-For VM, Rmail, Wanderlust, MH-E, Gnus and BBDB buffers, the link will
+For IRC links, if you set the variable @code{org-irc-link-to-logs} to
-indicate the current article/entry.  For W3 and W3M buffers, the link goes to
+@code{t}, a @samp{file:/} style link to the relevant point in the logs for
-the current URL.  For IRC links, if you set the variable
+the current conversation is created.  Otherwise an @samp{irc:/} style link to
-@code{org-irc-link-to-logs} to non-nil then @kbd{C-c l} will store a
+the user/channel/server under the point will be stored.
-@samp{file:/} style link to the relevant point in the logs for the current
-conversation.  Otherwise an @samp{irc:/} style link to the user/channel/server
-under the point will be stored.
 
+@b{Other files}@*
 For any other files, the link will point to the file, with a search string
 (@pxref{Search options}) pointing to the contents of the current line.  If
 there is an active region, the selected words will form the basis of the

lisp/ChangeLog

@@ -1,3 +1,11 @@
+2009-04-17  Carsten Dominik  <carsten.dominik@gmail.com>
+
+	* org.el (org-link-to-org-use-id): New possible value
+	`create-if-interactive-and-no-custom-id'.
+	(org-store-link): Use custom IDs.
+	(org-link-search): Find custom ID properties from #link.
+	(org-default-properties): Add CUSTOM_ID for property completion.
+
 2009-04-16  Carsten Dominik  <carsten.dominik@gmail.com>
 
 	* org-html.el (org-export-as-html): Use custom IDs in the toc.

lisp/org.el

@@ -1086,7 +1086,7 @@ It should match if the message is from the user him/herself."
   :group 'org-link-store
   :type 'regexp)
 
-(defcustom org-link-to-org-use-id 'create-if-interactive
+(defcustom org-link-to-org-use-id 'create-if-interactive-and-no-custom-id
   "Non-nil means, storing a link to an Org file will use entry IDs.
 
 Note that before this variable is even considered, org-id must be loaded,
@@ -1115,9 +1115,11 @@ nil   Never use an ID to make a link, instead link using a text search for
   :group 'org-link-store
   :type '(choice
 	  (const :tag "Create ID to make link" t)
-	  (const :tag "Create if string link interactively"
+	  (const :tag "Create if storing link interactively"
-		 'create-if-interactive)
+		 create-if-interactive)
-	  (const :tag "Only use existing" 'use-existing)
+	  (const :tag "Create if storing link interactively and no CUSTOM_ID is present"
+		 create-if-interactive-and-no-custom-id)
+	  (const :tag "Only use existing" use-existing)
 	  (const :tag "Do not use ID to create link" nil)))
 
 (defcustom org-context-in-file-links t
@@ -6833,7 +6835,7 @@ For file links, arg negates `org-context-in-file-links'."
   (interactive "P")
   (org-load-modules-maybe)
   (setq org-store-link-plist nil)  ; reset
-  (let (link cpltxt desc description search txt)
+  (let (link cpltxt desc description search txt custom-id)
     (cond
 
      ((run-hook-with-args-until-success 'org-store-link-functions)
@@ -6903,6 +6905,7 @@ For file links, arg negates `org-context-in-file-links'."
 	    link (org-make-link cpltxt)))
 
      ((and buffer-file-name (org-mode-p))
+      (setq custom-id (org-entry-get nil "CUSTOM_ID"))
       (cond
        ((org-in-regexp "<<\\(.*?\\)>>")
 	(setq cpltxt
@@ -6914,6 +6917,9 @@ For file links, arg negates `org-context-in-file-links'."
 	     (or (eq org-link-to-org-use-id t)
 		 (and (eq org-link-to-org-use-id 'create-if-interactive)
 		      (interactive-p))
+		 (and (eq org-link-to-org-use-id 'create-if-interactive-and-no-custom-id)
+		      (interactive-p)
+		      (not custom-id))
 		 (and org-link-to-org-use-id
 		      (condition-case nil
 			  (org-entry-get nil "ID")
@@ -6980,7 +6986,12 @@ For file links, arg negates `org-context-in-file-links'."
 	(progn
 	  (setq org-stored-links
 		(cons (list link desc) org-stored-links))
-	  (message "Stored: %s" (or desc link)))
+	  (message "Stored: %s" (or desc link))
+	  (when custom-id
+	    (setq link (concat "file:" (abbreviate-file-name (buffer-file-name))
+			       "::#" custom-id))
+	    (setq org-stored-links
+		  (cons (list link desc) org-stored-links))))
       (and link (org-make-link-string link desc)))))
 
 (defun org-store-link-props (&rest plist)
@@ -7753,6 +7764,18 @@ in all files.  If AVOID-POS is given, ignore matches near that position."
      ;; First check if there are any special
      ((run-hook-with-args-until-success 'org-execute-file-search-functions s))
      ;; Now try the builtin stuff
+     ((and (equal (string-to-char s0) ?#)
+	   (> (length s0) 1)
+	   (save-excursion
+	     (goto-char (point-min))
+	     (and
+	      (re-search-forward
+	       (concat "^[ \t]*:CUSTOM_ID:[ \t]+" (regexp-quote (substring s0 1)) "[ \t]*$") nil t)
+	      (setq type 'dedicated
+		    pos (match-beginning 0))))
+	   ;; There is an exact target for this
+	   (goto-char pos)
+	   (org-back-to-heading t)))
      ((save-excursion
 	(goto-char (point-min))
 	(and
@@ -11095,7 +11118,7 @@ These are properties that are not defined in the property drawer,
 but in some other way.")
 
 (defconst org-default-properties
-  '("ARCHIVE" "CATEGORY" "SUMMARY" "DESCRIPTION"
+  '("ARCHIVE" "CATEGORY" "SUMMARY" "DESCRIPTION" "CUSTOM_LINK"
     "LOCATION" "LOGGING" "COLUMNS" "VISIBILITY"
     "TABLE_EXPORT_FORMAT" "TABLE_EXPORT_FILE"
     "EXPORT_FILE_NAME" "EXPORT_TITLE" "ORDERED")