From fb9a7538b5a6965cf10da2371bb93fdebf51ddb7 Mon Sep 17 00:00:00 2001
From: Mario Martelli <cocoa@schnuddelhuddel.de>
Date: Sat, 1 Jul 2017 14:39:46 +0200
Subject: [PATCH 1/3] 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)

