From mboxrd@z Thu Jan 1 00:00:00 1970 From: Nicolas Goaziou Subject: Re: org-protocol documentation Date: Thu, 06 Jul 2017 19:54:15 +0200 Message-ID: <8760f578oo.fsf@nicolasgoaziou.fr> References: <68E12968-9AF5-440A-B22C-AC55B70BA910@schnuddelhuddel.de> <87k248b6p8.fsf@nicolasgoaziou.fr> <7C76EDC3-CC7E-4AFE-B45B-867752C1B33A@schnuddelhuddel.de> <87a8519rlg.fsf@nicolasgoaziou.fr> <8760fp9mui.fsf@nicolasgoaziou.fr> <2FAD7DF2-2A0C-4703-A383-BA8D3346C691@schnuddelhuddel.de> <18D83D3C-C472-4614-988F-1F1DA5EB5CEC@schnuddelhuddel.de> <87efub7psj.fsf@nicolasgoaziou.fr> <87lgobrmm7.fsf@nicolasgoaziou.fr> <4D8D18D3-FBA7-4878-AB6A-76CE57635127@schnuddelhuddel.de> <878tk84fab.fsf@nicolasgoaziou.fr> <8760fc2joe.fsf@nicolasgoaziou.fr> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:40003) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dTAyw-0002cm-4r for emacs-orgmode@gnu.org; Thu, 06 Jul 2017 13:54:28 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dTAyr-0003by-6U for emacs-orgmode@gnu.org; Thu, 06 Jul 2017 13:54:26 -0400 Received: from relay3-d.mail.gandi.net ([2001:4b98:c:538::195]:42151) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1dTAyq-0003bF-Sq for emacs-orgmode@gnu.org; Thu, 06 Jul 2017 13:54:21 -0400 In-Reply-To: (Mario Martelli's message of "Sat, 1 Jul 2017 21:24:47 +0200") List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: "Emacs-orgmode" To: Mario Martelli Cc: emacs-orgmode@gnu.org --=-=-= Content-Type: text/plain Hello, Mario Martelli writes: > I started this whole thing because I wanted to learn elisp. But > learning texinfo en-passant is nice :) Thank you for your patch. I re-worded the documentation based on your work. I also added more index entries. Since I'm not using Org Protocol, I may fall wide of the mark. Anyway, it's now your turn to do some reviewing ;) WDYT? Regards, -- Nicolas Goaziou 0x80A93738 --=-=-= Content-Type: text/x-diff Content-Disposition: attachment; filename=0001-org.texi-Document-Org-Protocol.patch Content-Description: document Org Protocol >From 6caca7a57427efb67d5d1fdaf25232a46c96b2ba Mon Sep 17 00:00:00 2001 From: Nicolas Goaziou Date: Tue, 4 Jul 2017 14:48:41 +0200 Subject: [PATCH] org.texi: Document Org Protocol * doc/org.texi (Protocols): Document feature. --- doc/org.texi | 208 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 200 insertions(+), 8 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 176e7c259..e73c9c06a 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -499,6 +499,12 @@ Capture templates * Template expansion:: Filling in information about time and context * Templates in contexts:: Only show a template in a specific context +Protocols for external access + +* @code{store-link} protocol:: Store a link, push URL to kill-ring +* @code{capture} protocol:: Fill a buffer with external information +* @code{open-source} protocol:: Edit published contents + Archiving * Moving subtrees:: Moving a tree to an archive file @@ -7515,16 +7521,202 @@ For more information, including how to read atom feeds, see @node Protocols @section Protocols for external access @cindex protocols, for external access -@cindex emacsserver -You can set up Org for handling protocol calls from outside applications that -are passed to Emacs through the @file{emacsserver}. For example, you can +Org protocol in a mean to trigger custom actions in Emacs from external +applications. Any application that supports calling external programs with +an URL as argument may be used with this functionality. 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. +Org and create a note from it using capture (@pxref{Capture}). You can also +create a bookmark that tells Emacs to open the local source file of a remote +website you are browsing. + +@cindex Org protocol, set-up +@cindex Installing Org protocol +In order to use Org protocol from an application, you need to register +@samp{org-protocol://} as a valid scheme-handler. External calls are passed +to Emacs through the @code{emacsclient} command, so you also need to ensure +an Emacs server is running. More precisely, when the application calls + +@example +emacsclient org-protocol://PROTOCOL?key1=var1&key2=var2 +@end example + +@noindent +Emacs calls the handler associated to @samp{PROTOCOL} with argument +@samp{(:key1 var1 :key2 var2)}. + +@cindex protocol, new protocol +@cindex defining new protocols +Org protocol comes with three predefined protocols, detailed in the following +sections. Configure @code{org-protocol-protocol-alist} to define your own. + +@menu +* @code{store-link} protocol:: Store a link, push URL to kill-ring +* @code{capture} protocol:: Fill a buffer with external information +* @code{open-source} protocol:: Edit published contents +@end menu + +@node @code{store-link} protocol +@subsection @code{store-link} protocol +@cindex store-link protocol +@cindex protocol, store-link + +Using @code{store-link} handler, you can copy links, insertable through +@kbd{M-x org-insert-link} or yanking thereafter. More precisely, the command + +@example +emacsclient org-protocol://store-link?url=URL&title=TITLE +@end example + +@noindent +stores the following link: + +@example +[[URL][TITLE]] +@end example + +In addition, @samp{URL} is pushed on the kill-ring for yanking. You need to +encode @samp{URL} and @samp{TITLE} if they contain slashes, and probably +quote those for the shell. + +To use this feature from a browser, add a bookmark with an arbitrary name, +e.g., @samp{Org: store-link} and enter this as @emph{Location}: + +@example +javascript:location.href='org-protocol://store-link?url='+ + encodeURIComponent(location.href); +@end example + +@node @code{capture} protocol +@subsection @code{capture} protocol +@cindex capture protocol +@cindex protocol, capture + +@cindex capture, %:url placeholder +@cindex %:url template expansion in capture +@cindex capture, %:title placeholder +@cindex %:title template expansion in capture +Activating @code{capture} handler pops up a @samp{Capture} buffer and fills +the capture template associated to the @samp{X} key with them. The template +refers to the data through @code{%:url} and @code{%:title} placeholders. +Moreover, any selected text in the browser is appended to the body of the +entry. + +@example +emacsclient org-protocol://capture?template=X?url=URL?title=TITLE?body=BODY +@end example + +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 + +@vindex org-protocol-default-template-key +The result depends on the capture template used, which is set in the bookmark +itself, as in the example above, or in +@code{org-protocol-default-template-key}. + +@node @code{open-source} protocol +@subsection @code{open-source} protocol +@cindex open-source protocol +@cindex protocol, open-source + +The @code{open-source} handler is designed to help with editing local sources +when reading a document. To that effect, you can use a bookmark with the +following location: + +@example +javascript:location.href='org-protocol://open-source?&url='+ + encodeURIComponent(location.href) +@end example + +@cindex protocol, open-source, :base-url property +@cindex :base-url property in open-source protocol +@cindex protocol, open-source, :working-directory property +@cindex :working-directory property in open-source protocol +@cindex protocol, open-source, :online-suffix property +@cindex :online-suffix property in open-source protocol +@cindex protocol, open-source, :working-suffix property +@cindex :working-suffix property in open-source protocol +@vindex org-protocol-project-alist +The variable @code{org-protocol-project-alist} maps URLs to local file names, +by stripping URL parameters from the end and replacing the @code{:base-url} +with @code{:working-diretory} and @code{:online-suffix} with +@code{:working-suffix}. For example, assuming you own a local copy of +@url{http://orgmode.org/worg/} contents at @file{/home/user/worg}, 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 + +@noindent +If you are now browsing +@url{http://orgmode.org/worg/org-contrib/org-protocol.html} and find a typo +or have an idea about how to enhance the documentation, simply click the +bookmark and start editing. + +@cindex handle rewritten URL in open-source protocol +@cindex protocol, open-source rewritten URL +However, such mapping may not yield the desired results. Suppose you +maintain an online store located at @url{http://example.com/}. The local +sources reside in @file{/home/user/example/}. It is common practice to serve +all products in such a store through one file and rewrite URLs that do not +match an existing file on the server. That way, a request to +@url{http://example.com/print/posters.html} might be rewritten on the server +to something like +@url{http://example.com/shop/products.php/posters.html.php}. The +@code{open-source} handler probably cannot find a file named +@file{/home/user/example/print/posters.html.php} and fails. + +@cindex protocol, open-source, :rewrites property +@cindex :rewrites property in open-source protocol +Such an entry in @code{org-protocol-project-alist} may hold an additional +property @code{:rewrites}. This property is a list of cons cells, each of +which maps a regular expression to a path relative to the +@code{:working-directory}. + +Now map the URL to the path @file{/home/user/example/products.php} by adding +@code{:rewrites} rules like this: + +@lisp +(setq org-protocol-project-alist + '(("example.com" + :base-url "http://example.com/" + :working-directory "/home/user/example/" + :online-suffix ".php" + :working-suffix ".php" + :rewrites (("example.com/print/" . "products.php") + ("example.com/$" . "index.php"))))) +@end lisp + +@noindent +Since @samp{example.com/$} is used as a regular expression, it maps +@url{http://example.com/}, @url{https://example.com}, +@url{http://www.example.com/} and similar to +@file{/home/user/example/index.php}. + +The @code{:rewrites} rules are searched as a last resort if and only if no +existing file name is matched. + +@cindex protocol, open-source, set-up mapping +@cindex set-up mappings in open-source protocol +@findex org-protocol-create +@findex org-protocol-create-for-org +Two functions can help you filling @code{org-protocol-project-alist} with +valid contents: @code{org-protocol-create} and +@code{org-protocol-create-for-org}. The latter is of use if you're editing +an Org file that is part of a publishing project. @node Refile and copy @section Refile and copy -- 2.13.2 --=-=-=--