emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Mario Martelli <tlmtr@schnuddelhuddel.de>
To: Nicolas Goaziou <mail@nicolasgoaziou.fr>
Cc: emacs-orgmode@gnu.org
Subject: Re: org-protocol documentation
Date: Fri, 30 Jun 2017 14:05:10 +0200	[thread overview]
Message-ID: <4D8D18D3-FBA7-4878-AB6A-76CE57635127@schnuddelhuddel.de> (raw)
In-Reply-To: <C2DA0E26-3B55-45C6-86D0-6C8AE7D357FE@schnuddelhuddel.de>

[-- 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
— 


  reply	other threads:[~2017-06-30 12:05 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 [this message]
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

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=4D8D18D3-FBA7-4878-AB6A-76CE57635127@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).