From mboxrd@z Thu Jan 1 00:00:00 1970 From: Nicolas Goaziou Subject: Re: org-protocol documentation Date: Thu, 29 Jun 2017 14:42:40 +0200 Message-ID: <87lgobrmm7.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> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:34373) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dQYmX-0006FG-0U for emacs-orgmode@gnu.org; Thu, 29 Jun 2017 08:42:52 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dQYmT-0000m5-Dh for emacs-orgmode@gnu.org; Thu, 29 Jun 2017 08:42:49 -0400 Received: from relay4-d.mail.gandi.net ([2001:4b98:c:538::196]:45997) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1dQYmS-0000ip-UY for emacs-orgmode@gnu.org; Thu, 29 Jun 2017 08:42:45 -0400 In-Reply-To: (Mario Martelli's message of "Sun, 25 Jun 2017 12:15:20 +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 Hello, Mario Martelli writes: > Please note, that the documentation assumes that the patches regarding > =E2=80=9Copen-source=E2=80=9D are applied. Thank you. > +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. There should be a menu here. "ox-texinfo.el" should take care of it automatically. > +@node About org-protocolel > +@section About org-protocol.el This should be @subsection About ... But I think this can be merged with the paragraph above and the whole section "About ..." removed. > +@samp{org-protocol.el} is based on code and ideas from @uref{./org-annot= ation-helper.org, org-annotation-helper.el} and > +@samp{org-browser-url.el}. I think we can remove the above since the references are not particularly clear. > +"@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} @code{org-protocol-store-link} > + triggered through the sub-protocol "@samp{store-link}". Stores an Org-l= ink and > +pushes the URL to the @samp{kill-ring}. I think @samp{store-link} is sufficient, i.e., the double quote are supererogatory. Also ... the URL to the kill ring. since we do not refer explicitly here to the kill-ring variable but rather to the Emacs concept. Note that Org manual requires two spaces after each sentence. There are multiple occurrences to fix below. > +@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}. See above about the quotes. Also, @code{org-capture} @code{} is preferred over @samp{} for functions, variables, and syntactical elements in an Org buffer. > +@item @samp{org-protocol-remember} > + Fills a remember buffer with information gathered somewhere else. This Note that it was "Fill" instead of "Fills" in the previous item. I'd rather have the former. > +handler is triggered through the "@samp{remember}" sub-protocol and still > +available for backward compatibility. This handler uses @samp{org-rememb= er}. Use > +the current @samp{org-protocol-capture}. See above. > +@item @samp{org-protocol-open-source} > + "@samp{open-source}". Maps URLs to local filenames. Use this to open so= urces of > +already published contents in emacs for editing. > +@end table emacs -> Emacs. The first sentence needs to be expounded. > +@samp{org-protocol} helps creating custom handlers @uref{../org-tutorial= s/org-protocol-custom-handler.org, (tutorial)} and so called We can remove the @uref since it points to a relative path from the website. > +@samp{org-protocol-projects}. > + > + > +@@As of Org mode 9.0 a new org-protocol key=3Dvalue syntax is support= ed@@ This syntax was removed in Org 8.0. You can delete the whole line. > +Org-protocol can now handle query-style parameters such as: It should be Org protocol, like Org mode, not Org-protocol. > +@example > +org-protocol://store-link?url=3Dhttp:%2F%2Flocalhost%2Findex.html&title= =3DThe%20title > +org-protocol://capture?template=3Dx&title=3DHello&body=3DWorld&url=3Dhtt= p:%2F%2Fexample.com > +@end example > + > +Old-style links such as > +@samp{org-protocol://store-link:/http:%2F%2Flocalhost%2Findex.html/The%2= 0title} > +continue to be supported. I wonder if it is useful to document old-style links at all in the manual. Maybe as a footnote (i.e., @footnote{Old-style links...}) but no more. > +If you have defined your own handler functions for > +@code{org-protocol-protocol-alist}, change them to accept either a prope= rty > +list (for new-style links) or a string (for old-style links). Use This is very personal, but I don't like parenthesis outside Maths and Lisp. In a document, they just break the flow of reading, even though they are meant for side comments. Perhaps the following is better: 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 ones. But, again, should we document old-style links? > +@code{org-protocol-parse-parameters} to convert old-style links into pro= perty > +lists. See above. > +@@As of Org mode release 7.01 @samp{org-protocol-remember} is now by = @samp{org-protocol-capture}.@@ See above. > +If not stated otherwise, you may simply replace each occurrence of > +@emph{capture} with @emph{remember} throughout this document, if you sti= ll want to use > +remember templates. Use @samp{M-x org-version} to find out about the ver= sion you're > +using. You can remove references about Remember, which has been superseded by Capt= ure. > +@anchor{orga3188cf} You can remove this. "@node ..." are anchors. > +@node Installation > +@section Installation @subsection ... > +@itemize > +@item > +To load org-protocol.el add the following to your @samp{.emacs}: To load @file{org-protocol.el} ... to your Emacs init file: > +@example > +(server-start) > +(require 'org-protocol) > +@end example > +@end itemize > + > +@node Browser / system setup > +@subsection Browser / system setup @node System setup @subsection System setup @cindex System setup, for Org protocol @cindex System configuration for Org protocol @cindex whatnot... (Browser should be taken care of in Applications node). > +@itemize > +@item > +@ref{Linux setup (Gnome)} > +@item > +@ref{Linux setup (KDE)} > +@item > +@ref{Windows setup} > +@item > +@ref{macOS setup} > +@end itemize This looks like a menu. This can be removed, as "ox-texinfo.el" already takes care of it. The other option is to use @subsubheading instead of @subsubsection and have the four setup in the same page (the menu is then useless). Your call. > +@enumerate > +@item > +Linux setup (Gnome) @subsubsection Linux setup (Gnome) or @subsubheading Linux setup (Gnome) per above. > +For this to work, you'll need the Gnome-Libraries to be installed. Is this still necessary? > +@example > +gconftool-2 -s /desktop/gnome/url-handlers/org-protocol/command '/usr/lo= cal/bin/emacsclient %s' --type String > +gconftool-2 -s /desktop/gnome/url-handlers/org-protocol/enabled --type B= oolean true > +@end example Ditto. Could an Org protocol user double-check this? > +@item > +Linux setup (KDE) See above about @subsubsection and @subsubheading. > +Add a file @samp{org.protocol} to @samp{~/.kde/share/kde4/services/}: @file{org.protocol} to @file{~/...}: > +@example > +# -*- conf -*- > +[Protocol] > +protocol=3Dorg-protocol > +exec=3D/usr/bin/emacsclient '%u' > +input=3Dnone > +output=3Dnone > +helper=3Dtrue > +listing=3D > +reading=3Dfalse > +writing=3Dfalse > +makedir=3Dfalse > +deleting=3Dfalse > +Icon=3Demacs > +Description=3DA protocol for org-mode A protocol for Org mode > +@end example > + > +@anchor{org3cb52a6} You can remove this. > +@item > +Windows setup See above. > +Windows users may register the "@samp{org-protocol}" once for all by > adjusting the See above (quotes). > +following to their facts, save it as *.reg file and double-click it. > This @file{.reg} files > +worked for me on Windows-XP Professional and the emasc23 from ourcomment= s.org > +(@uref{http://ourcomments.org/cgi-bin/emacsw32-dl-latest.pl}). I'm no Wi= ndows user > +though and enhancements are more than welcome on the org-mode mailinglis= t. The > +original file is from > @uref{http://kb.mozillazine.org/Register_protocol}. Could someone double-check this? > +@example > +REGEDIT4 > + > +[HKEY_CLASSES_ROOT\org-protocol] > +@@=3D"URL:Org Protocol" > +"URL Protocol"=3D"" > +[HKEY_CLASSES_ROOT\org-protocol\shell] > +[HKEY_CLASSES_ROOT\org-protocol\shell\open] > +[HKEY_CLASSES_ROOT\org-protocol\shell\open\command] > +@@=3D"\"C:\\Programme\\Emacs\\emacs\\bin\\emacsclientw.exe\" \"%1\"" > +@end example > + > +@item > +macOS setup See above. > +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. -> protocol handler. The URL doesn't respond anymore. > +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. 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 Ditto. > +protocol handler is needed with it. > +@end enumerate > + > +@node Applications > +@subsection Applications > +@anchor{org91000c6} You can remove the @anchor{...}. > +@enumerate > +@item > +Firefox @subsubsection Firefox or @subsubheading Firefox > +If you are using Firefox on macOS, see @ref{macOS setup}.=20 This is redundant with the link below. > +Please refer to @uref{http://kb.mozillazine.org/Register_protocol} and u= se > +"org-protocol" as protocol. > + > +@anchor{org83914ec} See above. > + > +@item > +Acrobat Reader Ditto. > +Adapted from @uref{http://article.gmane.org/gmane.emacs.orgmode/6810} Not necessary, IMO. > +You place a javascript file for each menu entry in > +@samp{~/.adobe/Acrobat//JavaScripts} on unix-like systems or > +@samp{c:/Program Files/Adobe/Acrobat /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} See above. > +@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://' + encodeURICompon= ent(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://' + encodeURIComponen= t(this.URL) + '/' + encodeURIComponent(this.info.Title) + '/');"@}); > +@end example You can remove this part as Remember is no longer supported. > + > +@anchor{org6ef67df} > +@end enumerate > + > +@item > +Opera > + > +If you are using Opera on macOS, see @ref{macOS setup}.=20 > + > +Opera setup is described here: > +@uref{http://www.opera.com/support/kb/view/535/}. See above. > + > +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 @emph -> @code, everywhere. No quotes. "->" becomes "@arrow". > +@anchor{orgb32e0fa} > + > +@item > +Safari > + > +To use org-protocol add a bookmark to your favorites bar. Org protocol ... favorite > +Doing that enables you to trigger the bookmark by a keystroke.=20 > + > +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=20 > +exchange the @samp{x} with the template shortcut of your choice. > + > +@example > +javascript:(function()@{window.location.href=3D'org-protocol://sub-proto= col? > +template=3Dx&url=3D'+encodeURIComponent(window.location.href)+ > +'&title=3D'+encodeURIComponent(document.title)+ > +'&body=3D'+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 > + > +@end html > + > + > +@anchor{org6223309} > +@strong{*} Using org-protocol It should be @subsection 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=3D'org-protocol://sub-protocol? > + template=3Dx&url=3D'+encodeURIComponent(window.location.href)+ > + '&title=3D'+encodeURIComponent(document.title)+ > + '&body=3D'+encodeURIComponent(window.getSelection());@})(); > +@end example > + > +This URL may be used for all three standard handlers in @samp{org-protoc= ol.el}. Some > +of the values will be ignored (e.g. @samp{store-link:/} will use the URL= and title > +only). Documentation is at the present tense. "are ignored" .. "uses the URL and"... > + > +@anchor{org15dcbb6} > + > +@menu > +* Browser / system setup:: > +* Applications:: > +* Verify the installation:: > +@end menu This is a correct menu, but it looks out of place. Actually, this is a bug in "ox-texinfo.el" that I introduced recently and is now fixed. > +@node Links and bookmarks @samp{org-protocol-store-link} > +@section Links and bookmarks: @samp{org-protocol-store-link} Doesn't this belong to "Using Org protocol" section? > +@samp{org-store-link} stores an Org-link insertable through @samp{M-x or= g-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}": ... an Org link ... @kbd{M-x org-insert-link} ... @kbd(C-y) > +@example > +emacsclient org-protocol://store-link?url=3DURL&title=3DTITLE > +@end example > + > +will store this Org-link: -> store the following 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 In addition, URL is pushed on the kill ring for yanking (@kbd{C-y}). > +have to encode @samp{URL} and/or @samp{TITLE} if they contain slashes, a= nd probably quote > +those for the shell. Encode URL, or TITLE, if they contain slashes. Probable quote those for the shell, too. > +To use this feature, add a bookmark with an arbitrary name (e.g. > +"@emph{Org: store-link}") and enter this as "@samp{Location}": arbitrary name, e.g., @samp{Org: store-link}, and ... > +@example > +javascript:location.href=3D'org-protocol://store-link?url=3D'+encodeURIC= omponent(location.href) > +@end example > + > +@anchor{org00a295d} See above. > +@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 cons= umes up to > +four data fields: > + > +@example > +emacsclient org-protocol:/capture?template=3DTEMPLATE?url=3DURL?title=3D= TITLE?body=3DBODY > +@end example > + > +will pop up an @emph{@strong{Capture}} buffer and fill the template with= the data > +submitted. pops up a @samp{Capture} buffer and fills 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}": See above. > +@example > +javascript:location.href=3D'org-protocol://capture? > + template=3Dx&url=3D'+encodeURIComponent(window.location.href)+ > + '&title=3D'+encodeURIComponent(document.title)+ > + '&body=3D'+encodeURIComponent(window.getSelection());@})(); > +@end example > + > +The result depends on the template used. See @ref{org2eb70b8, , An examp= le 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-cap= ture}, > +since Org-mode provides a default template for those cases. Newer > versions -> Org mode > +provide an interactive interface for choosing a template. You may provi= de a > +template to be used by customizing the variable > +@samp{org-capture-default-template} When referring to a variable, you need to add a @vindex VARIABLE-NAME above. > @footnote{Before commit @samp{fc49c1ec96b2c789f573ae1ba936b930a8494402}, = 3rd Sept. 2010, > +if a template with the key string "@samp{w}" was defined, this one was c= hosen by > +default. This was done to make bookmarks used for @uref{./org-annotatio= n-helper.el, org-annotation-helper} work > +without changing the template.}. The footnote can be removed. > + > +The problem with this solution would be, that only one template can be u= sed > +with the fuction. If this approach fit your needs you might omit > +the @samp{template} parameter in the @ref{org6223309, , example above}. > + > + > +@anchor{org2eb70b8} Unlike to the previous ones, this anchor may be useful as it is actually referred to above. > +@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}" @file{~/org/capture.org} Is this true, BTW? I mean, is "~/org/capture.org" really hard-coded? the headline @samep{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}. This can be turned into a regular @ref{Template expansio}. > +@node Org-protocol-remember > +@subsection Org-protocol-remember You can remove the whole node. > +@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 brow= sing > +in the first place. @samp{org-protocol-open-source} uses the custom vari= able > +@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 t= he first > +field only, this here will do: > + > +@example > +javascript:location.href=3D'org-protocol://open-source://'+encodeURIComp= onent(location.href) > +@end example > + > +To open files published on Worg locally, @samp{org-protocol-project-alis= t} should look > +like this (you may skip the second project): Then what about removing the second project from the example? > +@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-pro= tocol.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 t= he following: > +@lisp > +("Hugo based MobileOrg Documentation Site" > + :base-url "https://mobileorg.github.io/" > + :working-directory "~/Documents/Github/MobileOrg/mobileorg.github.io/co= ntent/" > + :online-suffix ".html" > + :working-suffix "index.org") > +@end lisp > + > +For blogs and date-style URI please see @ref{orgc5ad545, , Handle > rewritten URLs} The @ref needs to be rewritten to target the @node, not the @anchor. > +There are two functions to help you fill @samp{org-protocol-project-alis= t} with > +valid contents. One possibility is @samp{org-protocol-create} that guide= s you through > +the process. If you're editing an Org-mode file that is part of a publis= hing > +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 des= ired 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 UR= Ls 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 com= mon > +practice to serve all products in such a store through one file and rewr= ite > +URLs that do not match an existing file on the server. > + > +That way, a request to @samp{http://example.com/print/posters-A4.html} m= ight 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 tha= t 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} fr= om 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 ce= lls, each > +of which maps a regular expression to a path relative to the > +@samp{:working-directory}. The archeology stuff can be removed. > +Now map the URL to the path @samp{/home/user/example/products.php} by ad= ding 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/i= ndex.php}. > + > +If you are using date style URLs like @samp{https://cool-blog.com/2017/0= 5/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/c= ontent/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 exi= sting file > +name is matched. > + > +@menu > +* Handle rewritten URLs:: > +@end menu > + > +@node Other browsers > +@section Other browsers I would remove this section. > +@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. We should do that in the documentation. > +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: @samp{Add a new Key} button. Enter @samp{Org store link} as the name. ... @samp{* CODE *} in it > +@example > +var orgProtoString =3D 'org-protocol://store-link://'+ > + encodeURIComponent(gBrowser.currentURI.spec) + '/' + > + encodeURIComponent(gBrowser.contentWindow.document.title) + '/' + > + encodeURIComponent(gBrowser.contentWindow.getSelection()); > + > +gBrowser.loadURI(orgProtoString); > +@end example > + > +Click OK. @samp{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 'Ap= ply' to > +store the keybinding. @samp{Apply} > + > +Repeat the steps, but call the next key "Org capture" and use the code b= elow: > + > +@example > +var orgProtoString =3D '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. Org protocol functions > + > +@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 This section can be removed. Besides the changes suggested above, we should put some thinking in the structure, which may be not adapter for a manual. In particular, it should be made shorter. Also, index entries are sorely missing for now. Regards, --=20 Nicolas Goaziou