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 21:24:47 +0200 [thread overview]
Message-ID: <A062DAC9-00CA-4409-A518-6E41D753108A@schnuddelhuddel.de> (raw)
In-Reply-To: <8760fc2joe.fsf@nicolasgoaziou.fr>
[-- 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
—
next prev parent reply other threads:[~2017-07-01 19:24 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 [this message]
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=A062DAC9-00CA-4409-A518-6E41D753108A@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).