* org-protocol documentation @ 2017-06-19 10:14 Mario Martelli 2017-06-19 10:41 ` Nicolas Goaziou 2017-06-19 12:26 ` Chunyang Xu 0 siblings, 2 replies; 42+ messages in thread From: Mario Martelli @ 2017-06-19 10:14 UTC (permalink / raw) To: emacs-orgmode [-- Attachment #1: Type: text/plain, Size: 993 bytes --] Hi, recently I’ve updated my macOS - Org mode setup. I had some pain setting up org-protocol properly which was mainly because the documentation (http://orgmode.org/worg/org-contrib/org-protocol.html <http://orgmode.org/worg/org-contrib/org-protocol.html>) is outdated. Especially for macOS. I thought about updating the documentation. But I’m unsure wether that is still the correct place. To me it seems that org-protocol is no longer in org-contrib but in org-mode. I could not verify that because I could not clone the repo (fatal: unable to connect to orgmode.org: orgmode.org[0: 104.239.132.130]: errno=Operation timed out ). - is the task of documenting org-protocol already scheduled? - if not, I would update the documentation in general and for macOS and would leave the linux and windows parts untouched (don’t know if they need to be updated), if that’s ok. Kind regards Mario — 🌍http://www.schnuddelhuddel.de <http://www.schnuddelhuddel.de/> [-- Attachment #2: Type: text/html, Size: 2413 bytes --] ^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: org-protocol documentation 2017-06-19 10:14 org-protocol documentation Mario Martelli @ 2017-06-19 10:41 ` Nicolas Goaziou 2017-06-19 12:37 ` Mario Martelli 2017-06-19 12:26 ` Chunyang Xu 1 sibling, 1 reply; 42+ messages in thread From: Nicolas Goaziou @ 2017-06-19 10:41 UTC (permalink / raw) To: Mario Martelli; +Cc: emacs-orgmode Hello, Mario Martelli <tlmtr@schnuddelhuddel.de> writes: > recently I’ve updated my macOS - Org mode setup. I had some pain > setting up org-protocol properly which was mainly because the > documentation (http://orgmode.org/worg/org-contrib/org-protocol.html > <http://orgmode.org/worg/org-contrib/org-protocol.html>) is outdated. > Especially for macOS. I thought about updating the documentation. But > I’m unsure wether that is still the correct place. To me it seems that > org-protocol is no longer in org-contrib but in org-mode. I could not > verify that because I could not clone the repo (fatal: unable to > connect to orgmode.org: orgmode.org[0: 104.239.132.130]: > errno=Operation timed out ). > > - is the task of documenting org-protocol already scheduled? I don't think so. Besides, org-protocol in indeed in core and should be documented in the manual. The latter merely points to the Worg page. > - if not, I would update the documentation in general and for macOS > and would leave the linux and windows parts untouched (don’t know if > they need to be updated), if that’s ok. This is fine as a first step IMO. Thank you. Regards, -- Nicolas Goaziou ^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: org-protocol documentation 2017-06-19 10:41 ` Nicolas Goaziou @ 2017-06-19 12:37 ` Mario Martelli 2017-06-19 13:41 ` Chunyang Xu 2017-06-21 17:29 ` Nicolas Goaziou 0 siblings, 2 replies; 42+ messages in thread From: Mario Martelli @ 2017-06-19 12:37 UTC (permalink / raw) To: Nicolas Goaziou, Chunyang Xu; +Cc: emacs-orgmode [-- Attachment #1: Type: text/plain, Size: 618 bytes --] > for what it's worth, the Emacs Mac Port supports org-protocol out of > box. It works without the Emacs server (emacsclient), e.g., Good to know. I’ve listed it in the documentation. Do you plan to provide ready built binaries? >> - if not, I would update the documentation in general and for macOS >> and would leave the linux and windows parts untouched (don’t know if >> they need to be updated), if that’s ok. > > This is fine as a first step IMO. Please find my attempt at: https://github.com/mgmart/org-mode <https://github.com/mgmart/org-mode> Kind regards Mario — [-- Attachment #2: Type: text/html, Size: 1403 bytes --] ^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: org-protocol documentation 2017-06-19 12:37 ` Mario Martelli @ 2017-06-19 13:41 ` Chunyang Xu 2017-06-21 17:29 ` Nicolas Goaziou 1 sibling, 0 replies; 42+ messages in thread From: Chunyang Xu @ 2017-06-19 13:41 UTC (permalink / raw) To: Mario Martelli, Nicolas Goaziou; +Cc: emacs-orgmode Mario Martelli <tlmtr@schnuddelhuddel.de> writes: >> for what it's worth, the Emacs Mac Port supports org-protocol out of >> box. It works without the Emacs server (emacsclient), e.g., > > Good to know. I’ve listed it in the documentation. > Do you plan to provide ready built binaries? The author of the Emacs Mac Port is Mitsuharu Yamamoto and I don't think there is any built binaries provided by him. I installed the built binaries via MacPorts (a package manager for Mac) with: $ sudo port install emacs-mac-app and I also heard that it is also available from Homebrew (another package manager). [...] ^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: org-protocol documentation 2017-06-19 12:37 ` Mario Martelli 2017-06-19 13:41 ` Chunyang Xu @ 2017-06-21 17:29 ` Nicolas Goaziou 2017-06-21 18:58 ` Mario Martelli 1 sibling, 1 reply; 42+ messages in thread From: Nicolas Goaziou @ 2017-06-21 17:29 UTC (permalink / raw) To: Mario Martelli; +Cc: emacs-orgmode, Chunyang Xu Hello, Mario Martelli <tlmtr@schnuddelhuddel.de> writes: > Please find my attempt at: https://github.com/mgmart/org-mode > <https://github.com/mgmart/org-mode> Thank you. However, AFAIU, this change is about orgmanual.org, which is an outdated copy of the official manual in contrib/. Could you modify "org.texi" in doc/ directory instead? Regards, -- Nicolas Goaziou 0x80A93738 ^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: org-protocol documentation 2017-06-21 17:29 ` Nicolas Goaziou @ 2017-06-21 18:58 ` Mario Martelli 2017-06-21 19:12 ` Nicolas Goaziou 0 siblings, 1 reply; 42+ messages in thread From: Mario Martelli @ 2017-06-21 18:58 UTC (permalink / raw) To: Nicolas Goaziou; +Cc: emacs-orgmode > However, AFAIU, this change is about orgmanual.org, which is an outdated > copy of the official manual in contrib/. Well, I thought I could begin with an easy task for my first contribution :) > Could you modify "org.texi" in doc/ directory instead? This will take a while, I assume. Although pandoc did a terrific job, there is some additional work to do. Kind regards Mario — ^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: org-protocol documentation 2017-06-21 18:58 ` Mario Martelli @ 2017-06-21 19:12 ` Nicolas Goaziou 2017-06-22 8:40 ` Mario Martelli 0 siblings, 1 reply; 42+ messages in thread From: Nicolas Goaziou @ 2017-06-21 19:12 UTC (permalink / raw) To: Mario Martelli; +Cc: emacs-orgmode Mario Martelli <tlmtr@schnuddelhuddel.de> writes: >> However, AFAIU, this change is about orgmanual.org, which is an outdated >> copy of the official manual in contrib/. > > Well, I thought I could begin with an easy task for my first contribution :) > >> Could you modify "org.texi" in doc/ directory instead? > > This will take a while, I assume. Although pandoc did a terrific job, there is some additional work to do. I'm not sure why is pandoc needed here. Org can export to Texinfo format, if needed. Also, if the syntax is not quite right, no worries, we'll fix it. Regards, ^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: org-protocol documentation 2017-06-21 19:12 ` Nicolas Goaziou @ 2017-06-22 8:40 ` Mario Martelli 2017-06-22 19:32 ` Mario Martelli 0 siblings, 1 reply; 42+ messages in thread From: Mario Martelli @ 2017-06-22 8:40 UTC (permalink / raw) To: Nicolas Goaziou; +Cc: emacs-orgmode I’m about to incorporate the new style URIs into the documentation. During my tests somehow the open-source protocol does not work for me. I assume a bug around Line 527 in org-protocol.el (let* ((base-url (plist-get (cdr prolist) :base-url)) —> (wsearch (regexp-quote base-url))) <— Could anyone confirm that? I’m unsure whether it might be a local misconfiguration on my side or not. I tried it with the worg example: emacsclient "org-protocol://open-source?url=http://orgmode.org/worg/org-tutorials/org-import-rtm.html” and escaped emacsclient 'org-protocol://open-source?url=https%3A%2F%2Forgmode.org%2Fworg%2Forg-tutorials%2Forg-import-rtm.html’ In both cases it fails silently. > I'm not sure why is pandoc needed here. Org can export to Texinfo > format, if needed. Thank you! Output is much nicer than with pandoc. I’ve disabled it years ago because not needed. So it went out of my sight ;) > Also, if the syntax is not quite right, no worries, > we'll fix it. That are great news! Kind regards Mario — ^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: org-protocol documentation 2017-06-22 8:40 ` Mario Martelli @ 2017-06-22 19:32 ` Mario Martelli 2017-06-22 20:03 ` Nicolas Goaziou 0 siblings, 1 reply; 42+ messages in thread From: Mario Martelli @ 2017-06-22 19:32 UTC (permalink / raw) To: Nicolas Goaziou; +Cc: emacs-orgmode [-- Attachment #1: Type: text/plain, Size: 1868 bytes --] I’ve incorporated the org-protocol documentation into org.texi. https://github.com/mgmart/org-mode/commit/31dd3cc13034c8501d8526e25086152a0e6538dd <https://github.com/mgmart/org-mode/commit/31dd3cc13034c8501d8526e25086152a0e6538dd> In a separate branch you could see the history of changes to the original org-protocol documentation from worg https://github.com/mgmart/org-mode/commits/documentation/org-protocol <https://github.com/mgmart/org-mode/commits/documentation/org-protocol> Still not sure wether the open-source subprotocol is broken or not. Kind regards Mario — > Am 22.06.2017 um 10:40 schrieb Mario Martelli <tlmtr@schnuddelhuddel.de>: > > I’m about to incorporate the new style URIs into the documentation. > During my tests somehow the open-source protocol does not work for me. > > I assume a bug around Line 527 in org-protocol.el > > (let* ((base-url (plist-get (cdr prolist) :base-url)) > —> (wsearch (regexp-quote base-url))) <— > > Could anyone confirm that? I’m unsure whether it might be a local misconfiguration on my side or not. > > I tried it with the worg example: > > emacsclient "org-protocol://open-source?url=http://orgmode.org/worg/org-tutorials/org-import-rtm.html” > > and escaped > > emacsclient 'org-protocol://open-source?url=https%3A%2F%2Forgmode.org%2Fworg%2Forg-tutorials%2Forg-import-rtm.html’ > > In both cases it fails silently. > >> I'm not sure why is pandoc needed here. Org can export to Texinfo >> format, if needed. > > Thank you! Output is much nicer than with pandoc. I’ve disabled it years ago because not needed. So it went out of my sight ;) > >> Also, if the syntax is not quite right, no worries, >> we'll fix it. > > That are great news! > > Kind regards > Mario > — > > > [-- Attachment #2: Type: text/html, Size: 3970 bytes --] ^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: org-protocol documentation 2017-06-22 19:32 ` Mario Martelli @ 2017-06-22 20:03 ` Nicolas Goaziou 2017-06-23 7:50 ` Mario Martelli 2017-06-25 10:15 ` org-protocol documentation Mario Martelli 0 siblings, 2 replies; 42+ messages in thread From: Nicolas Goaziou @ 2017-06-22 20:03 UTC (permalink / raw) To: Mario Martelli; +Cc: emacs-orgmode Hello, Mario Martelli <tlmtr@schnuddelhuddel.de> writes: > I’ve incorporated the org-protocol documentation into org.texi. > > https://github.com/mgmart/org-mode/commit/31dd3cc13034c8501d8526e25086152a0e6538dd <https://github.com/mgmart/org-mode/commit/31dd3cc13034c8501d8526e25086152a0e6538dd> So as to ease the reviewing process, could you send it on the ML with git format-patch sub-command? Also, I suggest using ox-texinfo from development version, if you can, as the Texinfo output should be superior. >> I assume a bug around Line 527 in org-protocol.el >> >> (let* ((base-url (plist-get (cdr prolist) :base-url)) >> —> (wsearch (regexp-quote base-url))) <— >> >> Could anyone confirm that? I’m unsure whether it might be a local misconfiguration on my side or not. Confirm what? Why do you think there is a bug in the line above? Regards, -- Nicolas Goaziou ^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: org-protocol documentation 2017-06-22 20:03 ` Nicolas Goaziou @ 2017-06-23 7:50 ` Mario Martelli 2017-06-23 16:46 ` Mario Martelli 2017-06-25 10:15 ` org-protocol documentation Mario Martelli 1 sibling, 1 reply; 42+ messages in thread From: Mario Martelli @ 2017-06-23 7:50 UTC (permalink / raw) To: Nicolas Goaziou; +Cc: emacs-orgmode [-- Attachment #1: Type: text/plain, Size: 1918 bytes --] Hi, > Am 22.06.2017 um 22:03 schrieb Nicolas Goaziou <mail@nicolasgoaziou.fr>: > > So as to ease the reviewing process, could you send it on the ML with > git format-patch sub-command? > sure. I would like to add an example using the subprotocol “open-source” for hugo. If that sounds ok for you. For that I would need “open-source” working, of course. > Also, I suggest using ox-texinfo from development version, if you can, > as the Texinfo output should be superior. have to set that up first. But I think I will need it anyway. ;) >>> I assume a bug around Line 527 in org-protocol.el >>> >>> (let* ((base-url (plist-get (cdr prolist) :base-url)) >>> —> (wsearch (regexp-quote base-url))) <— >>> >>> Could anyone confirm that? I’m unsure whether it might be a local misconfiguration on my side or not. > > Confirm what? That “open-source" is not working and is failing silently. > Why do you think there is a bug in the line above? Because I’m not experienced with elisp ;) I dug a little deeper and do now assume that there *might* be something wrong with “f” which is created in line 523 (f (plist-get (org-protocol-parse-parameters fname nil '(:url)) :url))) and which has “http:” as value if I’m using old style URIs and the whole URL (“http:/orgmode.org/worg/org-tutorials/org-import-rtm.html <http://orgmode.org/worg/org-tutorials/org-import-rtm.html>” in my example) if I’m using new style URIs. I assume “f” should be set to the base-url ("http:/orgmode.org/worg/ <http://orgmode.org/worg/>“ in my case). Given that, the test in line 529 (when (string-match wsearch f) fails all the time causing the function to fail silently. Thank you for being patient with me. At the moment I’m seeing parenthesises and backslashes everywhere :) Kind regards Mario — [-- Attachment #2: Type: text/html, Size: 3593 bytes --] ^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: org-protocol documentation 2017-06-23 7:50 ` Mario Martelli @ 2017-06-23 16:46 ` Mario Martelli 2017-06-25 6:49 ` [PATCH] org-protocol: fixes open-source and extends rewriting of URLs Mario Martelli 0 siblings, 1 reply; 42+ messages in thread From: Mario Martelli @ 2017-06-23 16:46 UTC (permalink / raw) To: Nicolas Goaziou; +Cc: emacs-orgmode Hi, > fails all the time causing the function to fail silently. I got "open-source" working by sanitising the URI before it is processed. diff --git a/lisp/org-protocol.el b/lisp/org-protocol.el index 825435674..7e986a9ed 100644 --- a/lisp/org-protocol.el +++ b/lisp/org-protocol.el @@ -520,7 +520,7 @@ The location for a browser's bookmark should look like this: ;; As we enter this function for a match on our protocol, the return value ;; defaults to nil. (let ((result nil) - (f (plist-get (org-protocol-parse-parameters fname nil '(:url)) :url))) + (f (org-protocol-sanitize-uri (plist-get (org-protocol-parse-parameters fname nil '(:url)) :url)))) (catch 'result (dolist (prolist org-protocol-project-alist) (let* ((base-url (plist-get (cdr prolist) :base-url)) Unfortunately it is still failing for old-style URIs. Fixing that would exceed my abilities. I could document that "open-source" does only support new-style URIs. Not sure if that is the best solution. Kind regards Mario — ^ permalink raw reply related [flat|nested] 42+ messages in thread
* [PATCH] org-protocol: fixes open-source and extends rewriting of URLs 2017-06-23 16:46 ` Mario Martelli @ 2017-06-25 6:49 ` Mario Martelli 2017-06-25 7:17 ` Nicolas Goaziou 0 siblings, 1 reply; 42+ messages in thread From: Mario Martelli @ 2017-06-25 6:49 UTC (permalink / raw) To: emacs-orgmode [-- Attachment #1: Type: text/plain, Size: 968 bytes --] Hi list, Doing the tests for the documentation I encountered some issues with org-protocol. [0001-url-is-sanitized-before-processing] I’ve got trouble to get sub-protocol “open-source” working in some cases. By sanitising the URL it works for me in all cases. [0002-tests-open-source-uri-against-uri-and-not-filename] This changes the test of the URI which was tested against the resulting filename. It’s now tested against the base-url. I’m still unsure with this because the code is there for more than seven years. Maybe I’m not seeing something obvious here. But all tests I made so far are succeeding with this change. [0003-org-protocol-open-source-can-open-hugo-sources-with-date-url] Enables “open-source” to open hugo sources from a blog which is using date URLs like: https://cool-blog.com/2017/05/20/cool-post/ <https://cool-blog.com/2017/05/20/cool-post/> WDYT of this? Kind regards Mario — [-- Attachment #2.1: Type: text/html, Size: 3099 bytes --] [-- Attachment #2.2: 0001-url-is-sanitized-before-processing.patch --] [-- Type: application/octet-stream, Size: 1014 bytes --] From 572a9fb03b62aa989752104898318096fa8809e4 Mon Sep 17 00:00:00 2001 From: Mario Martelli <cocoa@schnuddelhuddel.de> Date: Fri, 23 Jun 2017 18:32:49 +0200 Subject: [PATCH 1/3] url is sanitized before processing --- lisp/org-protocol.el | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lisp/org-protocol.el b/lisp/org-protocol.el index 825435674..7e986a9ed 100644 --- a/lisp/org-protocol.el +++ b/lisp/org-protocol.el @@ -520,7 +520,7 @@ The location for a browser's bookmark should look like this: ;; As we enter this function for a match on our protocol, the return value ;; defaults to nil. (let ((result nil) - (f (plist-get (org-protocol-parse-parameters fname nil '(:url)) :url))) + (f (org-protocol-sanitize-uri (plist-get (org-protocol-parse-parameters fname nil '(:url)) :url)))) (catch 'result (dolist (prolist org-protocol-project-alist) (let* ((base-url (plist-get (cdr prolist) :base-url)) -- 2.11.0 (Apple Git-81) [-- Attachment #2.3: Type: text/html, Size: 2167 bytes --] [-- Attachment #2.4: 0002-tests-open-source-uri-against-uri-and-not-filename.patch --] [-- Type: application/octet-stream, Size: 903 bytes --] From f7562e781de0331231d5e369280a2f710c240ca4 Mon Sep 17 00:00:00 2001 From: Mario Martelli <cocoa@schnuddelhuddel.de> Date: Sat, 24 Jun 2017 16:01:20 +0200 Subject: [PATCH 2/3] tests open-source uri against uri and not filename --- lisp/org-protocol.el | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lisp/org-protocol.el b/lisp/org-protocol.el index 7e986a9ed..6744fc0ac 100644 --- a/lisp/org-protocol.el +++ b/lisp/org-protocol.el @@ -554,7 +554,7 @@ The location for a browser's bookmark should look like this: ;; Try to match a rewritten URL and map it to ;; a real file. Compare redirects without ;; suffix. - (when (string-match-p (car rewrite) f2) + (when (string-match-p (car rewrite) f1) (throw 'result (concat wdir (cdr rewrite)))))))) ;; -- end of redirects -- -- 2.11.0 (Apple Git-81) [-- Attachment #2.5: Type: text/html, Size: 3067 bytes --] ^ permalink raw reply related [flat|nested] 42+ messages in thread
* Re: [PATCH] org-protocol: fixes open-source and extends rewriting of URLs 2017-06-25 6:49 ` [PATCH] org-protocol: fixes open-source and extends rewriting of URLs Mario Martelli @ 2017-06-25 7:17 ` Nicolas Goaziou 2017-06-25 8:21 ` Mario Martelli 0 siblings, 1 reply; 42+ messages in thread From: Nicolas Goaziou @ 2017-06-25 7:17 UTC (permalink / raw) To: Mario Martelli; +Cc: emacs-orgmode Hello, Mario Martelli <tlmtr@schnuddelhuddel.de> writes: > > Doing the tests for the documentation I encountered some issues with org-protocol. > > [0001-url-is-sanitized-before-processing] > I’ve got trouble to get sub-protocol “open-source” working in some cases. By sanitising the URL it works for me in all cases. > [...] > This changes the test of the URI which was tested against the resulting filename. It’s now tested against the base-url. > > I’m still unsure with this because the code is there for more than seven years. Maybe I’m not seeing something obvious here. But all tests I made so far are succeeding with this change. > [...] If all tests in "test-org-protocol.el" pass with your changes, I think it is fine to apply them. Another round of tests for the cases you solve would be nice, too. Regards, -- Nicolas Goaziou ^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: [PATCH] org-protocol: fixes open-source and extends rewriting of URLs 2017-06-25 7:17 ` Nicolas Goaziou @ 2017-06-25 8:21 ` Mario Martelli 2017-06-26 20:46 ` Nicolas Goaziou 0 siblings, 1 reply; 42+ messages in thread From: Mario Martelli @ 2017-06-25 8:21 UTC (permalink / raw) To: Nicolas Goaziou; +Cc: emacs-orgmode [-- Attachment #1: Type: text/plain, Size: 445 bytes --] > If all tests in "test-org-protocol.el" pass with your changes, I think > it is fine to apply them. Selector: "test-org-protocol/" Passed: 2 Failed: 0 Skipped: 0 Total: 2/2 > Another round of tests for the cases you solve > would be nice, too. I added the configuration part. That will be parsed during the tests I suppose. Selector: "test-org-protocol/" Passed: 3 Failed: 0 Skipped: 0 Total: 3/3 [-- Attachment #2: 0004-config-for-date-style-URL-is-added-to-org-protocol-t.patch --] [-- Type: application/octet-stream, Size: 1036 bytes --] From 4408f27e37f6578b3244a1ff7f4d7bd27720e1e6 Mon Sep 17 00:00:00 2001 From: Mario Martelli <cocoa@schnuddelhuddel.de> Date: Sun, 25 Jun 2017 10:14:40 +0200 Subject: [PATCH 4/4] config for date style URL is added to org-protocol tests --- testing/lisp/test-org-protocol.el | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/testing/lisp/test-org-protocol.el b/testing/lisp/test-org-protocol.el index 8f946864c..b11c72a68 100644 --- a/testing/lisp/test-org-protocol.el +++ b/testing/lisp/test-org-protocol.el @@ -137,6 +137,12 @@ :base-url "http://another.example.com/" :online-suffix ".js" :working-directory ,(file-name-directory temp-file-name2)) + (test3 + :base-url "https://blog-example.com/" + :working-directory ,(file-name-directory temp-file-name2)) + :online-suffix ".html" + :working-suffix ".md" + :rewrites (("\\(https://blog-example.com/[0-9]+/[0-9]+/[0-9]+/\\)" . ".md")) )) (test-cases (list -- 2.11.0 (Apple Git-81) [-- Attachment #3: Type: text/plain, Size: 538 bytes --] Adding full test-coverage of my changes is beyond my abilities at the moment, I must admit. But I will come back to it soon, I promise ;) Especially as there are succeeding tests for open-source using old-style URIs. (old-style URIs are not working for me with open-source) That will be the next task for me after completing the documentation. Speaking of the documentation: is it right, that there is no more support for “remember”? I would then remove that part from the documentation. Kind regards Mario — ^ permalink raw reply related [flat|nested] 42+ messages in thread
* Re: [PATCH] org-protocol: fixes open-source and extends rewriting of URLs 2017-06-25 8:21 ` Mario Martelli @ 2017-06-26 20:46 ` Nicolas Goaziou 2017-06-27 6:54 ` Mario Martelli 0 siblings, 1 reply; 42+ messages in thread From: Nicolas Goaziou @ 2017-06-26 20:46 UTC (permalink / raw) To: Mario Martelli; +Cc: emacs-orgmode Hello, Mario Martelli <tlmtr@schnuddelhuddel.de> writes: > Selector: "test-org-protocol/" > Passed: 2 > Failed: 0 > Skipped: 0 > Total: 2/2 Great! >> Another round of tests for the cases you solve >> would be nice, too. > > I added the configuration part. That will be parsed during the tests I suppose. > > > Selector: "test-org-protocol/" > Passed: 3 > Failed: 0 > Skipped: 0 > Total: 3/3 Even greater. > > From 4408f27e37f6578b3244a1ff7f4d7bd27720e1e6 Mon Sep 17 00:00:00 2001 > From: Mario Martelli <cocoa@schnuddelhuddel.de> > Date: Sun, 25 Jun 2017 10:14:40 +0200 > Subject: [PATCH 4/4] config for date style URL is added to org-protocol tests > OK. Could you wrap up the patches needed so far, with appropriate commit messages, so I can apply them? BTW, have you signed FSF papers? Thank you. Regards, -- Nicolas Goaziou ^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: [PATCH] org-protocol: fixes open-source and extends rewriting of URLs 2017-06-26 20:46 ` Nicolas Goaziou @ 2017-06-27 6:54 ` Mario Martelli 2017-06-28 9:32 ` Nicolas Goaziou 0 siblings, 1 reply; 42+ messages in thread From: Mario Martelli @ 2017-06-27 6:54 UTC (permalink / raw) To: Nicolas Goaziou; +Cc: emacs-orgmode [-- Attachment #1: Type: text/plain, Size: 254 bytes --] Hi, > OK. Could you wrap up the patches needed so far, with appropriate commit > messages, so I can apply them? Sorry for producing noise. Just read the contribution guidelines once again ;) Hope everything is now according to the guidelines. [-- Attachment #2: 0001-org-protocol.el-Fix-for-failing-open-source-subproto.patch --] [-- Type: application/octet-stream, Size: 1128 bytes --] From 0605063662ef6ae92abe75956dc2432f5028a041 Mon Sep 17 00:00:00 2001 From: Mario Martelli <cocoa@schnuddelhuddel.de> Date: Fri, 23 Jun 2017 18:32:49 +0200 Subject: [PATCH 1/4] org-protocol.el: Fix for failing open-source subprotocol * (org-protocol-open-source): make sure url is sanitised before processing TINYCHANGE --- lisp/org-protocol.el | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lisp/org-protocol.el b/lisp/org-protocol.el index 825435674..7e986a9ed 100644 --- a/lisp/org-protocol.el +++ b/lisp/org-protocol.el @@ -520,7 +520,7 @@ The location for a browser's bookmark should look like this: ;; As we enter this function for a match on our protocol, the return value ;; defaults to nil. (let ((result nil) - (f (plist-get (org-protocol-parse-parameters fname nil '(:url)) :url))) + (f (org-protocol-sanitize-uri (plist-get (org-protocol-parse-parameters fname nil '(:url)) :url)))) (catch 'result (dolist (prolist org-protocol-project-alist) (let* ((base-url (plist-get (cdr prolist) :base-url)) -- 2.11.0 (Apple Git-81) [-- Attachment #3: 0002-org-protocol.el-Fix-for-silently-failing-open-source.patch --] [-- Type: application/octet-stream, Size: 1014 bytes --] From 44d0ea97c452ed5f5cd0f358b75115a029a28487 Mon Sep 17 00:00:00 2001 From: Mario Martelli <cocoa@schnuddelhuddel.de> Date: Sat, 24 Jun 2017 16:01:20 +0200 Subject: [PATCH 2/4] org-protocol.el: Fix for silently failing open-source subprotocol * (org-protocol-open-source): tests URL against base-url and not the filename TINYCHANGE --- lisp/org-protocol.el | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lisp/org-protocol.el b/lisp/org-protocol.el index 7e986a9ed..6744fc0ac 100644 --- a/lisp/org-protocol.el +++ b/lisp/org-protocol.el @@ -554,7 +554,7 @@ The location for a browser's bookmark should look like this: ;; Try to match a rewritten URL and map it to ;; a real file. Compare redirects without ;; suffix. - (when (string-match-p (car rewrite) f2) + (when (string-match-p (car rewrite) f1) (throw 'result (concat wdir (cdr rewrite)))))))) ;; -- end of redirects -- -- 2.11.0 (Apple Git-81) [-- Attachment #4: 0003-org-protocol.el-sources-with-date-URL-are-supported.patch --] [-- Type: application/octet-stream, Size: 2180 bytes --] From dd9d41cfb6d48cc03a71c8604f3d913c35df4844 Mon Sep 17 00:00:00 2001 From: Mario Martelli <cocoa@schnuddelhuddel.de> Date: Sun, 25 Jun 2017 01:03:34 +0200 Subject: [PATCH 3/4] org-protocol.el sources with date URL are supported * (org-protocol-project-alist): date-URL is added as example * (org-protocol-open-source): first match is processed in rewrite TINYCHANGE --- lisp/org-protocol.el | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/lisp/org-protocol.el b/lisp/org-protocol.el index 6744fc0ac..5d4baae34 100644 --- a/lisp/org-protocol.el +++ b/lisp/org-protocol.el @@ -194,7 +194,14 @@ Example: :working-suffix \".org\" :base-url \"http://localhost/org/\" :working-directory \"/home/user/org/\" - :rewrites ((\"org/?$\" . \"index.php\"))))) + :rewrites ((\"org/?$\" . \"index.php\"))) + (\"Hugo based blog\" + :base-url \"https://themes.gohugo.io/theme/hugo-icarus/\" + :working-directory \"~/Documents/MyBlog/themes/hugo-icarus-theme/exampleSite/content/post/\" + :online-suffix \".html\" + :working-suffix \".md\" + :rewrites ((\"\\(https://themes.gohugo.io/theme/hugo-icarus/[0-9]+/[0-9]+/[0-9]+/\\)\" . \".md\"))))) + The last line tells `org-protocol-open-source' to open /home/user/org/index.php, if the URL cannot be mapped to an existing @@ -554,8 +561,13 @@ The location for a browser's bookmark should look like this: ;; Try to match a rewritten URL and map it to ;; a real file. Compare redirects without ;; suffix. - (when (string-match-p (car rewrite) f1) - (throw 'result (concat wdir (cdr rewrite)))))))) + (when (string-match (car rewrite) f1) + (setq replacement (cdr rewrite)) + (if (match-string 0 f1) + (setq replacement (concat + (directory-file-name (replace-match "" nil nil f1 1)) + replacement ))))) + (throw 'result (concat wdir replacement))))) ;; -- end of redirects -- (if (file-readable-p the-file) -- 2.11.0 (Apple Git-81) [-- Attachment #5: 0004-test-org-protocol.el-date-style-URL-support.patch --] [-- Type: application/octet-stream, Size: 1139 bytes --] From ec444303c239bc6d82bd8566e3fb283ea580070d Mon Sep 17 00:00:00 2001 From: Mario Martelli <cocoa@schnuddelhuddel.de> Date: Sun, 25 Jun 2017 10:14:40 +0200 Subject: [PATCH 4/4] test-org-protocol.el: date style URL support * (test-org-protocol/org-protocol-open-source): configuration displaying a date-style URL is added TINYCHANGE --- testing/lisp/test-org-protocol.el | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/testing/lisp/test-org-protocol.el b/testing/lisp/test-org-protocol.el index 8f946864c..b11c72a68 100644 --- a/testing/lisp/test-org-protocol.el +++ b/testing/lisp/test-org-protocol.el @@ -137,6 +137,12 @@ :base-url "http://another.example.com/" :online-suffix ".js" :working-directory ,(file-name-directory temp-file-name2)) + (test3 + :base-url "https://blog-example.com/" + :working-directory ,(file-name-directory temp-file-name2)) + :online-suffix ".html" + :working-suffix ".md" + :rewrites (("\\(https://blog-example.com/[0-9]+/[0-9]+/[0-9]+/\\)" . ".md")) )) (test-cases (list -- 2.11.0 (Apple Git-81) [-- Attachment #6: Type: text/plain, Size: 135 bytes --] > BTW, have you signed FSF papers? Applied for it just now. Have marked the changes as tiny. Kind regards Mario — ^ permalink raw reply related [flat|nested] 42+ messages in thread
* Re: [PATCH] org-protocol: fixes open-source and extends rewriting of URLs 2017-06-27 6:54 ` Mario Martelli @ 2017-06-28 9:32 ` Nicolas Goaziou 2017-06-28 14:44 ` Mario Martelli 0 siblings, 1 reply; 42+ messages in thread From: Nicolas Goaziou @ 2017-06-28 9:32 UTC (permalink / raw) To: Mario Martelli; +Cc: emacs-orgmode Hello, Mario Martelli <tlmtr@schnuddelhuddel.de> writes: > Sorry for producing noise. Just read the contribution guidelines once again ;) > Hope everything is now according to the guidelines. Thank you. Comments follow. > Subject: [PATCH 1/4] org-protocol.el: Fix for failing open-source subprotocol > > * (org-protocol-open-source): make sure url is > sanitised before processing Applied. > Subject: [PATCH 2/4] org-protocol.el: Fix for silently failing open-source > subprotocol > > * (org-protocol-open-source): tests URL against > base-url and not the filename Applied. > Subject: [PATCH 3/4] org-protocol.el sources with date URL are supported > > * (org-protocol-project-alist): date-URL is added as example > * (org-protocol-open-source): first match is processed in rewrite Not applied. See below. > + :rewrites ((\"org/?$\" . \"index.php\"))) > + (\"Hugo based blog\" > + :base-url \"https://themes.gohugo.io/theme/hugo-icarus/\" > + :working-directory \"~/Documents/MyBlog/themes/hugo-icarus-theme/exampleSite/content/post/\" > + :online-suffix \".html\" > + :working-suffix \".md\" > + :rewrites ((\"\\(https://themes.gohugo.io/theme/hugo-icarus/[0-9]+/[0-9]+/[0-9]+/\\)\" . \".md\"))))) Would it be possible to make the path involved smaller so that the example can fit in 80 columns? > The last line tells `org-protocol-open-source' to open > /home/user/org/index.php, if the URL cannot be mapped to an existing > @@ -554,8 +561,13 @@ The location for a browser's bookmark should look like this: > ;; Try to match a rewritten URL and map it to > ;; a real file. Compare redirects without > ;; suffix. > - (when (string-match-p (car rewrite) f1) > - (throw 'result (concat wdir (cdr rewrite)))))))) > + (when (string-match (car rewrite) f1) > + (setq replacement (cdr rewrite)) Here, `replacement' isn't lexically bound, so compiling "org-protocol.el" should return an error. `replacement' should be let-bound instead. > + (if (match-string 0 f1) AFAIU, (match-string 0 f1) is necessarily true, per the (string-match (car rewrite) f1) above, so the test can be removed. > + (setq replacement (concat > + (directory-file-name (replace-match "" nil nil f1 1)) > + replacement ))))) Spurious white space character before the parenthesis. > + (throw 'result (concat wdir replacement))))) Shouldn't the (throw ...) be within the (when (string-match ...)) as it was before? I may be wrong. I didn't check the high level logic of the patch since I don't know "org-protocol.el". > Applied for it just now. Have marked the changes as tiny. Great. Let me know when the process is complete. Regards, -- Nicolas Goaziou 0x80A93738 ^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: [PATCH] org-protocol: fixes open-source and extends rewriting of URLs 2017-06-28 9:32 ` Nicolas Goaziou @ 2017-06-28 14:44 ` Mario Martelli 2017-06-28 15:49 ` Nicolas Goaziou 0 siblings, 1 reply; 42+ messages in thread From: Mario Martelli @ 2017-06-28 14:44 UTC (permalink / raw) To: Nicolas Goaziou; +Cc: emacs-orgmode [-- Attachment #1: Type: text/plain, Size: 499 bytes --] Hi, > Would it be possible to make the path involved smaller so that the > example can fit in 80 columns? The idea was to give an example which is available online and could get cloned easily onto the local machine. Changed it to a simple example. > Here, `replacement' isn't lexically bound, so compiling > "org-protocol.el" should return an error. `replacement' should be > let-bound instead. ... Thank you for your patience, Nicolas 😇 Please find attached a fresh attempt. [-- Attachment #2: 0001-org-protocol.el-sources-with-date-URL-are-supported.patch --] [-- Type: application/octet-stream, Size: 2848 bytes --] From d6744d7fee6a78a20759c7a61dbc9a118cc21c78 Mon Sep 17 00:00:00 2001 From: Mario Martelli <cocoa@schnuddelhuddel.de> Date: Wed, 28 Jun 2017 16:36:45 +0200 Subject: [PATCH] org-protocol.el sources with date URL are supported * (org-protocol-project-alist): date-URL is added as example * (org-protocol-open-source): first match is processed in rewrite * (test-org-protocol/org-protocol-open-source): configuration displaying a date-style URL is added TINYCHANGE --- lisp/org-protocol.el | 16 +++++++++++++--- testing/lisp/test-org-protocol.el | 6 ++++++ 2 files changed, 19 insertions(+), 3 deletions(-) diff --git a/lisp/org-protocol.el b/lisp/org-protocol.el index cd4b216aa..099e7e25d 100644 --- a/lisp/org-protocol.el +++ b/lisp/org-protocol.el @@ -194,7 +194,14 @@ Example: :working-suffix \".org\" :base-url \"http://localhost/org/\" :working-directory \"/home/user/org/\" - :rewrites ((\"org/?$\" . \"index.php\"))))) + :rewrites ((\"org/?$\" . \"index.php\"))) + (\"Hugo based blog\" + :base-url \"https://www.site.com/\" + :working-directory \"~/site/content/post/\" + :online-suffix \".html\" + :working-suffix \".md\" + :rewrites ((\"\\(https://site.com/[0-9]+/[0-9]+/[0-9]+/\\)\" . \".md\"))))) + The last line tells `org-protocol-open-source' to open /home/user/org/index.php, if the URL cannot be mapped to an existing @@ -556,8 +563,11 @@ The location for a browser's bookmark should look like this: ;; Try to match a rewritten URL and map it to ;; a real file. Compare redirects without ;; suffix. - (when (string-match-p (car rewrite) f1) - (throw 'result (concat wdir (cdr rewrite)))))))) + (when (string-match (car rewrite) f1) + (let ((replacement (concat + (directory-file-name (replace-match "" nil nil f1 1)) + (cdr rewrite)))) + (throw 'result (concat wdir replacement)))))))) ;; -- end of redirects -- (if (file-readable-p the-file) diff --git a/testing/lisp/test-org-protocol.el b/testing/lisp/test-org-protocol.el index 8f946864c..b11c72a68 100644 --- a/testing/lisp/test-org-protocol.el +++ b/testing/lisp/test-org-protocol.el @@ -137,6 +137,12 @@ :base-url "http://another.example.com/" :online-suffix ".js" :working-directory ,(file-name-directory temp-file-name2)) + (test3 + :base-url "https://blog-example.com/" + :working-directory ,(file-name-directory temp-file-name2)) + :online-suffix ".html" + :working-suffix ".md" + :rewrites (("\\(https://blog-example.com/[0-9]+/[0-9]+/[0-9]+/\\)" . ".md")) )) (test-cases (list -- 2.11.0 (Apple Git-81) [-- Attachment #3: Type: text/plain, Size: 135 bytes --] > Great. Let me know when the process is complete. Will do. Sent out the signed copy today. Kind regards Mario — ^ permalink raw reply related [flat|nested] 42+ messages in thread
* Re: [PATCH] org-protocol: fixes open-source and extends rewriting of URLs 2017-06-28 14:44 ` Mario Martelli @ 2017-06-28 15:49 ` Nicolas Goaziou 2017-06-29 8:28 ` Mario Martelli 0 siblings, 1 reply; 42+ messages in thread From: Nicolas Goaziou @ 2017-06-28 15:49 UTC (permalink / raw) To: Mario Martelli; +Cc: emacs-orgmode Mario Martelli <tlmtr@schnuddelhuddel.de> writes: > Hi, > >> Would it be possible to make the path involved smaller so that the >> example can fit in 80 columns? > > The idea was to give an example which is available online and could get cloned easily onto the local machine. > Changed it to a simple example. > >> Here, `replacement' isn't lexically bound, so compiling >> "org-protocol.el" should return an error. `replacement' should be >> let-bound instead. > ... > Thank you for your patience, Nicolas 😇 > Please find attached a fresh attempt. Applied. Thank you. I fixed some whitespace issue and typo in the test. Could you provide an ORG-NEWS entry about it? Regards, ^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: [PATCH] org-protocol: fixes open-source and extends rewriting of URLs 2017-06-28 15:49 ` Nicolas Goaziou @ 2017-06-29 8:28 ` Mario Martelli 2017-06-29 12:47 ` Nicolas Goaziou 0 siblings, 1 reply; 42+ messages in thread From: Mario Martelli @ 2017-06-29 8:28 UTC (permalink / raw) To: Nicolas Goaziou; +Cc: emacs-orgmode [-- Attachment #1: Type: text/plain, Size: 199 bytes --] > Applied. Thank you. Thanks to you :) > I fixed some whitespace issue and typo in the test. :blush: Thanks again. > Could you provide an ORG-NEWS entry about it? Sure. Kind regards Mario [-- Attachment #2.1: Type: text/html, Size: 2613 bytes --] [-- Attachment #2.2: 0001-ORG_NEWS-org-protocol-s-date-style-URL-support-is-me.patch --] [-- Type: application/octet-stream, Size: 834 bytes --] From ec6d2a617497e54bf80daa50b41d4a215ac7b060 Mon Sep 17 00:00:00 2001 From: Mario Martelli <cocoa@schnuddelhuddel.de> Date: Thu, 29 Jun 2017 10:16:30 +0200 Subject: [PATCH] ORG_NEWS: org-protocol's date style URL support is mentioned --- etc/ORG-NEWS | 3 +++ 1 file changed, 3 insertions(+) diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS index 89751cefd..27743c642 100644 --- a/etc/ORG-NEWS +++ b/etc/ORG-NEWS @@ -392,6 +392,9 @@ suitable as a default value. *** New entities : ~\dollar~ and ~\USD~ *** ~org-parse-time-string~ accepts a new optional argument =ZONE= specifies the current time zone. +*** Support for date style URLs in =org-protocol://open-source= + URLs like =https://cool-blog.com/2017/05/20/cool-post/= are + covered by rewrite rules. * Version 9.0 -- 2.11.0 (Apple Git-81) [-- Attachment #2.3: Type: text/html, Size: 335 bytes --] ^ permalink raw reply related [flat|nested] 42+ messages in thread
* Re: [PATCH] org-protocol: fixes open-source and extends rewriting of URLs 2017-06-29 8:28 ` Mario Martelli @ 2017-06-29 12:47 ` Nicolas Goaziou 0 siblings, 0 replies; 42+ messages in thread From: Nicolas Goaziou @ 2017-06-29 12:47 UTC (permalink / raw) To: Mario Martelli; +Cc: emacs-orgmode Hello, Mario Martelli <tlmtr@schnuddelhuddel.de> writes: > Could you provide an ORG-NEWS entry about it? > > Sure. Applied. Thank you. Regards, -- Nicolas Goaziou ^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: org-protocol documentation 2017-06-22 20:03 ` Nicolas Goaziou 2017-06-23 7:50 ` Mario Martelli @ 2017-06-25 10:15 ` Mario Martelli 2017-06-29 12:42 ` Nicolas Goaziou 1 sibling, 1 reply; 42+ messages in thread From: Mario Martelli @ 2017-06-25 10:15 UTC (permalink / raw) To: Nicolas Goaziou; +Cc: emacs-orgmode [-- 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&server=vimeo.com&show_title=1&show_byline=1&show_portrait=1&color=FF7700&fullscreen=1}" +/><embed +src="@uref{http://vimeo.com/moogaloop.swf?clip_id=5662410&server=vimeo.com&show_title=1&show_byline=1&show_portrait=1&color=FF7700&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 — ^ permalink raw reply related [flat|nested] 42+ messages in thread
* Re: org-protocol documentation 2017-06-25 10:15 ` org-protocol documentation Mario Martelli @ 2017-06-29 12:42 ` Nicolas Goaziou 2017-06-29 18:30 ` Mario Martelli 2017-06-30 4:42 ` Mario Martelli 0 siblings, 2 replies; 42+ messages in thread From: Nicolas Goaziou @ 2017-06-29 12:42 UTC (permalink / raw) To: Mario Martelli; +Cc: emacs-orgmode Hello, Mario Martelli <tlmtr@schnuddelhuddel.de> writes: > Please note, that the documentation assumes that the patches regarding > “open-source” 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-annotation-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-link 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-remember}. 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 sources 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-tutorials/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}. > + > + > +@@<b>As of Org mode 9.0 a new org-protocol key=value syntax is supported@@<b> 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=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. 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 property > +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 property > +lists. See above. > +@@<b>As of Org mode release 7.01 @samp{org-protocol-remember} is now by @samp{org-protocol-capture}.@@</b> See above. > +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. You can remove references about Remember, which has been superseded by Capture. > +@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/local/bin/emacsclient %s' --type String > +gconftool-2 -s /desktop/gnome/url-handlers/org-protocol/enabled --type Boolean 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=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 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 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}. Could someone double-check this? > +@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 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}. This is redundant with the link below. > +Please refer to @uref{http://kb.mozillazine.org/Register_protocol} and use > +"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/<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} 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://' + 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 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}. > + > +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. > + > +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 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='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). 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 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}": ... an Org link ... @kbd{M-x org-insert-link} ... @kbd(C-y) > +@example > +emacsclient org-protocol://store-link?url=URL&title=TITLE > +@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, and 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='org-protocol://store-link?url='+encodeURIComponent(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 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. 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='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 -> Org mode > +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} 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 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 footnote can be removed. > + > +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} 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 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): 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-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} 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-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}. The archeology stuff can be removed. > +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 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 = '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 'Apply' to > +store the keybinding. @samp{Apply} > + > +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. 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, -- Nicolas Goaziou ^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: org-protocol documentation 2017-06-29 12:42 ` Nicolas Goaziou @ 2017-06-29 18:30 ` Mario Martelli 2017-06-30 12:05 ` Mario Martelli 2017-06-30 4:42 ` Mario Martelli 1 sibling, 1 reply; 42+ messages in thread From: Mario Martelli @ 2017-06-29 18:30 UTC (permalink / raw) To: Nicolas Goaziou; +Cc: emacs-orgmode Hi, > 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. My attempt was to copy the existing documentation from worg to the core documentation and to leave as much as possible unchanged. I also think that a much shorter documentation of Org protocol would be the better approach. > Also, index entries are sorely missing for now. It seems that writing the documentation in Org and exporting it to texi might not be the best approach. I’ll start with a fresh approach and try to bring up a short manual in org.texi. BTW: Papers are signed Kind regards Mario — ^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: org-protocol documentation 2017-06-29 18:30 ` Mario Martelli @ 2017-06-30 12:05 ` Mario Martelli 2017-07-01 10:34 ` Nicolas Goaziou 0 siblings, 1 reply; 42+ messages in thread From: Mario Martelli @ 2017-06-30 12:05 UTC (permalink / raw) To: Nicolas Goaziou; +Cc: emacs-orgmode [-- 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 — ^ permalink raw reply related [flat|nested] 42+ messages in thread
* Re: org-protocol documentation 2017-06-30 12:05 ` Mario Martelli @ 2017-07-01 10:34 ` Nicolas Goaziou 2017-07-01 13:13 ` Mario Martelli 0 siblings, 1 reply; 42+ messages in thread From: Nicolas Goaziou @ 2017-07-01 10:34 UTC (permalink / raw) To: Mario Martelli; +Cc: emacs-orgmode Hello, Mario Martelli <tlmtr@schnuddelhuddel.de> writes: > I created a pretty short documentation of org-protocol. It’s still > mainly copied from the old documentation. But distilled :) Thank you. > It might be an idea to link to the old documentation at worg. I'd rather not do that. Ideally, Org internal documentation should be self-contained. > Any comments? Always ;) > +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. triggered -> Triggered Stores -> Store pushes -> push Org-link -> Org link -> link (since we can assume in an Org manual, links default to Org link). > +@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}. This should be consistent with the previous wording, e.g.: Triggered through the sub-protocol @code{capture}. Fill a @samp{Capture} buffer with ... calling @code{org-capture} function. > +@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. See above. > +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. I suggest to rewrite this using a more direct style. > +To open files published on Worg locally, @code{org-protocol-project-alist} > +should look like this. 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 > + > +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 Missing space after dot. Are there really two functions? You only document one. Also, more direct: Two functions can help you filling... @code{org-protocol-create} guides... > +the process. If you're editing an Org-mode file that is part of a publishing Missing space. Also, Org-mode file -> Org file > +project in @code{org-publish-project-alist}, try > + > +@example > +M-x org-protocol-create-for-org RET > +@end example @example @kbd{M-x org-protocol-create-for org @key{RET}} @end example But is the example really necessary? > +@node Using Org protocol > +@subsection Using Org protocol > + > +To actually use org-protocol add a bookmark to your browser. org-protocol -> Org protocol Is Org protocol really limited to bookmarks in browsers? > +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. will be ignored -> are ignored will use -> uses > +@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}: stores an Org-link -> Store a link @kbd{M-x org-insert-link} pushes -> push > +@example > +emacsclient org-protocol://store-link?url=URL&title=TITLE > +@end example > + > +will store this Org-link: will store this Org-link > stores the following link > +@example > +[[URL][TITLE]] > +@end example > + > +In addition, @code{URL} will be pushed on the kill-ring for yanking. In addition, @samp{URL} is pushed... > +You will have to encode @code{URL} and @code{TITLE} if You will have to -> You need to (or something equivalent) @samp{URL} ... @samp{TITLE} > +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. @noindent pops up a ... > +To use this feature, add a bookmark with an arbitrary name, e.g. > +@samp{Org: capture} and enter this as @code{Location}: @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 Genuine question: is this documentation actually complete enough to use the feature? Regards, -- Nicolas Goaziou ^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: org-protocol documentation 2017-07-01 10:34 ` Nicolas Goaziou @ 2017-07-01 13:13 ` Mario Martelli 2017-07-01 16:42 ` Nicolas Goaziou 2017-07-23 22:39 ` Adam Porter 0 siblings, 2 replies; 42+ messages in thread From: Mario Martelli @ 2017-07-01 13:13 UTC (permalink / raw) To: Nicolas Goaziou; +Cc: emacs-orgmode [-- Attachment #1: Type: text/plain, Size: 635 bytes --] Hi, >> Any comments? > > Always ;) :-) > Are there really two functions? You only > document one. Hope it’s clearer now. > Genuine question: is this documentation actually complete enough to use > the feature? I suppose so, if one knows how to configure URL handlers on their OS. Of course there are some things missing from the documentation. But it’s more than we have at the moment :) I’m not happy with that there is so much information - although outdated - in the old Worg documentation which might be hidden to the reader. Anyway, I hope I’ve correctly incorporated all your comments. [-- Attachment #2: 0001-org.texi-Basic-Org-protocol-documentation-is-added.patch --] [-- Type: application/octet-stream, Size: 5413 bytes --] 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/2] 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) [-- Attachment #3: 0002-org.texi-Fixes-missing-space-after-dot.patch --] [-- Type: application/octet-stream, Size: 1475 bytes --] From 1bd6e3b3390609254f1fae79a53957ba3f51868c Mon Sep 17 00:00:00 2001 From: Mario Martelli <cocoa@schnuddelhuddel.de> Date: Sat, 1 Jul 2017 14:44:45 +0200 Subject: [PATCH 2/2] org.texi: Fixes missing space after dot. * org.texi Minor change regarding missing space --- doc/org.texi | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 76f491a78..93c9d4167 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -829,7 +829,7 @@ different formats such as HTML, @LaTeX{}, Open Document, and Markdown. New export backends can be derived from existing ones, or defined from scratch. Org files can include source code blocks, which makes Org uniquely suited for -authoring technical documents with code examples. Org source code blocks are +authoring technical documents with code examples. Org source code blocks are fully functional; they can be evaluated in place and their results can be captured in the file. This makes it possible to create a single file reproducible research compendium. @@ -8200,7 +8200,7 @@ you can use the following instead: @end example That will give you three days' warning: on the anniversary date itself and the -two days prior. The argument is optional: if omitted, it defaults to 7. +two days prior. The argument is optional: if omitted, it defaults to 7. @subsubheading Appointment reminders @cindex @file{appt.el} -- 2.11.0 (Apple Git-81) [-- Attachment #4: Type: text/plain, Size: 33 bytes --] Kind regards Mario — ^ permalink raw reply related [flat|nested] 42+ messages in thread
* Re: org-protocol documentation 2017-07-01 13:13 ` Mario Martelli @ 2017-07-01 16:42 ` Nicolas Goaziou 2017-07-01 16:44 ` Nicolas Goaziou 2017-07-01 19:24 ` Mario Martelli 2017-07-23 22:39 ` Adam Porter 1 sibling, 2 replies; 42+ messages in thread From: Nicolas Goaziou @ 2017-07-01 16:42 UTC (permalink / raw) To: Mario Martelli; +Cc: emacs-orgmode Mario Martelli <tlmtr@schnuddelhuddel.de> writes: >> Genuine question: is this documentation actually complete enough to use >> the feature? > > I suppose so, if one knows how to configure URL handlers on their OS. > Of course there are some things missing from the documentation. But > it’s more than we have at the moment :) That is true. > I’m not happy with that there is so much information - although > outdated - in the old Worg documentation which might be hidden to the > reader. Note that > +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. You probably missed my remark about this part. I think each sub-protocol should be introduced in a similar way. > +@end table > + > +@node Setting up Org protocol > +@subsection Setting up Org protocol This is the trick part. We need to feed the index. For example, we could add the following right below the @subsection line @cindex Org protocol, set-up @cindex Installing Org protocol Feel free to adapt. > +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}. Just above this paragraph, you need @vindex 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. Just above this paragraph, we need @findex org-protocol-project-alist @findex org-protocol-create Though, I'm puzzled, `org-publish-project-alist' is a variable, not a function. > +@node Using Org protocol > +@subsection Using Org protocol See above about the @cindex: @cindex Org protocol, usage ... > +Org protocol is triggered by @file{emacsclient}. If you want to use Org ^^^ Gotcha > +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. ^^^ Ditto > +@table @asis > +@item @code{org-store-link} > + store a link, insertable through @kbd{M-x org-insert-link} and -> Store > Subject: [PATCH 2/2] org.texi: Fixes missing space after dot. > > * org.texi Minor change regarding missing space Good catch. Applied. Thank you. Regards, ^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: org-protocol documentation 2017-07-01 16:42 ` Nicolas Goaziou @ 2017-07-01 16:44 ` Nicolas Goaziou 2017-07-01 19:24 ` Mario Martelli 1 sibling, 0 replies; 42+ messages in thread From: Nicolas Goaziou @ 2017-07-01 16:44 UTC (permalink / raw) To: Mario Martelli; +Cc: emacs-orgmode Nicolas Goaziou <mail@nicolasgoaziou.fr> writes: > Mario Martelli <tlmtr@schnuddelhuddel.de> writes: >> outdated - in the old Worg documentation which might be hidden to the >> reader. > > Note that Ahem. Note that most of this documentation is available through other means, AFAIU. ^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: org-protocol documentation 2017-07-01 16:42 ` Nicolas Goaziou 2017-07-01 16:44 ` Nicolas Goaziou @ 2017-07-01 19:24 ` Mario Martelli 2017-07-03 17:21 ` Nick Dokos 2017-07-06 17:54 ` Nicolas Goaziou 1 sibling, 2 replies; 42+ messages in thread From: Mario Martelli @ 2017-07-01 19:24 UTC (permalink / raw) To: Nicolas Goaziou; +Cc: emacs-orgmode [-- Attachment #1: Type: text/plain, Size: 1852 bytes --] >> I’m not happy with that there is so much information - although >> outdated - in the old Worg documentation which might be hidden to the >> reader. > > Note that most of this documentation is available through other > means, AFAIU. Ok, what I meant are the readers who are not able to use Google ;) > You probably missed my remark about this part. I think each sub-protocol > should be introduced in a similar way. I misinterpreted the meaning. I do not really like to begin each sentence with the same phrase. But I got it eventually that it's a manual ;) >> +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. > > Though, I'm puzzled, `org-publish-project-alist' is a variable, not a function. Don’t know what happened there. Repaired. >> +Org protocol is triggered by @file{emacsclient}. If you want to use Org > ^^^ > Gotcha > >> +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. > ^^^ > Ditto This one I do not understand. I use now @file{emacsclient} consistently if that was the meaning of the comment. > This is the trick part. We need to feed the index. > @cindex Installing Org protocol > @vindex org-protocol-project-alist > @findex org-protocol-project-alist I started this whole thing because I wanted to learn elisp. But learning texinfo en-passant is nice :) [-- Attachment #2: 0001-org.texi-Basic-Org-protocol-documentation-is-added.patch --] [-- Type: application/octet-stream, Size: 5413 bytes --] 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) [-- Attachment #3: 0002-org.texi-Fixes-missing-space-after-dot.patch --] [-- Type: application/octet-stream, Size: 1475 bytes --] From 1bd6e3b3390609254f1fae79a53957ba3f51868c Mon Sep 17 00:00:00 2001 From: Mario Martelli <cocoa@schnuddelhuddel.de> Date: Sat, 1 Jul 2017 14:44:45 +0200 Subject: [PATCH 2/3] org.texi: Fixes missing space after dot. * org.texi Minor change regarding missing space --- doc/org.texi | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 76f491a78..93c9d4167 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -829,7 +829,7 @@ different formats such as HTML, @LaTeX{}, Open Document, and Markdown. New export backends can be derived from existing ones, or defined from scratch. Org files can include source code blocks, which makes Org uniquely suited for -authoring technical documents with code examples. Org source code blocks are +authoring technical documents with code examples. Org source code blocks are fully functional; they can be evaluated in place and their results can be captured in the file. This makes it possible to create a single file reproducible research compendium. @@ -8200,7 +8200,7 @@ you can use the following instead: @end example That will give you three days' warning: on the anniversary date itself and the -two days prior. The argument is optional: if omitted, it defaults to 7. +two days prior. The argument is optional: if omitted, it defaults to 7. @subsubheading Appointment reminders @cindex @file{appt.el} -- 2.11.0 (Apple Git-81) [-- Attachment #4: 0003-org.texi-Minor-changes-and-added-index-to-org-protoc.patch --] [-- Type: application/octet-stream, Size: 3725 bytes --] From 9468832e402e46c1a574cdeeadaa6b7ae275198c Mon Sep 17 00:00:00 2001 From: Mario Martelli <cocoa@schnuddelhuddel.de> Date: Sat, 1 Jul 2017 21:13:54 +0200 Subject: [PATCH 3/3] org.texi: Minor changes and added index to org-protocol * doc/org.texi Minor changes and added index to org-protocol --- doc/org.texi | 30 +++++++++++++++++++++--------- 1 file changed, 21 insertions(+), 9 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 93c9d4167..7add60d5c 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -7528,26 +7528,31 @@ 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. + 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}. + Triggered through the sub-protocol @code{capture}. Fill a buffer + with information gathered somewhere else. @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. + Triggered through the sub-protoicol @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 +@cindex Org protocol, set-up +@cindex Installing 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. +@vindex org-protocol-project-alist To map a website with @code{open-source} to local files you have to set up the mapping in @code{org-protocol-project-alist}. +@vindex 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 @@ -7560,15 +7565,22 @@ For example, in order to open files published on Worg locally, you can set :working-suffix ".org"))) @end lisp +@vindex org-protocol-project-alist +@findex org-protocol-create +@findex org-protocol-create-for-org 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 +contents: @code{org-protocol-create} and @code{org-protocol-create-for-org}. 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 +@cindex Org protocol, using +@cindex 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 +protocol, there are many possibilities to do so. You can invoke @file{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 @@ -7592,7 +7604,7 @@ e.g. @code{store-link} uses the URL and title only. The sub-protocol used is @code{store-link}: @example -emacsclient org-protocol://store-link?url=URL&title=TITLE +@file{emacsclient} org-protocol://store-link?url=URL&title=TITLE @end example will store the following link: -- 2.11.0 (Apple Git-81) [-- Attachment #5: Type: text/plain, Size: 89 bytes --] (second patch attached out of consistency reasons) Kind regards Mario — ^ permalink raw reply related [flat|nested] 42+ messages in thread
* Re: org-protocol documentation 2017-07-01 19:24 ` Mario Martelli @ 2017-07-03 17:21 ` Nick Dokos 2017-07-03 18:09 ` Mario Martelli 2017-07-06 17:54 ` Nicolas Goaziou 1 sibling, 1 reply; 42+ messages in thread From: Nick Dokos @ 2017-07-03 17:21 UTC (permalink / raw) To: emacs-orgmode Mario Martelli <tlmtr@schnuddelhuddel.de> writes: >>> +Org protocol is triggered by @file{emacsclient}. If you want to use Org >> ^^^ >> Gotcha >> >>> +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. >> ^^^ >> Ditto > > This one I do not understand. > I use now @file{emacsclient} consistently if that was the meaning of the comment. > No, it's a much more mundane style issue: you need to have two spaces after a period. -- Nick ^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: org-protocol documentation 2017-07-03 17:21 ` Nick Dokos @ 2017-07-03 18:09 ` Mario Martelli 0 siblings, 0 replies; 42+ messages in thread From: Mario Martelli @ 2017-07-03 18:09 UTC (permalink / raw) To: Nick Dokos; +Cc: emacs-orgmode [-- Attachment #1: Type: text/plain, Size: 291 bytes --] >> This one I do not understand. >> I use now @file{emacsclient} consistently if that was the meaning of the comment. >> > > No, it's a much more mundane style issue: you need to have two spaces after a period. :smile: I hope I got that changed too ;) rgrds Mario — [-- Attachment #2: smime.p7s --] [-- Type: application/pkcs7-signature, Size: 3690 bytes --] ^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: org-protocol documentation 2017-07-01 19:24 ` Mario Martelli 2017-07-03 17:21 ` Nick Dokos @ 2017-07-06 17:54 ` Nicolas Goaziou 2017-07-23 16:18 ` Mario Martelli 1 sibling, 1 reply; 42+ messages in thread From: Nicolas Goaziou @ 2017-07-06 17:54 UTC (permalink / raw) To: Mario Martelli; +Cc: emacs-orgmode [-- Attachment #1: Type: text/plain, Size: 488 bytes --] Hello, Mario Martelli <tlmtr@schnuddelhuddel.de> writes: > I started this whole thing because I wanted to learn elisp. But > learning texinfo en-passant is nice :) Thank you for your patch. I re-worded the documentation based on your work. I also added more index entries. Since I'm not using Org Protocol, I may fall wide of the mark. Anyway, it's now your turn to do some reviewing ;) WDYT? Regards, -- Nicolas Goaziou 0x80A93738 [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #2: document Org Protocol --] [-- Type: text/x-diff, Size: 9541 bytes --] From 6caca7a57427efb67d5d1fdaf25232a46c96b2ba Mon Sep 17 00:00:00 2001 From: Nicolas Goaziou <mail@nicolasgoaziou.fr> Date: Tue, 4 Jul 2017 14:48:41 +0200 Subject: [PATCH] org.texi: Document Org Protocol * doc/org.texi (Protocols): Document feature. --- doc/org.texi | 208 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 200 insertions(+), 8 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 176e7c259..e73c9c06a 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -499,6 +499,12 @@ Capture templates * Template expansion:: Filling in information about time and context * Templates in contexts:: Only show a template in a specific context +Protocols for external access + +* @code{store-link} protocol:: Store a link, push URL to kill-ring +* @code{capture} protocol:: Fill a buffer with external information +* @code{open-source} protocol:: Edit published contents + Archiving * Moving subtrees:: Moving a tree to an archive file @@ -7515,16 +7521,202 @@ For more information, including how to read atom feeds, see @node Protocols @section Protocols for external access @cindex protocols, for external access -@cindex emacsserver -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 +Org protocol in a mean to trigger custom actions in Emacs from external +applications. Any application that supports calling external programs with +an URL as argument may be used with this functionality. 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. +Org and create a note from it using capture (@pxref{Capture}). You can also +create a bookmark that tells Emacs to open the local source file of a remote +website you are browsing. + +@cindex Org protocol, set-up +@cindex Installing Org protocol +In order to use Org protocol from an application, you need to register +@samp{org-protocol://} as a valid scheme-handler. External calls are passed +to Emacs through the @code{emacsclient} command, so you also need to ensure +an Emacs server is running. More precisely, when the application calls + +@example +emacsclient org-protocol://PROTOCOL?key1=var1&key2=var2 +@end example + +@noindent +Emacs calls the handler associated to @samp{PROTOCOL} with argument +@samp{(:key1 var1 :key2 var2)}. + +@cindex protocol, new protocol +@cindex defining new protocols +Org protocol comes with three predefined protocols, detailed in the following +sections. Configure @code{org-protocol-protocol-alist} to define your own. + +@menu +* @code{store-link} protocol:: Store a link, push URL to kill-ring +* @code{capture} protocol:: Fill a buffer with external information +* @code{open-source} protocol:: Edit published contents +@end menu + +@node @code{store-link} protocol +@subsection @code{store-link} protocol +@cindex store-link protocol +@cindex protocol, store-link + +Using @code{store-link} handler, you can copy links, insertable through +@kbd{M-x org-insert-link} or yanking thereafter. More precisely, the command + +@example +emacsclient org-protocol://store-link?url=URL&title=TITLE +@end example + +@noindent +stores the following link: + +@example +[[URL][TITLE]] +@end example + +In addition, @samp{URL} is pushed on the kill-ring for yanking. You need to +encode @samp{URL} and @samp{TITLE} if they contain slashes, and probably +quote those for the shell. + +To use this feature from a browser, add a bookmark with an arbitrary name, +e.g., @samp{Org: store-link} and enter this as @emph{Location}: + +@example +javascript:location.href='org-protocol://store-link?url='+ + encodeURIComponent(location.href); +@end example + +@node @code{capture} protocol +@subsection @code{capture} protocol +@cindex capture protocol +@cindex protocol, capture + +@cindex capture, %:url placeholder +@cindex %:url template expansion in capture +@cindex capture, %:title placeholder +@cindex %:title template expansion in capture +Activating @code{capture} handler pops up a @samp{Capture} buffer and fills +the capture template associated to the @samp{X} key with them. The template +refers to the data through @code{%:url} and @code{%:title} placeholders. +Moreover, any selected text in the browser is appended to the body of the +entry. + +@example +emacsclient org-protocol://capture?template=X?url=URL?title=TITLE?body=BODY +@end example + +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 + +@vindex org-protocol-default-template-key +The result depends on the capture template used, which is set in the bookmark +itself, as in the example above, or in +@code{org-protocol-default-template-key}. + +@node @code{open-source} protocol +@subsection @code{open-source} protocol +@cindex open-source protocol +@cindex protocol, open-source + +The @code{open-source} handler is designed to help with editing local sources +when reading a document. To that effect, you can use a bookmark with the +following location: + +@example +javascript:location.href='org-protocol://open-source?&url='+ + encodeURIComponent(location.href) +@end example + +@cindex protocol, open-source, :base-url property +@cindex :base-url property in open-source protocol +@cindex protocol, open-source, :working-directory property +@cindex :working-directory property in open-source protocol +@cindex protocol, open-source, :online-suffix property +@cindex :online-suffix property in open-source protocol +@cindex protocol, open-source, :working-suffix property +@cindex :working-suffix property in open-source protocol +@vindex org-protocol-project-alist +The variable @code{org-protocol-project-alist} maps URLs to local file names, +by stripping URL parameters from the end and replacing the @code{:base-url} +with @code{:working-diretory} and @code{:online-suffix} with +@code{:working-suffix}. For example, assuming you own a local copy of +@url{http://orgmode.org/worg/} contents at @file{/home/user/worg}, 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 + +@noindent +If you are now browsing +@url{http://orgmode.org/worg/org-contrib/org-protocol.html} and find a typo +or have an idea about how to enhance the documentation, simply click the +bookmark and start editing. + +@cindex handle rewritten URL in open-source protocol +@cindex protocol, open-source rewritten URL +However, such mapping may not yield the desired results. Suppose you +maintain an online store located at @url{http://example.com/}. The local +sources reside in @file{/home/user/example/}. It is 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 +@url{http://example.com/print/posters.html} might be rewritten on the server +to something like +@url{http://example.com/shop/products.php/posters.html.php}. The +@code{open-source} handler probably cannot find a file named +@file{/home/user/example/print/posters.html.php} and fails. + +@cindex protocol, open-source, :rewrites property +@cindex :rewrites property in open-source protocol +Such an entry in @code{org-protocol-project-alist} may hold an additional +property @code{:rewrites}. This property is a list of cons cells, each of +which maps a regular expression to a path relative to the +@code{:working-directory}. + +Now map the URL to the path @file{/home/user/example/products.php} by adding +@code{:rewrites} rules 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 + +@noindent +Since @samp{example.com/$} is used as a regular expression, it maps +@url{http://example.com/}, @url{https://example.com}, +@url{http://www.example.com/} and similar to +@file{/home/user/example/index.php}. + +The @code{:rewrites} rules are searched as a last resort if and only if no +existing file name is matched. + +@cindex protocol, open-source, set-up mapping +@cindex set-up mappings in open-source protocol +@findex org-protocol-create +@findex org-protocol-create-for-org +Two functions can help you filling @code{org-protocol-project-alist} with +valid contents: @code{org-protocol-create} and +@code{org-protocol-create-for-org}. The latter is of use if you're editing +an Org file that is part of a publishing project. @node Refile and copy @section Refile and copy -- 2.13.2 ^ permalink raw reply related [flat|nested] 42+ messages in thread
* Re: org-protocol documentation 2017-07-06 17:54 ` Nicolas Goaziou @ 2017-07-23 16:18 ` Mario Martelli 2017-07-23 20:49 ` Nicolas Goaziou 0 siblings, 1 reply; 42+ messages in thread From: Mario Martelli @ 2017-07-23 16:18 UTC (permalink / raw) To: Nicolas Goaziou; +Cc: Org-mode [-- Attachment #1: Type: text/plain, Size: 826 bytes --] Hi, sorry for late response. I like the new docs very much. I would like to suggest some minor changes. Kind regards Mario — > Am 06.07.2017 um 19:54 schrieb Nicolas Goaziou <mail@nicolasgoaziou.fr>: > > Hello, > > Mario Martelli <tlmtr@schnuddelhuddel.de> writes: > >> I started this whole thing because I wanted to learn elisp. But >> learning texinfo en-passant is nice :) > > Thank you for your patch. > > I re-worded the documentation based on your work. I also added more > index entries. Since I'm not using Org Protocol, I may fall wide of the > mark. > > Anyway, it's now your turn to do some reviewing ;) > > WDYT? > > Regards, > > -- > Nicolas Goaziou 0x80A93738 > <0001-org.texi-Document-Org-Protocol.patch> [-- Attachment #2.1: Type: text/html, Size: 440 bytes --] [-- Attachment #2.2: 0001-oprg-prtocol-minor-changes-to-new-documentation.patch --] [-- Type: application/octet-stream, Size: 1555 bytes --] From 289f7dd62f06795005af4219d58ace2a551f57e9 Mon Sep 17 00:00:00 2001 From: Mario Martelli <cocoa@schnuddelhuddel.de> Date: Sun, 23 Jul 2017 18:14:47 +0200 Subject: [PATCH] oprg-prtocol: minor changes to new documentation --- doc/org.texi | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 9add87a84..23d629d05 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -7522,7 +7522,7 @@ For more information, including how to read atom feeds, see @section Protocols for external access @cindex protocols, for external access -Org protocol in a mean to trigger custom actions in Emacs from external +Org protocol's mean is to trigger custom actions in Emacs from external applications. Any application that supports calling external programs with an URL as argument may be used with this functionality. For example, you can configure bookmarks in your web browser to send a link to the current page to @@ -7538,12 +7538,12 @@ to Emacs through the @code{emacsclient} command, so you also need to ensure an Emacs server is running. More precisely, when the application calls @example -emacsclient org-protocol://PROTOCOL?key1=var1&key2=var2 +emacsclient org-protocol://PROTOCOL?key1=val1&key2=val2 @end example @noindent Emacs calls the handler associated to @samp{PROTOCOL} with argument -@samp{(:key1 var1 :key2 var2)}. +@samp{(:key1 val1 :key2 val2)}. @cindex protocol, new protocol @cindex defining new protocols -- 2.11.0 (Apple Git-81) [-- Attachment #2.3: Type: text/html, Size: 3477 bytes --] ^ permalink raw reply related [flat|nested] 42+ messages in thread
* Re: org-protocol documentation 2017-07-23 16:18 ` Mario Martelli @ 2017-07-23 20:49 ` Nicolas Goaziou 0 siblings, 0 replies; 42+ messages in thread From: Nicolas Goaziou @ 2017-07-23 20:49 UTC (permalink / raw) To: Mario Martelli; +Cc: Org-mode Hello, Mario Martelli <tlmtr@schnuddelhuddel.de> writes: > sorry for late response. I like the new docs very much. > > I would like to suggest some minor changes. Thank you for the feedback. I included your suggestions and pushed the change. Regards, -- Nicolas Goaziou ^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: org-protocol documentation 2017-07-01 13:13 ` Mario Martelli 2017-07-01 16:42 ` Nicolas Goaziou @ 2017-07-23 22:39 ` Adam Porter 2017-07-24 6:17 ` Colin Baxter 1 sibling, 1 reply; 42+ messages in thread From: Adam Porter @ 2017-07-23 22:39 UTC (permalink / raw) To: emacs-orgmode Mario Martelli <tlmtr@schnuddelhuddel.de> writes: > I suppose so, if one knows how to configure URL handlers on their > OS. Of course there are some things missing from the > documentation. But it’s more than we have at the moment :) FYI, I have some instructions for setting up org-protocol at https://github.com/alphapapa/org-protocol-capture-html#org-protocol-instructions and https://stackoverflow.com/a/32851154 ^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: org-protocol documentation 2017-07-23 22:39 ` Adam Porter @ 2017-07-24 6:17 ` Colin Baxter 2017-07-24 23:53 ` Adam Porter 0 siblings, 1 reply; 42+ messages in thread From: Colin Baxter @ 2017-07-24 6:17 UTC (permalink / raw) To: Adam Porter; +Cc: emacs-orgmode Dear Adam, >>>>> "Adam" == Adam Porter <adam@alphapapa.net> writes: Adam> FYI, I have some instructions for setting up org-protocol at Adam> https://github.com/alphapapa/org-protocol-capture-html#org-protocol-instructions Adam> and https://stackoverflow.com/a/32851154 I notice that your instructions give (require 'org-protocol). Does that mean (setq org-modules (quote (org-protocol))) no longer works? -- -- Colin Baxter m43cap@yandex.com GnuPG fingerprint: 68A8 799C 0230 16E7 BF68 2A27 BBFA 2492 91F5 41C8 ^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: org-protocol documentation 2017-07-24 6:17 ` Colin Baxter @ 2017-07-24 23:53 ` Adam Porter 2017-07-25 8:13 ` Colin Baxter 0 siblings, 1 reply; 42+ messages in thread From: Adam Porter @ 2017-07-24 23:53 UTC (permalink / raw) To: emacs-orgmode Colin Baxter <m43cap@yandex.com> writes: > I notice that your instructions give (require 'org-protocol). Does that > mean (setq org-modules (quote (org-protocol))) no longer works? No, that should work too, as long as that is run before Org is loaded. You may prefer to use the customize interface for setting org-modules. ^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: org-protocol documentation 2017-07-24 23:53 ` Adam Porter @ 2017-07-25 8:13 ` Colin Baxter 0 siblings, 0 replies; 42+ messages in thread From: Colin Baxter @ 2017-07-25 8:13 UTC (permalink / raw) To: Adam Porter; +Cc: emacs-orgmode >>>>> "Adam" == Adam Porter <adam@alphapapa.net> writes: Adam> Colin Baxter <m43cap@yandex.com> writes: >> I notice that your instructions give (require >> 'org-protocol). Does that mean (setq org-modules (quote >> (org-protocol))) no longer works? Adam> No, that should work too, as long as that is run before Org is Adam> loaded. You may prefer to use the customize interface for Adam> setting org-modules. Thank you. -- -- Colin Baxter m43cap@yandex.com GnuPG fingerprint: 68A8 799C 0230 16E7 BF68 2A27 BBFA 2492 91F5 41C8 ^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: org-protocol documentation 2017-06-29 12:42 ` Nicolas Goaziou 2017-06-29 18:30 ` Mario Martelli @ 2017-06-30 4:42 ` Mario Martelli 1 sibling, 0 replies; 42+ messages in thread From: Mario Martelli @ 2017-06-30 4:42 UTC (permalink / raw) To: Nicolas Goaziou; +Cc: emacs-orgmode [-- Attachment #1: Type: text/plain, Size: 1206 bytes --] >> +worked for me on Windows-XP Professional and the emasc23 from ourcomments.org <http://ourcomments.org/> >> +(@uref{http://ourcomments.org/cgi-bin/emacsw32-dl-latest.pl <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 <http://kb.mozillazine.org/Register_protocol>}. > > Could someone double-check this? > >> +@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 > > See above. As it seems Org protocol is not so popular :) I assume there will be no feedback and it'll be sufficient to relegate to the OS documentation. Especially the OS and 3rd party application related stuff made be anxious about rewriting the original documentation. [-- Attachment #2: Type: text/html, Size: 4817 bytes --] ^ permalink raw reply [flat|nested] 42+ messages in thread
* Re: org-protocol documentation 2017-06-19 10:14 org-protocol documentation Mario Martelli 2017-06-19 10:41 ` Nicolas Goaziou @ 2017-06-19 12:26 ` Chunyang Xu 1 sibling, 0 replies; 42+ messages in thread From: Chunyang Xu @ 2017-06-19 12:26 UTC (permalink / raw) To: Mario Martelli, emacs-orgmode Mario Martelli <tlmtr@schnuddelhuddel.de> writes: > Hi, > > recently I’ve updated my macOS - Org mode setup. I had some pain setting up org-protocol properly for what it's worth, the Emacs Mac Port supports org-protocol out of box. It works without the Emacs server (emacsclient), e.g., $ open 'org-protocol://store-link?url=http%3A%2F%2Forgmode.org&title=Org%20mode' Thus for Emacs Mac Port users, no setup is needed. [Emacs Mac Port] https://bitbucket.org/mituharu/emacs-mac [...] ^ permalink raw reply [flat|nested] 42+ messages in thread
end of thread, other threads:[~2017-07-25 8:14 UTC | newest] Thread overview: 42+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2017-06-19 10:14 org-protocol documentation Mario Martelli 2017-06-19 10:41 ` Nicolas Goaziou 2017-06-19 12:37 ` Mario Martelli 2017-06-19 13:41 ` Chunyang Xu 2017-06-21 17:29 ` Nicolas Goaziou 2017-06-21 18:58 ` Mario Martelli 2017-06-21 19:12 ` Nicolas Goaziou 2017-06-22 8:40 ` Mario Martelli 2017-06-22 19:32 ` Mario Martelli 2017-06-22 20:03 ` Nicolas Goaziou 2017-06-23 7:50 ` Mario Martelli 2017-06-23 16:46 ` Mario Martelli 2017-06-25 6:49 ` [PATCH] org-protocol: fixes open-source and extends rewriting of URLs Mario Martelli 2017-06-25 7:17 ` Nicolas Goaziou 2017-06-25 8:21 ` Mario Martelli 2017-06-26 20:46 ` Nicolas Goaziou 2017-06-27 6:54 ` Mario Martelli 2017-06-28 9:32 ` Nicolas Goaziou 2017-06-28 14:44 ` Mario Martelli 2017-06-28 15:49 ` Nicolas Goaziou 2017-06-29 8:28 ` Mario Martelli 2017-06-29 12:47 ` Nicolas Goaziou 2017-06-25 10:15 ` org-protocol documentation Mario Martelli 2017-06-29 12:42 ` Nicolas Goaziou 2017-06-29 18:30 ` Mario Martelli 2017-06-30 12:05 ` Mario Martelli 2017-07-01 10:34 ` Nicolas Goaziou 2017-07-01 13:13 ` Mario Martelli 2017-07-01 16:42 ` Nicolas Goaziou 2017-07-01 16:44 ` Nicolas Goaziou 2017-07-01 19:24 ` Mario Martelli 2017-07-03 17:21 ` Nick Dokos 2017-07-03 18:09 ` Mario Martelli 2017-07-06 17:54 ` Nicolas Goaziou 2017-07-23 16:18 ` Mario Martelli 2017-07-23 20:49 ` Nicolas Goaziou 2017-07-23 22:39 ` Adam Porter 2017-07-24 6:17 ` Colin Baxter 2017-07-24 23:53 ` Adam Porter 2017-07-25 8:13 ` Colin Baxter 2017-06-30 4:42 ` Mario Martelli 2017-06-19 12:26 ` Chunyang Xu
Code repositories for project(s) associated with this public inbox https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).