From: Mario Martelli <tlmtr@schnuddelhuddel.de>
To: Nicolas Goaziou <mail@nicolasgoaziou.fr>
Cc: emacs-orgmode@gnu.org
Subject: Re: org-protocol documentation
Date: Sat, 1 Jul 2017 15:13:47 +0200 [thread overview]
Message-ID: <CF831D7D-3C02-4FB6-BA13-7A0E60A9568D@schnuddelhuddel.de> (raw)
In-Reply-To: <878tk84fab.fsf@nicolasgoaziou.fr>
[-- 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
—
next prev parent reply other threads:[~2017-07-01 13:13 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 [this message]
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
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=CF831D7D-3C02-4FB6-BA13-7A0E60A9568D@schnuddelhuddel.de \
--to=tlmtr@schnuddelhuddel.de \
--cc=emacs-orgmode@gnu.org \
--cc=mail@nicolasgoaziou.fr \
/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).