Re: org-protocol documentation

[Mario Martelli <tlmtr@schnuddelhuddel.de>]

[-- Attachment #1: Type: text/plain, Size: 411 bytes --]

Hi,

> I’ll 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’s still mainly copied from the old documentation. But distilled :)

It might be an idea to link to the old documentation at worg. 

I know that it is far away of an ideal documentation but better than what we have at the moment ;)

Any comments?


[-- Attachment #2: org.texi.diff --]
[-- Type: application/octet-stream, Size: 4813 bytes --]

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

[-- Attachment #3: Type: text/plain, Size: 34 bytes --]



Kind regards 
Mario
—