From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mario Martelli Subject: Re: org-protocol documentation Date: Sat, 1 Jul 2017 21:24:47 +0200 Message-ID: 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> <878tk84fab.fsf@nicolasgoaziou.fr> <8760fc2joe.fsf@nicolasgoaziou.fr> Mime-Version: 1.0 (Mac OS X Mail 10.3 \(3273\)) Content-Type: multipart/mixed; boundary="Apple-Mail=_93C44B88-8C10-4C7C-A65D-131E9C3E2DBA" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:46230) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dRO0l-00070u-B8 for emacs-orgmode@gnu.org; Sat, 01 Jul 2017 15:24:56 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dRO0i-0004gp-5a for emacs-orgmode@gnu.org; Sat, 01 Jul 2017 15:24:55 -0400 Received: from mail-wm0-x234.google.com ([2a00:1450:400c:c09::234]:35821) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1dRO0h-0004g2-Od for emacs-orgmode@gnu.org; Sat, 01 Jul 2017 15:24:52 -0400 Received: by mail-wm0-x234.google.com with SMTP id w126so135773669wme.0 for ; Sat, 01 Jul 2017 12:24:51 -0700 (PDT) In-Reply-To: <8760fc2joe.fsf@nicolasgoaziou.fr> 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: Nicolas Goaziou Cc: emacs-orgmode@gnu.org --Apple-Mail=_93C44B88-8C10-4C7C-A65D-131E9C3E2DBA Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=utf-8 >> I=E2=80=99m not happy with that there is so much information - = although >> outdated - in the old Worg documentation which might be hidden to the >> reader. >=20 > 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. >=20 > Though, I'm puzzled, `org-publish-project-alist' is a variable, not a = function. Don=E2=80=99t know what happened there. Repaired. >> +Org protocol is triggered by @file{emacsclient}. If you want to use = Org > ^^^ > Gotcha >=20 >> +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 :) --Apple-Mail=_93C44B88-8C10-4C7C-A65D-131E9C3E2DBA Content-Disposition: attachment; filename=0001-org.texi-Basic-Org-protocol-documentation-is-added.patch Content-Type: application/octet-stream; x-unix-mode=0644; name="0001-org.texi-Basic-Org-protocol-documentation-is-added.patch" Content-Transfer-Encoding: quoted-printable =46rom=20fb9a7538b5a6965cf10da2371bb93fdebf51ddb7=20Mon=20Sep=2017=20= 00:00:00=202001=0AFrom:=20Mario=20Martelli=20=0A= Date:=20Sat,=201=20Jul=202017=2014:39:46=20+0200=0ASubject:=20[PATCH=20= 1/3]=20org.texi:=20Basic=20Org=20protocol=20documentation=20is=20added=0A= =0A*=20doc/org.texi=20Basic=20Org=20protocol=20documentation=20is=20= added=0A---=0A=20doc/org.texi=20|=20121=20= +++++++++++++++++++++++++++++++++++++++++++++++++++++++++--=0A=201=20= file=20changed,=20118=20insertions(+),=203=20deletions(-)=0A=0Adiff=20= --git=20a/doc/org.texi=20b/doc/org.texi=0Aindex=20879756e6f..76f491a78=20= 100644=0A---=20a/doc/org.texi=0A+++=20b/doc/org.texi=0A@@=20-7522,9=20= +7522,124=20@@=20are=20passed=20to=20Emacs=20through=20the=20= @file{emacsserver}.=20=20For=20example,=20you=20can=0A=20configure=20= bookmarks=20in=20your=20web=20browser=20to=20send=20a=20link=20to=20the=20= current=20page=20to=0A=20Org=20and=20create=20a=20note=20from=20it=20= using=20capture=20(@pxref{Capture}).=20=20Or=20you=0A=20could=20create=20= a=20bookmark=20that=20will=20tell=20Emacs=20to=20open=20the=20local=20= source=20file=20of=0A-a=20remote=20website=20you=20are=20looking=20at=20= with=20the=20browser.=20=20See=0A= -@uref{http://orgmode.org/worg/org-contrib/org-protocol.php}=20for=20= detailed=0A-documentation=20and=20setup=20instructions.=0A+a=20remote=20= website=20you=20are=20looking=20at=20with=20the=20browser.=0A+=0A+Org=20= protocol=20comes=20with=20three=20predefined=20handlers:=0A+@table=20= @asis=0A+@item=20@code{org-protocol-store-link}=0A+=09Triggered=20= through=20the=20sub-protocol=20@code{store-link}.=20=20Store=20a=0A+link=20= and=20push=20the=20URL=20to=20the=20kill-ring.=0A+@item=20= @code{org-protocol-capture}=0A+=09Fill=20a=20@code{capture}=20buffer=20= with=20information=20gathered=20somewhere=0A+else.=20=20This=20handler=20= is=20triggered=20through=20the=20@code{capture}=20sub-protocol=20and=0A= +uses=20the=20function=20@code{org-capture}.=0A+@item=20= @code{org-protocol-open-source}=0A+=09@code{open-source}.=20=20Map=20a=20= URL=20to=20local=20filename.=20=20Use=20this=20to=20open=0A+sources=20of=20= already=20published=20contents=20in=20Emacs=20for=20editing.=0A+@end=20= table=0A+=0A+@node=20Setting=20up=20Org=20protocol=0A+@subsection=20= Setting=20up=20Org=20protocol=0A+You=20need=20to=20set=20up=20a=20custom=20= URL=20handler=20on=20your=20system=20to=20trigger=20Emacs=20by=20a=0A= +URL.=20=20This=20URL=20handler=20could=20be=20already=20installed=20by=20= Emacs.=20=20Please=20consult=20the=0A+handbook=20of=20your=20operating=20= system=20how=20to=20install=20a=20custom=20URL=20handler=20if=20you=0A= +need=20to.=0A+=0A+To=20map=20a=20website=20with=20@code{open-source}=20= to=20local=20files=20you=20have=20to=20set=20up=0A+the=20mapping=20in=20= @code{org-protocol-project-alist}.=0A+=0A+For=20example,=20in=20order=20= to=20open=20files=20published=20on=20Worg=20locally,=20you=20can=20set=0A= +@code{org-protocol-project-alist}=20to=20the=20following=0A+=0A+@lisp=0A= +(setq=20org-protocol-project-alist=0A+=20=20=20=20=20=20'(("Worg"=0A+=09= =20:base-url=20"http://orgmode.org/worg/"=0A+=09=20:working-directory=20= "/home/user/worg/"=0A+=09=20:online-suffix=20".html"=0A+=09=20= :working-suffix=20".org")))=0A+@end=20lisp=0A+=0A+Two=20functions=20can=20= help=20you=20fill=20@code{org-protocol-project-alist}=20with=20valid=0A= +contents:=20@code{org-protocol-create}=20and=20= @code{org-publish-project-alist}.=20=20The=0A+latter=20is=20of=20use=20= if=20you're=20editing=20an=20Org=20file=20that=20is=20part=20of=20a=0A= +publishing=20project.=0A+=0A+@node=20Using=20Org=20protocol=0A= +@subsection=20Using=20Org=20protocol=0A+Org=20protocol=20is=20triggered=20= by=20@file{emacsclient}.=20If=20you=20want=20to=20use=20Org=0A+protocol,=20= there=20are=20many=20possibilities=20to=20do=20so.=20=20You=20can=20= invoke=20emacsclient=0A+by=20a=20shortcut=20on=20your=20desktop=20for=20= example.=20Or=20by=20adding=20a=20bookmark=20to=20your=20browser.=0A+=0A= +Here=20is=20the=20URL=20to=20use=20as=20@emph{Location}=20for=20browser=20= bookmarks.=20=20Just=20remove=20the=0A+line=20breaks=20and=20replace=20= @code{sub-protocol}=20with=20the=20real=20sub-protocol=20to=20use:=0A+=0A= +@example=0A+javascript:location.href=3D'org-protocol://sub-protocol?=0A= +template=3Dx&url=3D'+encodeURIComponent(window.location.href)+=0A= +'&title=3D'+encodeURIComponent(document.title)+=0A= +'&body=3D'+encodeURIComponent(window.getSelection());=0A+@end=20example=0A= +=0A+This=20URL=20may=20be=20used=20for=20all=20three=20standard=20= handlers=20in=0A+@code{org-protocol.el}.=20=20Some=20of=20the=20values=20= are=20ignored,=0A+e.g.=20@code{store-link}=20uses=20the=20URL=20and=20= title=20only.=0A+=0A+@table=20@asis=0A+@item=20@code{org-store-link}=0A+=20= =20=20=20=20=20store=20a=20link,=20insertable=20through=20@kbd{M-x=20= org-insert-link}=20and=0A+=20=20=20=20=20=20push=20the=20URL=20found=20= onto=20the=20kill-ring=20for=20yanking.=0A+=20=20=20=20=20=20The=20= sub-protocol=20used=20is=20@code{store-link}:=0A+=0A+@example=0A= +emacsclient=20org-protocol://store-link?url=3DURL&title=3DTITLE=0A+@end=20= example=0A+=0A+will=20store=20the=20following=20link:=0A+=0A+@example=0A= +[[URL][TITLE]]=0A+@end=20example=0A+=0A+In=20addition,=20@code{URL}=20= is=20pushed=20on=20the=20kill-ring=20for=20yanking.=0A+You=20need=20to=20= encode=20@code{URL}=20and=20@code{TITLE}=20if=0A+they=20contain=20= slashes,=20and=20probably=20quote=20those=20for=20the=20shell.=0A+=0A+To=20= use=20this=20feature,=20add=20a=20bookmark=20with=20an=20arbitrary=20= name,=20e.g.=0A+@samp{Org:=20store-link}=20and=20enter=20this=20as=20= @samp{Location}:=0A+=0A+@example=0A= +javascript:location.href=3D'org-protocol://store-link?=0A+=20=20=20=20=20= =20=20=20=20=20=20url=3D'+encodeURIComponent(location.href);=0A+@end=20= example=0A+=0A+@item=20@code{org-capture}=0A+This=20one=20is=20triggered=20= through=20the=20sub-protocol=20@code{capture}=20and=20consumes=20up=0A= +to=20four=20data=20fields:=0A+=0A+@example=0A+@file{emacsclient}=20= org-protocol:/capture?template=3D\=0A= +TEMPLATE?url=3DURL?title=3DTITLE?body=3DBODY=0A+@end=20example=0A+=0A= +@noindent=0A+pops=20up=20a=20@samp{Capture}=20buffer=20and=20fill=20the=20= template=20with=20the=20data=0A+submitted.=0A+=0A+To=20use=20this=20= feature,=20add=20a=20bookmark=20with=20an=20arbitrary=20name,=20e.g.=0A= +@samp{Org:=20capture}=20and=20enter=20this=20as=20@samp{Location}:=0A+=0A= +=0A+@example=0A+javascript:location.href=3D'org-protocol://=0A= +template=3Dx&url=3D'+encodeURIComponent(window.location.href)+=0A= +'&title=3D'+encodeURIComponent(document.title)+=0A= +'&body=3D'+encodeURIComponent(window.getSelection());=0A+@end=20example=0A= +=0A+The=20result=20depends=20on=20the=20template=20used.=0A+=0A+@end=20= table=0A=20=0A=20@node=20Refile=20and=20copy=0A=20@section=20Refile=20= and=20copy=0A--=20=0A2.11.0=20(Apple=20Git-81)=0A=0A= --Apple-Mail=_93C44B88-8C10-4C7C-A65D-131E9C3E2DBA Content-Disposition: attachment; filename=0002-org.texi-Fixes-missing-space-after-dot.patch Content-Type: application/octet-stream; x-unix-mode=0644; name="0002-org.texi-Fixes-missing-space-after-dot.patch" Content-Transfer-Encoding: quoted-printable =46rom=201bd6e3b3390609254f1fae79a53957ba3f51868c=20Mon=20Sep=2017=20= 00:00:00=202001=0AFrom:=20Mario=20Martelli=20=0A= Date:=20Sat,=201=20Jul=202017=2014:44:45=20+0200=0ASubject:=20[PATCH=20= 2/3]=20org.texi:=20Fixes=20missing=20space=20after=20dot.=0A=0A*=20= org.texi=20Minor=20change=20regarding=20missing=20space=0A---=0A=20= doc/org.texi=20|=204=20++--=0A=201=20file=20changed,=202=20= insertions(+),=202=20deletions(-)=0A=0Adiff=20--git=20a/doc/org.texi=20= b/doc/org.texi=0Aindex=2076f491a78..93c9d4167=20100644=0A---=20= a/doc/org.texi=0A+++=20b/doc/org.texi=0A@@=20-829,7=20+829,7=20@@=20= different=20formats=20such=20as=20HTML,=20@LaTeX{},=20Open=20Document,=20= and=20Markdown.=20=20New=0A=20export=20backends=20can=20be=20derived=20= from=20existing=20ones,=20or=20defined=20from=20scratch.=0A=20=0A=20Org=20= files=20can=20include=20source=20code=20blocks,=20which=20makes=20Org=20= uniquely=20suited=20for=0A-authoring=20technical=20documents=20with=20= code=20examples.=20Org=20source=20code=20blocks=20are=0A+authoring=20= technical=20documents=20with=20code=20examples.=20=20Org=20source=20code=20= blocks=20are=0A=20fully=20functional;=20they=20can=20be=20evaluated=20in=20= place=20and=20their=20results=20can=20be=0A=20captured=20in=20the=20= file.=20=20This=20makes=20it=20possible=20to=20create=20a=20single=20= file=0A=20reproducible=20research=20compendium.=0A@@=20-8200,7=20+8200,7=20= @@=20you=20can=20use=20the=20following=20instead:=0A=20@end=20example=0A=20= =0A=20That=20will=20give=20you=20three=20days'=20warning:=20on=20the=20= anniversary=20date=20itself=20and=20the=0A-two=20days=20prior.=20The=20= argument=20is=20optional:=20if=20omitted,=20it=20defaults=20to=207.=0A= +two=20days=20prior.=20=20The=20argument=20is=20optional:=20if=20= omitted,=20it=20defaults=20to=207.=0A=20=0A=20@subsubheading=20= Appointment=20reminders=0A=20@cindex=20@file{appt.el}=0A--=20=0A2.11.0=20= (Apple=20Git-81)=0A=0A= --Apple-Mail=_93C44B88-8C10-4C7C-A65D-131E9C3E2DBA Content-Disposition: attachment; filename=0003-org.texi-Minor-changes-and-added-index-to-org-protoc.patch Content-Type: application/octet-stream; x-unix-mode=0644; name="0003-org.texi-Minor-changes-and-added-index-to-org-protoc.patch" Content-Transfer-Encoding: quoted-printable =46rom=209468832e402e46c1a574cdeeadaa6b7ae275198c=20Mon=20Sep=2017=20= 00:00:00=202001=0AFrom:=20Mario=20Martelli=20=0A= Date:=20Sat,=201=20Jul=202017=2021:13:54=20+0200=0ASubject:=20[PATCH=20= 3/3]=20org.texi:=20Minor=20changes=20and=20added=20index=20to=20= org-protocol=0A=0A*=20doc/org.texi=20Minor=20changes=20and=20added=20= index=20to=20org-protocol=0A---=0A=20doc/org.texi=20|=2030=20= +++++++++++++++++++++---------=0A=201=20file=20changed,=2021=20= insertions(+),=209=20deletions(-)=0A=0Adiff=20--git=20a/doc/org.texi=20= b/doc/org.texi=0Aindex=2093c9d4167..7add60d5c=20100644=0A---=20= a/doc/org.texi=0A+++=20b/doc/org.texi=0A@@=20-7528,26=20+7528,31=20@@=20= Org=20protocol=20comes=20with=20three=20predefined=20handlers:=0A=20= @table=20@asis=0A=20@item=20@code{org-protocol-store-link}=0A=20=09= Triggered=20through=20the=20sub-protocol=20@code{store-link}.=20=20Store=20= a=0A-link=20and=20push=20the=20URL=20to=20the=20kill-ring.=0A+=20=20=20=20= =20=20=20=20link=20and=20push=20the=20URL=20to=20the=20kill-ring.=0A=20= @item=20@code{org-protocol-capture}=0A-=09Fill=20a=20@code{capture}=20= buffer=20with=20information=20gathered=20somewhere=0A-else.=20=20This=20= handler=20is=20triggered=20through=20the=20@code{capture}=20sub-protocol=20= and=0A-uses=20the=20function=20@code{org-capture}.=0A+=09Triggered=20= through=20the=20sub-protocol=20@code{capture}.=20=20Fill=20a=20buffer=0A= +=20=20=20=20=20=20=20=20with=20information=20gathered=20somewhere=20= else.=0A=20@item=20@code{org-protocol-open-source}=0A-=09= @code{open-source}.=20=20Map=20a=20URL=20to=20local=20filename.=20=20Use=20= this=20to=20open=0A-sources=20of=20already=20published=20contents=20in=20= Emacs=20for=20editing.=0A+=09Triggered=20through=20the=20sub-protoicol=20= @code{open-source}.=20=20Map=20a=20URL=20to=0A+=09local=20filename.=20=20= Use=20this=20to=20open=20sources=20of=20already=20published=0A+=09= contents=20in=20Emacs=20for=20editing.=0A=20@end=20table=0A=20=0A=20= @node=20Setting=20up=20Org=20protocol=0A=20@subsection=20Setting=20up=20= Org=20protocol=0A+@cindex=20Org=20protocol,=20set-up=0A+@cindex=20= Installing=20Org=20protocol=0A+=0A=20You=20need=20to=20set=20up=20a=20= custom=20URL=20handler=20on=20your=20system=20to=20trigger=20Emacs=20by=20= a=0A=20URL.=20=20This=20URL=20handler=20could=20be=20already=20installed=20= by=20Emacs.=20=20Please=20consult=20the=0A=20handbook=20of=20your=20= operating=20system=20how=20to=20install=20a=20custom=20URL=20handler=20= if=20you=0A=20need=20to.=0A=20=0A+@vindex=20org-protocol-project-alist=0A= =20To=20map=20a=20website=20with=20@code{open-source}=20to=20local=20= files=20you=20have=20to=20set=20up=0A=20the=20mapping=20in=20= @code{org-protocol-project-alist}.=0A=20=0A+@vindex=20= org-protocol-project-alist=0A=20For=20example,=20in=20order=20to=20open=20= files=20published=20on=20Worg=20locally,=20you=20can=20set=0A=20= @code{org-protocol-project-alist}=20to=20the=20following=0A=20=0A@@=20= -7560,15=20+7565,22=20@@=20For=20example,=20in=20order=20to=20open=20= files=20published=20on=20Worg=20locally,=20you=20can=20set=0A=20=09=20= :working-suffix=20".org")))=0A=20@end=20lisp=0A=20=0A+@vindex=20= org-protocol-project-alist=0A+@findex=20org-protocol-create=0A+@findex=20= org-protocol-create-for-org=0A=20Two=20functions=20can=20help=20you=20= fill=20@code{org-protocol-project-alist}=20with=20valid=0A-contents:=20= @code{org-protocol-create}=20and=20@code{org-publish-project-alist}.=20=20= The=0A+contents:=20@code{org-protocol-create}=20and=20= @code{org-protocol-create-for-org}.=20=20The=0A=20latter=20is=20of=20use=20= if=20you're=20editing=20an=20Org=20file=20that=20is=20part=20of=20a=0A=20= publishing=20project.=0A=20=0A=20@node=20Using=20Org=20protocol=0A=20= @subsection=20Using=20Org=20protocol=0A+@cindex=20Org=20protocol,=20= using=0A+@cindex=20Using=20Org=20protocol=0A+=0A+=0A=20Org=20protocol=20= is=20triggered=20by=20@file{emacsclient}.=20If=20you=20want=20to=20use=20= Org=0A-protocol,=20there=20are=20many=20possibilities=20to=20do=20so.=20=20= You=20can=20invoke=20emacsclient=0A+protocol,=20there=20are=20many=20= possibilities=20to=20do=20so.=20=20You=20can=20invoke=20= @file{emacsclient}=0A=20by=20a=20shortcut=20on=20your=20desktop=20for=20= example.=20Or=20by=20adding=20a=20bookmark=20to=20your=20browser.=0A=20=0A= =20Here=20is=20the=20URL=20to=20use=20as=20@emph{Location}=20for=20= browser=20bookmarks.=20=20Just=20remove=20the=0A@@=20-7592,7=20+7604,7=20= @@=20e.g.=20@code{store-link}=20uses=20the=20URL=20and=20title=20only.=0A= =20=20=20=20=20=20=20The=20sub-protocol=20used=20is=20@code{store-link}:=0A= =20=0A=20@example=0A-emacsclient=20= org-protocol://store-link?url=3DURL&title=3DTITLE=0A+@file{emacsclient}=20= org-protocol://store-link?url=3DURL&title=3DTITLE=0A=20@end=20example=0A=20= =0A=20will=20store=20the=20following=20link:=0A--=20=0A2.11.0=20(Apple=20= Git-81)=0A=0A= --Apple-Mail=_93C44B88-8C10-4C7C-A65D-131E9C3E2DBA Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=utf-8 (second patch attached out of consistency reasons) Kind regards Mario =E2=80=94=20 --Apple-Mail=_93C44B88-8C10-4C7C-A65D-131E9C3E2DBA--