From fb9a7538b5a6965cf10da2371bb93fdebf51ddb7 Mon Sep 17 00:00:00 2001 From: Mario Martelli Date: Sat, 1 Jul 2017 14:39:46 +0200 Subject: [PATCH 1/2] org.texi: Basic Org protocol documentation is added * doc/org.texi Basic Org protocol documentation is added --- doc/org.texi | 121 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 118 insertions(+), 3 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 879756e6f..76f491a78 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -7522,9 +7522,124 @@ are passed to Emacs through the @file{emacsserver}. For example, you can configure bookmarks in your web browser to send a link to the current page to Org and create a note from it using capture (@pxref{Capture}). Or you could create a bookmark that will tell Emacs to open the local source file of -a remote website you are looking at with the browser. See -@uref{http://orgmode.org/worg/org-contrib/org-protocol.php} for detailed -documentation and setup instructions. +a remote website you are looking at with the browser. + +Org protocol comes with three predefined handlers: +@table @asis +@item @code{org-protocol-store-link} + Triggered through the sub-protocol @code{store-link}. Store a +link and push the URL to the kill-ring. +@item @code{org-protocol-capture} + Fill a @code{capture} buffer with information gathered somewhere +else. This handler is triggered through the @code{capture} sub-protocol and +uses the function @code{org-capture}. +@item @code{org-protocol-open-source} + @code{open-source}. Map a URL to local filename. Use this to open +sources of already published contents in Emacs for editing. +@end table + +@node Setting up Org protocol +@subsection Setting up Org protocol +You need to set up a custom URL handler on your system to trigger Emacs by a +URL. This URL handler could be already installed by Emacs. Please consult the +handbook of your operating system how to install a custom URL handler if you +need to. + +To map a website with @code{open-source} to local files you have to set up +the mapping in @code{org-protocol-project-alist}. + +For example, in order to open files published on Worg locally, you can set +@code{org-protocol-project-alist} to the following + +@lisp +(setq org-protocol-project-alist + '(("Worg" + :base-url "http://orgmode.org/worg/" + :working-directory "/home/user/worg/" + :online-suffix ".html" + :working-suffix ".org"))) +@end lisp + +Two functions can help you fill @code{org-protocol-project-alist} with valid +contents: @code{org-protocol-create} and @code{org-publish-project-alist}. The +latter is of use if you're editing an Org file that is part of a +publishing project. + +@node Using Org protocol +@subsection Using Org protocol +Org protocol is triggered by @file{emacsclient}. If you want to use Org +protocol, there are many possibilities to do so. You can invoke emacsclient +by a shortcut on your desktop for example. Or by adding a bookmark to your browser. + +Here is the URL to use as @emph{Location} for browser bookmarks. Just remove the +line breaks and replace @code{sub-protocol} with the real sub-protocol to use: + +@example +javascript:location.href='org-protocol://sub-protocol? +template=x&url='+encodeURIComponent(window.location.href)+ +'&title='+encodeURIComponent(document.title)+ +'&body='+encodeURIComponent(window.getSelection()); +@end example + +This URL may be used for all three standard handlers in +@code{org-protocol.el}. Some of the values are ignored, +e.g. @code{store-link} uses the URL and title only. + +@table @asis +@item @code{org-store-link} + store a link, insertable through @kbd{M-x org-insert-link} and + push the URL found onto the kill-ring for yanking. + The sub-protocol used is @code{store-link}: + +@example +emacsclient org-protocol://store-link?url=URL&title=TITLE +@end example + +will store the following link: + +@example +[[URL][TITLE]] +@end example + +In addition, @code{URL} is pushed on the kill-ring for yanking. +You need to encode @code{URL} and @code{TITLE} if +they contain slashes, and probably quote those for the shell. + +To use this feature, add a bookmark with an arbitrary name, e.g. +@samp{Org: store-link} and enter this as @samp{Location}: + +@example +javascript:location.href='org-protocol://store-link? + url='+encodeURIComponent(location.href); +@end example + +@item @code{org-capture} +This one is triggered through the sub-protocol @code{capture} and consumes up +to four data fields: + +@example +@file{emacsclient} org-protocol:/capture?template=\ +TEMPLATE?url=URL?title=TITLE?body=BODY +@end example + +@noindent +pops up a @samp{Capture} buffer and fill the template with the data +submitted. + +To use this feature, add a bookmark with an arbitrary name, e.g. +@samp{Org: capture} and enter this as @samp{Location}: + + +@example +javascript:location.href='org-protocol:// +template=x&url='+encodeURIComponent(window.location.href)+ +'&title='+encodeURIComponent(document.title)+ +'&body='+encodeURIComponent(window.getSelection()); +@end example + +The result depends on the template used. + +@end table @node Refile and copy @section Refile and copy -- 2.11.0 (Apple Git-81)