From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mario Martelli Subject: Re: org-protocol documentation Date: Sat, 1 Jul 2017 15:13: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> Mime-Version: 1.0 (Mac OS X Mail 10.3 \(3273\)) Content-Type: multipart/mixed; boundary="Apple-Mail=_A995F283-7887-4EF4-BADF-C24C7E7E4F18" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:46571) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dRIDj-0003cv-9k for emacs-orgmode@gnu.org; Sat, 01 Jul 2017 09:13:56 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dRIDg-00089P-6Y for emacs-orgmode@gnu.org; Sat, 01 Jul 2017 09:13:55 -0400 Received: from mail-wr0-x22f.google.com ([2a00:1450:400c:c0c::22f]:34229) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1dRIDf-00088F-Q5 for emacs-orgmode@gnu.org; Sat, 01 Jul 2017 09:13:52 -0400 Received: by mail-wr0-x22f.google.com with SMTP id 77so215341639wrb.1 for ; Sat, 01 Jul 2017 06:13:50 -0700 (PDT) In-Reply-To: <878tk84fab.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=_A995F283-7887-4EF4-BADF-C24C7E7E4F18 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=utf-8 Hi, >> Any comments? >=20 > Always ;) :-) > Are there really two functions? You only > document one. Hope it=E2=80=99s clearer now. > Genuine question: is this documentation actually complete enough to = use > the feature? I suppose so, if one knows how to configure URL handlers on their OS. Of = course there are some things missing from the documentation. But it=E2=80=99= s more than we have at the moment :) 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 Anyway, I hope I=E2=80=99ve correctly incorporated all your comments. --Apple-Mail=_A995F283-7887-4EF4-BADF-C24C7E7E4F18 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/2]=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=_A995F283-7887-4EF4-BADF-C24C7E7E4F18 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/2]=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=_A995F283-7887-4EF4-BADF-C24C7E7E4F18 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=utf-8 Kind regards Mario =E2=80=94=20 --Apple-Mail=_A995F283-7887-4EF4-BADF-C24C7E7E4F18--