From mboxrd@z Thu Jan 1 00:00:00 1970 From: Nicolas Goaziou Subject: Re: org-protocol documentation Date: Sat, 01 Jul 2017 12:34:04 +0200 Message-ID: <878tk84fab.fsf@nicolasgoaziou.fr> References: <68E12968-9AF5-440A-B22C-AC55B70BA910@schnuddelhuddel.de> <87k248b6p8.fsf@nicolasgoaziou.fr> <7C76EDC3-CC7E-4AFE-B45B-867752C1B33A@schnuddelhuddel.de> <87a8519rlg.fsf@nicolasgoaziou.fr> <8760fp9mui.fsf@nicolasgoaziou.fr> <2FAD7DF2-2A0C-4703-A383-BA8D3346C691@schnuddelhuddel.de> <18D83D3C-C472-4614-988F-1F1DA5EB5CEC@schnuddelhuddel.de> <87efub7psj.fsf@nicolasgoaziou.fr> <87lgobrmm7.fsf@nicolasgoaziou.fr> <4D8D18D3-FBA7-4878-AB6A-76CE57635127@schnuddelhuddel.de> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:53429) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dRFjA-0004y2-OT for emacs-orgmode@gnu.org; Sat, 01 Jul 2017 06:34:14 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dRFj6-0003iB-Au for emacs-orgmode@gnu.org; Sat, 01 Jul 2017 06:34:12 -0400 Received: from relay2-d.mail.gandi.net ([217.70.183.194]:56368) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1dRFj6-0003hA-0o for emacs-orgmode@gnu.org; Sat, 01 Jul 2017 06:34:08 -0400 In-Reply-To: <4D8D18D3-FBA7-4878-AB6A-76CE57635127@schnuddelhuddel.de> (Mario Martelli's message of "Fri, 30 Jun 2017 14:05:10 +0200") List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: "Emacs-orgmode" To: Mario Martelli Cc: emacs-orgmode@gnu.org Hello, Mario Martelli writes: > I created a pretty short documentation of org-protocol. It=E2=80=99s 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 th= e 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-alis= t} > +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-alis= t} with > +valid contents. One possibility is @code{org-protocol-create} that guide= s 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 publis= hing Missing space. Also,=20 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 r= emove the > +line breaks and replace @code{sub-protocol} with the real sub-protocol t= o use: > + > +@example > +javascript:location.href=3D'org-protocol://sub-protocol? > +template=3Dx&url=3D'+encodeURIComponent(window.location.href)+ > +'&title=3D'+encodeURIComponent(document.title)+ > +'&body=3D'+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} a= nd > + 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=3DURL&title=3DTITLE > +@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=3D'org-protocol://store-link? > + url=3D'+encodeURIComponent(location.href); > +@end example > + > +@item @code{org-capture} > +This one is triggered through the sub-protocol @code{capture} and consum= es up > +to four data fields: > + > +@example > +@file{emacsclient} org-protocol:/capture?template=3D\ > +TEMPLATE?url=3DURL?title=3DTITLE?body=3DBODY > +@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=3D'org-protocol:// > +template=3Dx&url=3D'+encodeURIComponent(window.location.href)+ > +'&title=3D'+encodeURIComponent(document.title)+ > +'&body=3D'+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, --=20 Nicolas Goaziou