From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
To: Mario Martelli <tlmtr@schnuddelhuddel.de>
Cc: emacs-orgmode@gnu.org
Subject: Re: org-protocol documentation
Date: Thu, 06 Jul 2017 19:54:15 +0200 [thread overview]
Message-ID: <8760f578oo.fsf@nicolasgoaziou.fr> (raw)
In-Reply-To: <A062DAC9-00CA-4409-A518-6E41D753108A@schnuddelhuddel.de> (Mario Martelli's message of "Sat, 1 Jul 2017 21:24:47 +0200")
[-- 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
next prev parent reply other threads:[~2017-07-06 17:54 UTC|newest]
Thread overview: 42+ messages / expand[flat|nested] mbox.gz Atom feed top
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 [this message]
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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=8760f578oo.fsf@nicolasgoaziou.fr \
--to=mail@nicolasgoaziou.fr \
--cc=emacs-orgmode@gnu.org \
--cc=tlmtr@schnuddelhuddel.de \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).