Re: org-protocol documentation

[Mario Martelli <tlmtr@schnuddelhuddel.de>]

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

Hi,

> Also, I suggest using ox-texinfo from development version, if you can,
> as the Texinfo output should be superior.

Done that, eventually.

> Also, if the syntax is not quite right, no worries,
> we'll fix it.

That is probably necessary.

Please note, that the documentation assumes that the patches regarding “open-source” are applied.


[-- Attachment #2: 0001-org-protocol-documentation-is-moved-to-core-document.patch --]
[-- Type: application/octet-stream, Size: 30662 bytes --]

From cac507876c9d5acb7c61e62a425e1fdfa1676418 Mon Sep 17 00:00:00 2001
From: Mario Martelli <cocoa@schnuddelhuddel.de>
Date: Sun, 25 Jun 2017 12:00:51 +0200
Subject: [PATCH] org-protocol documentation is moved to core documentation

---
 doc/org.texi | 819 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 811 insertions(+), 8 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index 879756e6f..59725cbc6 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -7516,15 +7516,818 @@ For more information, including how to read atom feeds, see
 @section Protocols for external access
 @cindex protocols, for external access
 @cindex emacsserver
+@cindex org-protocol
 
-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
-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.
+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 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.  
+
+@node About org-protocolel
+@section About org-protocol.el
+@samp{org-protocol.el} is based on code and ideas from @uref{./org-annotation-helper.org, org-annotation-helper.el} and
+@samp{org-browser-url.el}.
+
+"@samp{org-protocol:/sub-protocol:/}" triggers actions associated with @samp{sub-protocol}
+through the custom variable @samp{org-protocol-protocol-alist}.
+
+It comes with four predefined handlers:
+@table @asis
+@item @samp{org-protocol-store-link}
+	triggered through the sub-protocol "@samp{store-link}". Stores an Org-link and
+pushes the URL to the @samp{kill-ring}.
+@item @samp{org-protocol-capture}
+	Fill a @samp{CAPTURE} buffer with information gathered somewhere else. This
+handler is triggered through the "@samp{capture}" sub-protocol and uses the
+function @samp{org-capture}.
+@item @samp{org-protocol-remember}
+	Fills a remember buffer with information gathered somewhere else. This
+handler is triggered through the "@samp{remember}" sub-protocol and still
+available for backward compatibility. This handler uses @samp{org-remember}. Use
+the current @samp{org-protocol-capture}.
+@item @samp{org-protocol-open-source}
+	"@samp{open-source}". Maps URLs to local filenames. Use this to open sources of
+already published contents in emacs for editing.
+@end table
+
+@samp{org-protocol} helps creating custom handlers @uref{../org-tutorials/org-protocol-custom-handler.org, (tutorial)} and so called
+@samp{org-protocol-projects}.
+
+
+@@<b>As of Org mode 9.0 a new org-protocol key=value syntax is supported@@<b>
+
+Org-protocol can now handle query-style parameters such as:
+
+@example
+org-protocol://store-link?url=http:%2F%2Flocalhost%2Findex.html&title=The%20title
+org-protocol://capture?template=x&title=Hello&body=World&url=http:%2F%2Fexample.com
+@end example
+
+Old-style links such as
+@samp{org-protocol://store-link:/http:%2F%2Flocalhost%2Findex.html/The%20title}
+continue to be supported.
+
+If you have defined your own handler functions for
+@code{org-protocol-protocol-alist}, change them to accept either a property
+list (for new-style links) or a string (for old-style links).  Use
+@code{org-protocol-parse-parameters} to convert old-style links into property
+lists.
+
+@@<b>As of Org mode release 7.01 @samp{org-protocol-remember} is now by @samp{org-protocol-capture}.@@</b>
+If not stated otherwise, you may simply replace each occurrence of
+@emph{capture} with @emph{remember} throughout this document, if you still want to use
+remember templates. Use @samp{M-x org-version} to find out about the version you're
+using.
+
+
+@anchor{orga3188cf}
+
+@node Installation
+@section Installation
+@itemize
+@item
+To load org-protocol.el add the following to your @samp{.emacs}:
+
+@example
+(server-start)
+(require 'org-protocol)
+@end example
+@end itemize
+
+@node Browser / system setup
+@subsection Browser / system setup
+@itemize
+@item
+@ref{Linux setup (Gnome)}
+@item
+@ref{Linux setup (KDE)}
+@item
+@ref{Windows setup}
+@item
+@ref{macOS setup}
+@end itemize
+
+@enumerate
+@item
+Linux setup (Gnome)
+
+For this to work, you'll need the Gnome-Libraries to be installed.
+
+@example
+gconftool-2 -s /desktop/gnome/url-handlers/org-protocol/command '/usr/local/bin/emacsclient %s' --type String
+gconftool-2 -s /desktop/gnome/url-handlers/org-protocol/enabled --type Boolean true
+@end example
+
+@item
+Linux setup (KDE)
+
+Add a file @samp{org.protocol} to @samp{~/.kde/share/kde4/services/}:
+
+@example
+# -*- conf -*-
+[Protocol]
+protocol=org-protocol
+exec=/usr/bin/emacsclient '%u'
+input=none
+output=none
+helper=true
+listing=
+reading=false
+writing=false
+makedir=false
+deleting=false
+Icon=emacs
+Description=A protocol for org-mode
+@end example
+
+@anchor{org3cb52a6}
+
+@item
+Windows setup
+
+Windows users may register the "@samp{org-protocol}" once for all by adjusting the
+following to their facts, save it as *.reg file and double-click it. This
+worked for me on Windows-XP Professional and the emasc23 from ourcomments.org
+(@uref{http://ourcomments.org/cgi-bin/emacsw32-dl-latest.pl}). I'm no Windows user
+though and enhancements are more than welcome on the org-mode mailinglist. The
+original file is from @uref{http://kb.mozillazine.org/Register_protocol}.
+
+@example
+REGEDIT4
+
+[HKEY_CLASSES_ROOT\org-protocol]
+@@="URL:Org Protocol"
+"URL Protocol"=""
+[HKEY_CLASSES_ROOT\org-protocol\shell]
+[HKEY_CLASSES_ROOT\org-protocol\shell\open]
+[HKEY_CLASSES_ROOT\org-protocol\shell\open\command]
+@@="\"C:\\Programme\\Emacs\\emacs\\bin\\emacsclientw.exe\" \"%1\""
+@end example
+
+@item
+macOS setup
+
+To bridge external calls to emacs you need to install a
+protocol-handler. @uref{https://github.com/aaronbieber/org-protocol-handler/commits/master/Commits%20%C2%B7%20aaronbieber/org-protocol-handler/, Aaron Bieber's org-protocol-handler} will work fine.
+
+If you are using a macOS native Emacs, it is recommended to use the
+emacsclient bundled with Emacs. Such as
+@samp{/Applications/Emacs.app/Contents/MacOS/bin/emacsclient} in the case
+of @uref{https://emacsformacosx.com, Emacs For Mac OS X}.
+
+After installing the protocol-handler you should then @ref{Verify the installation}. Once verified, you can begin using org-protocol.
+
+The @uref{https://bitbucket.org/mituharu/emacs-mac, Emacs Mac Port} comes with org-protocol. No installation of a
+protocol handler is needed with it.
+@end enumerate
+
+@node Applications
+@subsection Applications
+@anchor{org91000c6}
+
+@enumerate
+@item
+Firefox
+
+If you are using Firefox on macOS, see @ref{macOS setup}. 
+
+
+Please refer to @uref{http://kb.mozillazine.org/Register_protocol} and use
+"org-protocol" as protocol.
+
+@anchor{org83914ec}
+
+@item
+Acrobat Reader
+
+Adapted from @uref{http://article.gmane.org/gmane.emacs.orgmode/6810}
+
+You place a javascript file for each menu entry in
+@samp{~/.adobe/Acrobat/<VERSION>/JavaScripts} on unix-like systems or
+@samp{c:/Program Files/Adobe/Acrobat <VERSION>/Reader/Javascripts/} on
+Windows, or wherever your Adobe Reader Installation might look for
+javascript.
+
+The examples given here will place new menu entries in the "Tools"
+menu, after restarting Adobe Reader.
+
+@anchor{org6e6a1d8}
+
+@enumerate
+@item
+org-store-link.js
+
+@example
+// from http://article.gmane.org/gmane.emacs.orgmode/6810
+app.addMenuItem(@{cName:"org-store-link", cParent:"Tools",
+   cExec:"app.launchURL('org-protocol://store-link://' + encodeURIComponent(this.URL) + '/' + encodeURIComponent(this.info.Title));"@});
+@end example
+
+@anchor{orgdd4727b}
+
+@item
+org-capture.js
+
+@example
+// from http://article.gmane.org/gmane.emacs.orgmode/6810
+app.addMenuItem(@{cName:"org-capture", cParent:"Tools",
+   cExec:"app.launchURL('org-protocol://capture://' + encodeURIComponent(this.URL) + '/' + encodeURIComponent(this.info.Title) + '/');"@});
+@end example
+
+And this one, if you still use remember templates:
+
+@anchor{org3949e6c}
+
+@item
+org-remember.js
+
+@example
+// from http://article.gmane.org/gmane.emacs.orgmode/6810
+app.addMenuItem(@{cName:"org-remember", cParent:"Tools",
+   cExec:"app.launchURL('org-protocol://remember://' + encodeURIComponent(this.URL) + '/' + encodeURIComponent(this.info.Title) + '/');"@});
+@end example
+
+
+@anchor{org6ef67df}
+@end enumerate
+
+@item
+Opera
+
+If you are using Opera on macOS, see @ref{macOS setup}. 
+
+Opera setup is described here:
+@uref{http://www.opera.com/support/kb/view/535/}.
+
+To set up opera for use with org-protocol, follow these steps:
+
+@enumerate
+@item
+Choose "@emph{Tools}" -> "@emph{Prefences}" from the menu.
+@item
+Select the tab "@emph{Advanced}".
+@item
+Choose "@emph{Programs}" from the list on the left.
+@item
+Now click the button "@emph{Add}" on the very right.
+@item
+In the new dialog window, enter "@samp{org-protocol}" as "@emph{Protocol}", choose the
+radio button "@emph{Open with other application}" and enter the path to
+emacsclient.
+@end enumerate
+
+@anchor{orgb32e0fa}
+
+@item
+Safari
+
+To use org-protocol add a bookmark to your favorites bar. 
+Doing that enables you to trigger the bookmark by a keystroke. 
+
+Here is the URL to use as "@emph{Location}" for browser bookmarks. Just remove the
+line breaks, replace "@samp{sub-protocol}" with the real sub-protocol to use and 
+exchange the @samp{x} with the template shortcut of your choice.
+
+@example
+javascript:(function()@{window.location.href='org-protocol://sub-protocol?
+template=x&url='+encodeURIComponent(window.location.href)+
+'&title='+encodeURIComponent(document.title)+
+'&body='+encodeURIComponent(window.getSelection());@})();
+@end example
+@end enumerate
+
+@node Verify the installation
+@subsection Verify the installation
+After your protocol is registered with your browser/OS, these links here
+should work. Click on them and see if emacs reacts:
+
+@html
+<ul>
+ <li><a href="javascript:storeLink();">Org store-link</a></li>
+ <li><a href="javascript:capture();">Org capture (select some text if you like)</a></li>
+ <li><a href="javascript:remember();">Org remember (select some text please)</a></li>
+</ul>
+@end html
+
+
+@anchor{org6223309}
+@strong{*} Using org-protocol
+
+To actually use org-protocol add a bookmark to Firefox or Opera.
+
+Here is the URL to use as "@emph{Location}" for browser bookmarks. Just remove the
+line breaks and replace "@samp{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 @samp{org-protocol.el}. Some
+of the values will be ignored (e.g. @samp{store-link:/} will use the URL and title
+only).
+
+@anchor{org15dcbb6}
+
+@menu
+* Browser / system setup::
+* Applications::
+* Verify the installation::
+@end menu
+
+@node Links and bookmarks @samp{org-protocol-store-link}
+@section Links and bookmarks: @samp{org-protocol-store-link}
+@samp{org-store-link} stores an Org-link insertable through @samp{M-x org-insert-link} and
+pushes the URL found onto the @samp{kill-ring} for yanking (@samp{C-y}). The sub-protocol
+used is "@samp{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, @samp{URL} will be pushed on the @samp{kill-ring} for yanking ('@samp{C-y}'). You will
+have to encode @samp{URL} and/or @samp{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.
+"@emph{Org: store-link}") and enter this as "@samp{Location}":
+
+@example
+javascript:location.href='org-protocol://store-link?url='+encodeURIComponent(location.href)
+@end example
+
+@anchor{org00a295d}
+
+@node Note taking and citations @samp{org-protocol-capture}
+@section Note taking and citations: @samp{org-protocol-capture}
+This one is triggered through the sub-protocol "@samp{capture}" and consumes up to
+four data fields:
+
+@example
+emacsclient org-protocol:/capture?template=TEMPLATE?url=URL?title=TITLE?body=BODY
+@end example
+
+will pop up an @emph{@strong{Capture}} buffer and fill the template with the data
+submitted.
+
+To use this feature, add a bookmark with an arbitrary name (e.g.
+"@emph{Org: capture}") and enter this as "@samp{Location}":
+
+
+@example
+javascript:location.href='org-protocol://capture?
+           template=x&url='+encodeURIComponent(window.location.href)+
+           '&title='+encodeURIComponent(document.title)+
+           '&body='+encodeURIComponent(window.getSelection());@})();
+@end example
+
+The result depends on the template used. See @ref{org2eb70b8, , An example capture template}
+further down.
+
+Note, that this one, as opposed to the other two standard handlers, does not
+mix with more parameters to emacsclient. All parameters but the
+#'@samp{org-protocol://capture?...}' one will be discarded.
+
+@anchor{org7e3d71c}
+
+@node Which capture template is used?
+@subsection Which capture template is used?
+You don't need to setup a capture template to use @samp{org-protocol-capture},
+since Org-mode provides a default template for those cases.  Newer versions
+provide an interactive interface for choosing a template.  You may provide a
+template to be used by customizing the variable
+@samp{org-capture-default-template} @footnote{Before commit @samp{fc49c1ec96b2c789f573ae1ba936b930a8494402}, 3rd Sept. 2010,
+if a template with the key string "@samp{w}" was defined, this one was chosen by
+default.  This was done to make bookmarks used for @uref{./org-annotation-helper.el, org-annotation-helper} work
+without changing the template.}.
+
+The problem with this solution would be, that only one template can be used
+with the fuction. If this approach fit your needs you might omit
+the @samp{template} parameter in the @ref{org6223309, , example above}.
+
+
+@anchor{org2eb70b8}
+
+@enumerate
+@item
+An example capture template
+
+@lisp
+(setq org-capture-templates
+      (quote
+       (("w"
+	 "Default template"
+	 entry
+	 (file+headline "~/org/capture.org" "Notes")
+	 "* %^@{Title@}\n\n  Source: %u, %c\n\n  %i"
+	 :empty-lines 1)
+	;; ... more templates here ...
+	)))
+@end lisp
+
+@table @asis
+@item "@samp{w}"
+makes this one the default template used for
+"@samp{org-protocol://capture://}" URLs.
+@item @samp{entry}
+makes it a regular entry with a headline.
+@item @samp{file+headline}
+files the note in file "@samp{~/org/capture.org}" as child of
+the headline "@samp{Notes}"
+@item '@samp{%c}'
+will be replaced by an Org-link pointing to the location of the
+page you have been visiting when clicking on the link. The page
+title will be the link's description.
+@item '@samp{%i}'
+will be replaced by the selected text in your browser window if
+any.
+@end table
+
+In addition, you may use the following placeholders in your template:
+
+@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaa}
+@headitem Placeholders
+@tab Replacement
+@item @samp{%:link}
+@tab URL of the web-page
+@item @samp{%:description}
+@tab The title of the web-page
+@item @samp{%:initial}
+@tab Selected text.
+@end multitable
+
+You may read more about templates and their special escape characters in the
+@uref{http://orgmode.org/manual/Capture-templates.html#Capture-templates, Org-mode manual}.
+
+
+@anchor{org897a9c6}
+@end enumerate
+
+@node Org-protocol-remember
+@subsection Org-protocol-remember
+The @samp{org-protocol-remember} handler is now obsolete.  However, the handler is
+still available for backward compatibility.  To use this handler, closely
+follow the setup for the current @samp{org-protocol-capture} handler, and simply
+replace each occurrence of @emph{capture} with @emph{remember}.
+
+As remember templates look slightly different than capture templates, we
+provide an example here.
+
+@anchor{org8b49459}
+
+@enumerate
+@item
+An example remember template
+
+@lisp
+(setq org-remember-templates
+      '((?w "* %^@{Title@}\n\n  Source: %u, %c\n\n  %i" nil "Notes")))
+@end lisp
+
+@table @asis
+@item '@samp{?w}'
+makes this one the default template used for
+"@samp{org-protocol://remember://}" URLs.
+@item '@samp{%c}'
+will be replaced by an Org-link pointing to the location of the
+page you have been visiting when clicking on the link. The page
+title will be the link's description.
+@item '@samp{%i}'
+will be replaced by the selected text in your browser window if
+any.
+@end table
+
+In addition, you may use the following placeholders in your template:
+
+@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaa}
+@headitem Placeholders
+@tab Replacement
+@item @samp{%:link}
+@tab URL of the web-page
+@item @samp{%:description}
+@tab The title of the web-page
+@item @samp{%:initial}
+@tab Selected text.
+@end multitable
+
+You may read more about templates and their special escape characters in the
+@uref{http://orgmode.org/manual/Capture-templates.html#Capture-templates, Org-mode manual}.
+
+@anchor{org19b05e1}
+@end enumerate
+
+@menu
+* Which capture template is used?::
+* Org-protocol-remember::
+@end menu
+
+@node Edit published content @samp{org-protocol-open-source}
+@section Edit published content: @samp{org-protocol-open-source}
+This one was designed to help with opening sources for editing when browsing
+in the first place. @samp{org-protocol-open-source} uses the custom variable
+@samp{org-protocol-project-alist} to map URLs to (local) filenames.
+
+Let's take @uref{http://orgmode.org/worg/} as our example.
+
+Our intention is to click a bookmark (or link) to open the source of the
+published file we are reading in our favourite editor. The bookmark-URL above
+could be used again. But since @samp{org-protocol-open-source} regards the first
+field only, this here will do:
+
+@example
+javascript:location.href='org-protocol://open-source://'+encodeURIComponent(location.href)
+@end example
+
+To open files published on Worg locally, @samp{org-protocol-project-alist} should look
+like this (you may skip the second project):
+
+@lisp
+(setq org-protocol-project-alist
+      '(("Worg"
+	 :base-url "http://orgmode.org/worg/"
+	 :working-directory "/home/user/worg/"
+	 :online-suffix ".html"
+	 :working-suffix ".org")
+	("My local Org-notes"
+	 :base-url "http://localhost/org/"
+	 :working-directory "/home/user/org/"
+	 :online-suffix ".php"
+	 :working-suffix ".org")))
+@end lisp
+
+If you're now browsing @uref{http://orgmode.org/worg/org-contrib/org-protocol.html}
+and find a typo or have an idea how to enhance the documentation, simply click
+the bookmark and start editing.
+
+
+If you are using hugo to publish Org files. The configuration is
+slightly differnet as you have to name the whole filename of @samp{index.org}.
+If you clone the repo given in the example below you could you try out the following:
+@lisp
+("Hugo based MobileOrg Documentation Site"
+ :base-url "https://mobileorg.github.io/"
+ :working-directory "~/Documents/Github/MobileOrg/mobileorg.github.io/content/"
+ :online-suffix ".html"
+ :working-suffix "index.org")
+@end lisp
+
+For blogs and date-style URI please see @ref{orgc5ad545, , Handle rewritten URLs}
+
+
+There are two functions to help you fill @samp{org-protocol-project-alist} with
+valid contents. One possibility is @samp{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 @samp{org-publish-project-alist}, try
+
+@example
+M-x org-protocol-create-for-org RET
+@end example
+
+@anchor{orgc5ad545}
+
+@node Handle rewritten URLs
+@subsection Handle rewritten URLs
+In some cases, replacing @samp{:base-url} with @samp{:working-directory} and
+@samp{:online-suffix} with @samp{:working-suffix} will not yield the desired results.
+
+Suppose you maintain an online store located at @samp{http://example.com/}. The
+local sources reside in @samp{/home/user/example/}. While most of the URLs map
+directly to local file names by stripping URL parameters from the end and
+replacing the @samp{:base-url} with @samp{:working-diretory} and @samp{:online-suffix} with
+@samp{:working-suffix}, this might not work for rewritten URLs. It's 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 @samp{http://example.com/print/posters-A4.html} might be
+rewritten on the server to something like
+@samp{http://example.com/shop/products.php/posters-A4.html.php}, where
+@samp{/posters-A4-digital.html.php} is the so called path info. Note that the
+browser will not notice the rewrite.
+
+If you now click your @samp{org-protocol://open-source://} bookmark, the handler
+will probably not find a file named
+@samp{/home/user/example/print/posters-A4.html.php} and fail.
+
+Or, even more simple, assume you're browsing @samp{http://example.com/}. A file
+named @samp{/home/user/example/.php} is not likely to exist.
+
+Since Org-mode commit @samp{69b46e10aab3b2374ecbc1a963ba56e77102a9a4} from 15th
+Nov. 2009, such an entry in @samp{org-protocol-project-alist} may hold an
+additional property @samp{:rewrites}. This property is a list of cons cells, each
+of which maps a regular expression to a path relative to the
+@samp{:working-directory}.
+
+Now map the URL to the path @samp{/home/user/example/products.php} by adding the
+@samp{:rewrites} property 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
+
+Guess what the second @samp{:rewrites} element does. Since @samp{example.com/$} is used as
+a regular expression, it maps @samp{http://example.com/}, @samp{https://example.com},
+@samp{http://www.example.com/} and similar to @samp{/home/user/example/index.php}.
+
+If you are using date style URLs like @samp{https://cool-blog.com/2017/05/20/cool-post/},
+the following setup could be useful.
+
+@lisp
+(setq org-protocol-project-alist
+  '(("Icarus based blog"
+     :base-url "https://cool-blog.com/"
+     :working-directory "~/MyBlog/themes/hugo-icarus-theme/exampleSite/content/post/"
+     :online-suffix ".html"
+     :working-suffix ".org" ;; or ".md"
+     :rewrites (("\\(https://cool-blog.com/[0-9]+/[0-9]+/[0-9]+/\\)" . ".org"))
+     )))
+@end lisp
+
+The @samp{:rewrites} are searched as a last resort if and only if no existing file
+name is matched.
+
+@menu
+* Handle rewritten URLs::
+@end menu
+
+@node Other browsers
+@section Other browsers
+#@anchor{org7b66bec}
+
+@node Conkeror setup
+@subsection Conkeror setup
+Setting up org-protocol in @uref{http://conkeror.org/, Conkeror} (an emacs inspired Mozilla web
+browser) requires a slightly different method. You may simply add the
+following snippets of code to your .conkerorrc file.@footnote{Adapted from Tassilo Horn's blog, "Calling
+org-remember from inside conkeror," November 14, 2008.
+@uref{http://tsdh.wordpress.com/2008/11/14/calling-org-remember-from-inside-conkeror/}}
+Please note that the URIs used are of the old style before Org
+9.0. You might want to change them to the new style.
+
+For org-store-link, add the following to .conkerorrc:
+
+@example
+function org_store_link (url, title, window) @{
+    var cmd_str = 'emacsclient \"org-protocol://store-link://'+url+'/'+title+'\"';
+    if (window != null) @{
+	window.minibuffer.message('Issuing ' + cmd_str);
+    @}
+    shell_command_blind(cmd_str);
+@}
+
+interactive("org-store-link", "Stores [[url][title]] as org link and copies url to emacs kill ring",
+	    function (I) @{
+		org_store_link(encodeURIComponent(I.buffer.display_uri_string), encodeURIComponent(I.buffer.document.title), I.window);
+	    @});
+@end example
+
+For org-capture (or org-remember --- just exchange @emph{capture} with @emph{remember}), use
+the following:
+
+@example
+function org_capture (url, title, selection, window) @{
+    var cmd_str = 'emacsclient \"org-protocol://capture://'+url+'/'+title+'/'+selection+'\"';
+    if (window != null) @{
+	window.minibuffer.message('Issuing ' + cmd_str);
+    @}
+    shell_command_blind(cmd_str);
+@}
+
+interactive("org-capture", "Clip url, title, and selection to capture via org-protocol",
+	    function (I) @{
+		org_capture(encodeURIComponent(I.buffer.display_uri_string), encodeURIComponent(I.buffer.document.title), encodeURIComponent(I.buffer.top_frame.getSelection()), I.window);
+	    @});
+@end example
+
+Now, you should be able to invoke the commands from within conkeror
+with @samp{M-x org-store-link} and @samp{M-x org-capture} (or remember).
+
+Or, if you'd like your familiar emacs keybindings, you can add the
+following to your .conkerorrc:
+
+@example
+define_key(content_buffer_normal_keymap, "C-c r", "org-capture");
+define_key(content_buffer_normal_keymap, "C-c l", "org-store-link");
+@end example
+
+@node Uzbl
+@subsection Uzbl
+Uzbl is a minimalistic webkit browser for Unix/Linux.
+
+@itemize
+@item
+@uref{http://www.uzbl.org/}
+@end itemize
+
+You can pass encoded url data from uzbl to org-protocol by adding the
+following lines to @samp{.config/uzbl/config}.
+
+@example
+
+# Org-protocol
+
+@@cbind 	\\r = sh 'emacsclient "org-protocol://capture://\@@<encodeURIComponent(window.location.href)>\@@/\@@<encodeURIComponent(document.title)>\@@/\@@<document.getSelection()>\@@"'
+@@cbind 	\\l = sh 'emacsclient "org-protocol://capture://\@@<encodeURIComponent(window.location.href)>\@@/\@@<encodeURIComponent(document.title)>\@@"'
+
+@end example
+
+These bind org-protocol-capture and org-store-line to "" and "" respectively.
+
+@anchor{org3e33b3e}
+
+@node Keybindings for Firefox
+@subsection Keybindings for Firefox
+Please note that the URIs used are of the old style before Org
+9.0. You might want to change them to the new style.
+
+You can add key bindings for the @samp{org-protocol} commands using the keyconfig
+Firefox extension.
+
+First, install keyconfig from @uref{http://mozilla.dorando.at/keyconfig.xpi}.
+
+Open the keyconfig dialog by going to Tools and then Keyconfig.
+
+Click the 'Add a new Key' button. Enter "Org store link" as the name.
+Enter the following in the box with @emph{* CODE *} in it:
+
+@example
+var orgProtoString = 'org-protocol://store-link://'+
+  encodeURIComponent(gBrowser.currentURI.spec) + '/' +
+  encodeURIComponent(gBrowser.contentWindow.document.title) + '/' +
+  encodeURIComponent(gBrowser.contentWindow.getSelection());
+
+gBrowser.loadURI(orgProtoString);
+@end example
+
+Click OK. You will then need to bind a key by clicking in the box next to the
+'Apply' button and pressing whatever key combination you want. Click 'Apply' to
+store the keybinding.
+
+Repeat the steps, but call the next key "Org capture" and use the code below:
+
+@example
+var orgProtoString = 'org-protocol://capture://'+
+  encodeURIComponent(gBrowser.currentURI.spec) + '/' +
+  encodeURIComponent(gBrowser.contentWindow.document.title) + '/' +
+  encodeURIComponent(content.window.getSelection());
+
+gBrowser.loadURI(orgProtoString);
+@end example
+
+Click Close, then OK, and then restart Firefox. You should then be able to
+access the org-protocol functions with your chosen keys.
+
+@anchor{orgcd7acf4}
+
+@menu
+* Conkeror setup::
+* Uzbl::
+* Keybindings for Firefox::
+@end menu
+
+@node Screencast small introduction to org-protocolel
+@section Screencast: small introduction to org-protocol.el
+@html
+<object width="640" height="464"><param name="allowfullscreen"
+value="true" /><param name="allowscriptaccess" value="always" /><param
+name="movie"
+value="@uref{http://vimeo.com/moogaloop.swf?clip_id=5662410&amp;server=vimeo.com&amp;show_title=1&amp;show_byline=1&amp;show_portrait=1&amp;color=FF7700&amp;fullscreen=1}"
+/><embed
+src="@uref{http://vimeo.com/moogaloop.swf?clip_id=5662410&amp;server=vimeo.com&amp;show_title=1&amp;show_byline=1&amp;show_portrait=1&amp;color=FF7700&amp;fullscreen=1}"
+type="application/x-shockwave-flash" allowfullscreen="true"
+allowscriptaccess="always" width="640" height="464"></embed></object>
+@end html
+
+This screencast shows off some nice things you can do with Firefox,
+Emacs, Org-mode and org-protocol.el.
+
+It first shows how to create two bookmarklets, @samp{org-capture} and
+@samp{org-store-link}. These bookmarklets enable your Firefox to talk to
+emacsclient via a new protocol (@samp{org-protocol://}); emacsclient then
+parses the request and tells Emacs to capture or store stuff at the
+relevant places in your Org files.
+
+At the end of the screencast, we create two ubiquity commands from these
+bookmarklets.  Now in Firefox @samp{ALT-SPC org-capture RET} creates a note
+in my Org files.
 
 @node Refile and copy
 @section Refile and copy
-- 
2.11.0 (Apple Git-81)


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



Kind regards
Mario
—