From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
To: Mario Martelli <tlmtr@schnuddelhuddel.de>
Cc: emacs-orgmode@gnu.org
Subject: Re: org-protocol documentation
Date: Sat, 01 Jul 2017 12:34:04 +0200 [thread overview]
Message-ID: <878tk84fab.fsf@nicolasgoaziou.fr> (raw)
In-Reply-To: <4D8D18D3-FBA7-4878-AB6A-76CE57635127@schnuddelhuddel.de> (Mario Martelli's message of "Fri, 30 Jun 2017 14:05:10 +0200")
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
next prev parent reply other threads:[~2017-07-01 10:34 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 [this message]
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=878tk84fab.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).