From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mario Martelli Subject: Re: org-protocol documentation Date: Fri, 30 Jun 2017 14:05:10 +0200 Message-ID: <4D8D18D3-FBA7-4878-AB6A-76CE57635127@schnuddelhuddel.de> 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> Mime-Version: 1.0 (Mac OS X Mail 10.3 \(3273\)) Content-Type: multipart/mixed; boundary="Apple-Mail=_EA72A5EE-2A37-4D46-9B99-93C62E2FB52A" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:53871) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dQufn-0000dl-Db for emacs-orgmode@gnu.org; Fri, 30 Jun 2017 08:05:20 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dQufi-0000Av-Gm for emacs-orgmode@gnu.org; Fri, 30 Jun 2017 08:05:19 -0400 Received: from mail-wm0-x229.google.com ([2a00:1450:400c:c09::229]:38092) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1dQufi-00009f-4g for emacs-orgmode@gnu.org; Fri, 30 Jun 2017 08:05:14 -0400 Received: by mail-wm0-x229.google.com with SMTP id b184so43680219wme.1 for ; Fri, 30 Jun 2017 05:05:13 -0700 (PDT) In-Reply-To: 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: Nicolas Goaziou Cc: emacs-orgmode@gnu.org --Apple-Mail=_EA72A5EE-2A37-4D46-9B99-93C62E2FB52A Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=utf-8 Hi, > I=E2=80=99ll start with a fresh approach and try to bring up a short = manual in org.texi. I created a pretty short documentation of org-protocol. It=E2=80=99s = still mainly copied from the old documentation. But distilled :) It might be an idea to link to the old documentation at worg.=20 I know that it is far away of an ideal documentation but better than = what we have at the moment ;) Any comments? --Apple-Mail=_EA72A5EE-2A37-4D46-9B99-93C62E2FB52A Content-Disposition: attachment; filename=org.texi.diff Content-Type: application/octet-stream; x-unix-mode=0644; name="org.texi.diff" Content-Transfer-Encoding: 7bit diff --git a/doc/org.texi b/doc/org.texi index 879756e6f..9e491508f 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -7522,9 +7522,127 @@ 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}. Stores an +Org-link and pushes 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}. Maps URLs to local filenames. 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 configure handling of @code{open-source} the location of the website and the +location of the corresponding source must be configured. In addition the mapping +needs to be defined. + +To open files published on Worg locally, @code{org-protocol-project-alist} +should look like this. + +@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 + +There are two functions to help you fill @code{org-protocol-project-alist} with +valid contents. One possibility is @code{org-protocol-create} that guides you through +the process. If you're editing an Org-mode file that is part of a publishing +project in @code{org-publish-project-alist}, try + +@example +M-x org-protocol-create-for-org RET +@end example + +@node Using Org protocol +@subsection Using Org protocol + +To actually use org-protocol add 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 will be ignored, +e.g. @code{store-link} will use the URL and title only. + +@table @asis +@item @code{org-store-link} + stores an Org-link insertable through @code{M-x org-insert-link} and + pushes 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 this Org-link: + +@example +[[URL][TITLE]] +@end example + +In addition, @code{URL} will be pushed on the kill-ring for yanking. +You will have 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 + +will pop 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 @code{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 --Apple-Mail=_EA72A5EE-2A37-4D46-9B99-93C62E2FB52A Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=utf-8 Kind regards=20 Mario =E2=80=94=20 --Apple-Mail=_EA72A5EE-2A37-4D46-9B99-93C62E2FB52A--