forked from mirrors/org-mode
Custom IDs: Documentation and improvements
This commit is contained in:
Carsten Dominik
parent
53d0746d8d
commit
931e13d800
|
|
@ -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.
|
||||
|
|
|
|||
88
doc/org.texi
88
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
|
||||
the current file. 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}). The preferred
|
||||
match for such a link is a 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
|
||||
If the link does not look like a URL, it is considered to be internal in the
|
||||
current file. The most important case is a link like
|
||||
@samp{[[#my-custom-id]]} which will link to the entry with the
|
||||
@code{CUSTOM_ID} property @samp{my-custom-id}. Such custom IDs are very good
|
||||
for HTML export (@pxref{HTML export}) where they produce pretty section
|
||||
links. You are responsible yourself to make sure these custom IDs are unique
|
||||
in a file.
|
||||
|
||||
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
|
||||
link. In the above example the search would be for @samp{my target}.
|
||||
Links starting with a star like @samp{*My Target} restrict the search to
|
||||
headlines. 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:
|
||||
If no dedicated target exists, Org will search for the words in the link. In
|
||||
the above example the search would be for @samp{my target}. Links starting
|
||||
with a star like @samp{*My Target} restrict the search to
|
||||
headlines@footnote{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.}. 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
|
||||
(unsafe), or, if @file{org-id.el} is loaded and @code{org-link-to-org-use-id}
|
||||
is set, by ID property.
|
||||
to the target. Otherwise it points to the current headline, which will also
|
||||
be the description.
|
||||
|
||||
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
|
||||
indicate the current article/entry. For W3 and W3M buffers, the link goes to
|
||||
the current URL. For IRC links, if you set the variable
|
||||
@code{org-irc-link-to-logs} to non-nil then @kbd{C-c l} will store a
|
||||
@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.
|
||||
For IRC links, if you set the variable @code{org-irc-link-to-logs} to
|
||||
@code{t}, a @samp{file:/} style link to the relevant point in the logs for
|
||||
the current conversation is created. 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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
37
lisp/org.el
37
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"
|
||||
'create-if-interactive)
|
||||
(const :tag "Only use existing" 'use-existing)
|
||||
(const :tag "Create if storing link interactively"
|
||||
create-if-interactive)
|
||||
(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")
|
||||
|
|
|
|||
Loading…
Reference in New Issue