From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
To: Mario Martelli <tlmtr@schnuddelhuddel.de>
Cc: emacs-orgmode@gnu.org
Subject: Re: org-protocol documentation
Date: Thu, 29 Jun 2017 14:42:40 +0200 [thread overview]
Message-ID: <87lgobrmm7.fsf@nicolasgoaziou.fr> (raw)
In-Reply-To: <FE8CED69-5EB0-4850-B1C3-8991472B9FFE@schnuddelhuddel.de> (Mario Martelli's message of "Sun, 25 Jun 2017 12:15:20 +0200")
Hello,
Mario Martelli <tlmtr@schnuddelhuddel.de> writes:
> Please note, that the documentation assumes that the patches regarding
> “open-source” are applied.
Thank you.
> +You can set up Org for handling protocol calls from outside
> +applications that 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.
There should be a menu here. "ox-texinfo.el" should take care of it
automatically.
> +@node About org-protocolel
> +@section About org-protocol.el
This should be @subsection About ...
But I think this can be merged with the paragraph above and the whole
section "About ..." removed.
> +@samp{org-protocol.el} is based on code and ideas from @uref{./org-annotation-helper.org, org-annotation-helper.el} and
> +@samp{org-browser-url.el}.
I think we can remove the above since the references are not
particularly clear.
> +"@samp{org-protocol:/sub-protocol:/}" triggers actions associated with @samp{sub-protocol}
> +through the custom variable @samp{org-protocol-protocol-alist}.
> +It comes with four predefined handlers:
> +@table @asis
> +@item @samp{org-protocol-store-link}
@code{org-protocol-store-link}
> + triggered through the sub-protocol "@samp{store-link}". Stores an Org-link and
> +pushes the URL to the @samp{kill-ring}.
I think @samp{store-link} is sufficient, i.e., the double quote are
supererogatory.
Also
... the URL to the kill ring.
since we do not refer explicitly here to the kill-ring variable but
rather to the Emacs concept.
Note that Org manual requires two spaces after each sentence. There are
multiple occurrences to fix below.
> +@item @samp{org-protocol-capture}
> + Fill a @samp{CAPTURE} buffer with information gathered somewhere else. This
> +handler is triggered through the "@samp{capture}" sub-protocol and uses the
> +function @samp{org-capture}.
See above about the quotes.
Also,
@code{org-capture}
@code{} is preferred over @samp{} for functions, variables, and
syntactical elements in an Org buffer.
> +@item @samp{org-protocol-remember}
> + Fills a remember buffer with information gathered somewhere else. This
Note that it was "Fill" instead of "Fills" in the previous item. I'd
rather have the former.
> +handler is triggered through the "@samp{remember}" sub-protocol and still
> +available for backward compatibility. This handler uses @samp{org-remember}. Use
> +the current @samp{org-protocol-capture}.
See above.
> +@item @samp{org-protocol-open-source}
> + "@samp{open-source}". Maps URLs to local filenames. Use this to open sources of
> +already published contents in emacs for editing.
> +@end table
emacs -> Emacs.
The first sentence needs to be expounded.
> +@samp{org-protocol} helps creating custom handlers @uref{../org-tutorials/org-protocol-custom-handler.org, (tutorial)} and so called
We can remove the @uref since it points to a relative path from the
website.
> +@samp{org-protocol-projects}.
> +
> +
> +@@<b>As of Org mode 9.0 a new org-protocol key=value syntax is supported@@<b>
This syntax was removed in Org 8.0. You can delete the whole line.
> +Org-protocol can now handle query-style parameters such as:
It should be Org protocol, like Org mode, not Org-protocol.
> +@example
> +org-protocol://store-link?url=http:%2F%2Flocalhost%2Findex.html&title=The%20title
> +org-protocol://capture?template=x&title=Hello&body=World&url=http:%2F%2Fexample.com
> +@end example
> +
> +Old-style links such as
> +@samp{org-protocol://store-link:/http:%2F%2Flocalhost%2Findex.html/The%20title}
> +continue to be supported.
I wonder if it is useful to document old-style links at all in the
manual. Maybe as a footnote (i.e., @footnote{Old-style links...}) but no
more.
> +If you have defined your own handler functions for
> +@code{org-protocol-protocol-alist}, change them to accept either a property
> +list (for new-style links) or a string (for old-style links). Use
This is very personal, but I don't like parenthesis outside Maths and
Lisp. In a document, they just break the flow of reading, even though
they are meant for side comments. Perhaps the following is better:
If you have defined your own handler functions for
@code{org-protocol-protocol-alist}, change them to accept either
a property list, for new-style links, or a string, for old-style ones.
But, again, should we document old-style links?
> +@code{org-protocol-parse-parameters} to convert old-style links into property
> +lists.
See above.
> +@@<b>As of Org mode release 7.01 @samp{org-protocol-remember} is now by @samp{org-protocol-capture}.@@</b>
See above.
> +If not stated otherwise, you may simply replace each occurrence of
> +@emph{capture} with @emph{remember} throughout this document, if you still want to use
> +remember templates. Use @samp{M-x org-version} to find out about the version you're
> +using.
You can remove references about Remember, which has been superseded by Capture.
> +@anchor{orga3188cf}
You can remove this. "@node ..." are anchors.
> +@node Installation
> +@section Installation
@subsection ...
> +@itemize
> +@item
> +To load org-protocol.el add the following to your @samp{.emacs}:
To load @file{org-protocol.el} ... to your Emacs init file:
> +@example
> +(server-start)
> +(require 'org-protocol)
> +@end example
> +@end itemize
> +
> +@node Browser / system setup
> +@subsection Browser / system setup
@node System setup
@subsection System setup
@cindex System setup, for Org protocol
@cindex System configuration for Org protocol
@cindex whatnot...
(Browser should be taken care of in Applications node).
> +@itemize
> +@item
> +@ref{Linux setup (Gnome)}
> +@item
> +@ref{Linux setup (KDE)}
> +@item
> +@ref{Windows setup}
> +@item
> +@ref{macOS setup}
> +@end itemize
This looks like a menu. This can be removed, as "ox-texinfo.el" already
takes care of it.
The other option is to use @subsubheading instead of @subsubsection and
have the four setup in the same page (the menu is then useless). Your
call.
> +@enumerate
> +@item
> +Linux setup (Gnome)
@subsubsection Linux setup (Gnome)
or
@subsubheading Linux setup (Gnome)
per above.
> +For this to work, you'll need the Gnome-Libraries to be installed.
Is this still necessary?
> +@example
> +gconftool-2 -s /desktop/gnome/url-handlers/org-protocol/command '/usr/local/bin/emacsclient %s' --type String
> +gconftool-2 -s /desktop/gnome/url-handlers/org-protocol/enabled --type Boolean true
> +@end example
Ditto. Could an Org protocol user double-check this?
> +@item
> +Linux setup (KDE)
See above about @subsubsection and @subsubheading.
> +Add a file @samp{org.protocol} to @samp{~/.kde/share/kde4/services/}:
@file{org.protocol} to @file{~/...}:
> +@example
> +# -*- conf -*-
> +[Protocol]
> +protocol=org-protocol
> +exec=/usr/bin/emacsclient '%u'
> +input=none
> +output=none
> +helper=true
> +listing=
> +reading=false
> +writing=false
> +makedir=false
> +deleting=false
> +Icon=emacs
> +Description=A protocol for org-mode
A protocol for Org mode
> +@end example
> +
> +@anchor{org3cb52a6}
You can remove this.
> +@item
> +Windows setup
See above.
> +Windows users may register the "@samp{org-protocol}" once for all by
> adjusting the
See above (quotes).
> +following to their facts, save it as *.reg file and double-click it.
> This
@file{.reg} files
> +worked for me on Windows-XP Professional and the emasc23 from ourcomments.org
> +(@uref{http://ourcomments.org/cgi-bin/emacsw32-dl-latest.pl}). I'm no Windows user
> +though and enhancements are more than welcome on the org-mode mailinglist. The
> +original file is from
> @uref{http://kb.mozillazine.org/Register_protocol}.
Could someone double-check this?
> +@example
> +REGEDIT4
> +
> +[HKEY_CLASSES_ROOT\org-protocol]
> +@@="URL:Org Protocol"
> +"URL Protocol"=""
> +[HKEY_CLASSES_ROOT\org-protocol\shell]
> +[HKEY_CLASSES_ROOT\org-protocol\shell\open]
> +[HKEY_CLASSES_ROOT\org-protocol\shell\open\command]
> +@@="\"C:\\Programme\\Emacs\\emacs\\bin\\emacsclientw.exe\" \"%1\""
> +@end example
> +
> +@item
> +macOS setup
See above.
> +To bridge external calls to emacs you need to install a
> +protocol-handler.
> @uref{https://github.com/aaronbieber/org-protocol-handler/commits/master/Commits%20%C2%B7%20aaronbieber/org-protocol-handler/,
> Aaron Bieber's org-protocol-handler} will work fine.
-> protocol handler.
The URL doesn't respond anymore.
> +If you are using a macOS native Emacs, it is recommended to use the
> +emacsclient bundled with Emacs. Such as
> +@samp{/Applications/Emacs.app/Contents/MacOS/bin/emacsclient} in the case
> +of @uref{https://emacsformacosx.com, Emacs For Mac OS X}.
> +
> +After installing the protocol-handler you should then @ref{Verify the
> installation}. Once verified, you can begin using org-protocol.
you can begin using Org protocol.
> +The @uref{https://bitbucket.org/mituharu/emacs-mac, Emacs Mac Port}
> comes with org-protocol. No installation of a
Ditto.
> +protocol handler is needed with it.
> +@end enumerate
> +
> +@node Applications
> +@subsection Applications
> +@anchor{org91000c6}
You can remove the @anchor{...}.
> +@enumerate
> +@item
> +Firefox
@subsubsection Firefox
or
@subsubheading Firefox
> +If you are using Firefox on macOS, see @ref{macOS setup}.
This is redundant with the link below.
> +Please refer to @uref{http://kb.mozillazine.org/Register_protocol} and use
> +"org-protocol" as protocol.
> +
> +@anchor{org83914ec}
See above.
> +
> +@item
> +Acrobat Reader
Ditto.
> +Adapted from @uref{http://article.gmane.org/gmane.emacs.orgmode/6810}
Not necessary, IMO.
> +You place a javascript file for each menu entry in
> +@samp{~/.adobe/Acrobat/<VERSION>/JavaScripts} on unix-like systems or
> +@samp{c:/Program Files/Adobe/Acrobat <VERSION>/Reader/Javascripts/} on
> +Windows, or wherever your Adobe Reader Installation might look for
> +javascript.
> +
> +The examples given here will place new menu entries in the "Tools"
> +menu, after restarting Adobe Reader.
> +
> +@anchor{org6e6a1d8}
See above.
> +@enumerate
> +@item
> +org-store-link.js
> +
> +@example
> +// from http://article.gmane.org/gmane.emacs.orgmode/6810
> +app.addMenuItem(@{cName:"org-store-link", cParent:"Tools",
> + cExec:"app.launchURL('org-protocol://store-link://' + encodeURIComponent(this.URL) + '/' + encodeURIComponent(this.info.Title));"@});
> +@end example
> +
> +@anchor{orgdd4727b}
> +
> +@item
> +org-capture.js
> +
> +@example
> +// from http://article.gmane.org/gmane.emacs.orgmode/6810
> +app.addMenuItem(@{cName:"org-capture", cParent:"Tools",
> + cExec:"app.launchURL('org-protocol://capture://' + encodeURIComponent(this.URL) + '/' + encodeURIComponent(this.info.Title) + '/');"@});
> +@end example
> +
> +And this one, if you still use remember templates:
> +
> +@anchor{org3949e6c}
> +
> +@item
> +org-remember.js
> +
> +@example
> +// from http://article.gmane.org/gmane.emacs.orgmode/6810
> +app.addMenuItem(@{cName:"org-remember", cParent:"Tools",
> + cExec:"app.launchURL('org-protocol://remember://' + encodeURIComponent(this.URL) + '/' + encodeURIComponent(this.info.Title) + '/');"@});
> +@end example
You can remove this part as Remember is no longer supported.
> +
> +@anchor{org6ef67df}
> +@end enumerate
> +
> +@item
> +Opera
> +
> +If you are using Opera on macOS, see @ref{macOS setup}.
> +
> +Opera setup is described here:
> +@uref{http://www.opera.com/support/kb/view/535/}.
See above.
> +
> +To set up opera for use with org-protocol, follow these steps:
> +
> +@enumerate
> +@item
> +Choose "@emph{Tools}" -> "@emph{Prefences}" from the menu.
> +@item
> +Select the tab "@emph{Advanced}".
> +@item
> +Choose "@emph{Programs}" from the list on the left.
> +@item
> +Now click the button "@emph{Add}" on the very right.
> +@item
> +In the new dialog window, enter "@samp{org-protocol}" as "@emph{Protocol}", choose the
> +radio button "@emph{Open with other application}" and enter the path to
> +emacsclient.
> +@end enumerate
@emph -> @code, everywhere. No quotes. "->" becomes "@arrow".
> +@anchor{orgb32e0fa}
> +
> +@item
> +Safari
> +
> +To use org-protocol add a bookmark to your favorites bar.
Org protocol ... favorite
> +Doing that enables you to trigger the bookmark by a keystroke.
> +
> +Here is the URL to use as "@emph{Location}" for browser bookmarks. Just remove the
> +line breaks, replace "@samp{sub-protocol}" with the real sub-protocol to use and
> +exchange the @samp{x} with the template shortcut of your choice.
> +
> +@example
> +javascript:(function()@{window.location.href='org-protocol://sub-protocol?
> +template=x&url='+encodeURIComponent(window.location.href)+
> +'&title='+encodeURIComponent(document.title)+
> +'&body='+encodeURIComponent(window.getSelection());@})();
> +@end example
> +@end enumerate
> +
> +@node Verify the installation
> +@subsection Verify the installation
> +After your protocol is registered with your browser/OS, these links here
> +should work. Click on them and see if emacs reacts:
> +
> +@html
> +<ul>
> + <li><a href="javascript:storeLink();">Org store-link</a></li>
> + <li><a href="javascript:capture();">Org capture (select some text if you like)</a></li>
> + <li><a href="javascript:remember();">Org remember (select some text please)</a></li>
> +</ul>
> +@end html
> +
> +
> +@anchor{org6223309}
> +@strong{*} Using org-protocol
It should be @subsection Using Org protocol
> +To actually use org-protocol add a bookmark to Firefox or Opera.
> +
> +Here is the URL to use as "@emph{Location}" for browser bookmarks. Just remove the
> +line breaks and replace "@samp{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 @samp{org-protocol.el}. Some
> +of the values will be ignored (e.g. @samp{store-link:/} will use the URL and title
> +only).
Documentation is at the present tense. "are ignored" .. "uses the URL
and"...
> +
> +@anchor{org15dcbb6}
> +
> +@menu
> +* Browser / system setup::
> +* Applications::
> +* Verify the installation::
> +@end menu
This is a correct menu, but it looks out of place. Actually, this is
a bug in "ox-texinfo.el" that I introduced recently and is now fixed.
> +@node Links and bookmarks @samp{org-protocol-store-link}
> +@section Links and bookmarks: @samp{org-protocol-store-link}
Doesn't this belong to "Using Org protocol" section?
> +@samp{org-store-link} stores an Org-link insertable through @samp{M-x org-insert-link} and
> +pushes the URL found onto the @samp{kill-ring} for yanking (@samp{C-y}). The sub-protocol
> +used is "@samp{store-link}":
... an Org link ...
@kbd{M-x org-insert-link} ... @kbd(C-y)
> +@example
> +emacsclient org-protocol://store-link?url=URL&title=TITLE
> +@end example
> +
> +will store this Org-link:
-> store the following link
> +@example
> +[[URL][TITLE]]
> +@end example
> +
> +In addition, @samp{URL} will be pushed on the @samp{kill-ring} for
> yanking ('@samp{C-y}'). You will
In addition, URL is pushed on the kill ring for yanking (@kbd{C-y}).
> +have to encode @samp{URL} and/or @samp{TITLE} if they contain slashes, and probably quote
> +those for the shell.
Encode URL, or TITLE, if they contain slashes. Probable quote those for
the shell, too.
> +To use this feature, add a bookmark with an arbitrary name (e.g.
> +"@emph{Org: store-link}") and enter this as "@samp{Location}":
arbitrary name, e.g., @samp{Org: store-link}, and ...
> +@example
> +javascript:location.href='org-protocol://store-link?url='+encodeURIComponent(location.href)
> +@end example
> +
> +@anchor{org00a295d}
See above.
> +@node Note taking and citations @samp{org-protocol-capture}
> +@section Note taking and citations: @samp{org-protocol-capture}
> +This one is triggered through the sub-protocol "@samp{capture}" and consumes up to
> +four data fields:
> +
> +@example
> +emacsclient org-protocol:/capture?template=TEMPLATE?url=URL?title=TITLE?body=BODY
> +@end example
> +
> +will pop up an @emph{@strong{Capture}} buffer and fill the template with the data
> +submitted.
pops up a @samp{Capture} buffer and fills the template with the data
submitted.
> +To use this feature, add a bookmark with an arbitrary name (e.g.
> +"@emph{Org: capture}") and enter this as "@samp{Location}":
See above.
> +@example
> +javascript:location.href='org-protocol://capture?
> + template=x&url='+encodeURIComponent(window.location.href)+
> + '&title='+encodeURIComponent(document.title)+
> + '&body='+encodeURIComponent(window.getSelection());@})();
> +@end example
> +
> +The result depends on the template used. See @ref{org2eb70b8, , An example capture template}
> +further down.
> +Note, that this one, as opposed to the other two standard handlers, does not
> +mix with more parameters to emacsclient. All parameters but the
> +#'@samp{org-protocol://capture?...}' one will be discarded.
> +
> +@anchor{org7e3d71c}
> +
> +@node Which capture template is used?
> +@subsection Which capture template is used?
> +You don't need to setup a capture template to use @samp{org-protocol-capture},
> +since Org-mode provides a default template for those cases. Newer
> versions
-> Org mode
> +provide an interactive interface for choosing a template. You may provide a
> +template to be used by customizing the variable
> +@samp{org-capture-default-template}
When referring to a variable, you need to add a @vindex VARIABLE-NAME
above.
> @footnote{Before commit @samp{fc49c1ec96b2c789f573ae1ba936b930a8494402}, 3rd Sept. 2010,
> +if a template with the key string "@samp{w}" was defined, this one was chosen by
> +default. This was done to make bookmarks used for @uref{./org-annotation-helper.el, org-annotation-helper} work
> +without changing the template.}.
The footnote can be removed.
> +
> +The problem with this solution would be, that only one template can be used
> +with the fuction. If this approach fit your needs you might omit
> +the @samp{template} parameter in the @ref{org6223309, , example above}.
> +
> +
> +@anchor{org2eb70b8}
Unlike to the previous ones, this anchor may be useful as it is actually
referred to above.
> +@enumerate
> +@item
> +An example capture template
> +
> +@lisp
> +(setq org-capture-templates
> + (quote
> + (("w"
> + "Default template"
> + entry
> + (file+headline "~/org/capture.org" "Notes")
> + "* %^@{Title@}\n\n Source: %u, %c\n\n %i"
> + :empty-lines 1)
> + ;; ... more templates here ...
> + )))
> +@end lisp
> +
> +@table @asis
> +@item "@samp{w}"
> +makes this one the default template used for
> +"@samp{org-protocol://capture://}" URLs.
> +@item @samp{entry}
> +makes it a regular entry with a headline.
> +@item @samp{file+headline}
> +files the note in file "@samp{~/org/capture.org}" as child of
> +the headline "@samp{Notes}"
@file{~/org/capture.org}
Is this true, BTW? I mean, is "~/org/capture.org" really hard-coded?
the headline @samep{Notes}.
> +@item '@samp{%c}'
> +will be replaced by an Org-link pointing to the location of the
> +page you have been visiting when clicking on the link. The page
> +title will be the link's description.
> +@item '@samp{%i}'
> +will be replaced by the selected text in your browser window if
> +any.
> +@end table
> +
> +In addition, you may use the following placeholders in your template:
> +
> +@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaa}
> +@headitem Placeholders
> +@tab Replacement
> +@item @samp{%:link}
> +@tab URL of the web-page
> +@item @samp{%:description}
> +@tab The title of the web-page
> +@item @samp{%:initial}
> +@tab Selected text.
> +@end multitable
> +
> +You may read more about templates and their special escape characters in the
> +@uref{http://orgmode.org/manual/Capture-templates.html#Capture-templates,
> Org-mode manual}.
This can be turned into a regular @ref{Template expansio}.
> +@node Org-protocol-remember
> +@subsection Org-protocol-remember
You can remove the whole node.
> +@node Edit published content @samp{org-protocol-open-source}
> +@section Edit published content: @samp{org-protocol-open-source}
> +This one was designed to help with opening sources for editing when browsing
> +in the first place. @samp{org-protocol-open-source} uses the custom variable
> +@samp{org-protocol-project-alist} to map URLs to (local) filenames.
> +
> +Let's take @uref{http://orgmode.org/worg/} as our example.
> +
> +Our intention is to click a bookmark (or link) to open the source of the
> +published file we are reading in our favourite editor. The bookmark-URL above
> +could be used again. But since @samp{org-protocol-open-source} regards the first
> +field only, this here will do:
> +
> +@example
> +javascript:location.href='org-protocol://open-source://'+encodeURIComponent(location.href)
> +@end example
> +
> +To open files published on Worg locally, @samp{org-protocol-project-alist} should look
> +like this (you may skip the second project):
Then what about removing the second project from the example?
> +@lisp
> +(setq org-protocol-project-alist
> + '(("Worg"
> + :base-url "http://orgmode.org/worg/"
> + :working-directory "/home/user/worg/"
> + :online-suffix ".html"
> + :working-suffix ".org")
> + ("My local Org-notes"
> + :base-url "http://localhost/org/"
> + :working-directory "/home/user/org/"
> + :online-suffix ".php"
> + :working-suffix ".org")))
> +@end lisp
> +
> +If you're now browsing @uref{http://orgmode.org/worg/org-contrib/org-protocol.html}
> +and find a typo or have an idea how to enhance the documentation, simply click
> +the bookmark and start editing.
> +If you are using hugo to publish Org files. The configuration is
> +slightly differnet as you have to name the whole filename of @samp{index.org}.
> +If you clone the repo given in the example below you could you try out the following:
> +@lisp
> +("Hugo based MobileOrg Documentation Site"
> + :base-url "https://mobileorg.github.io/"
> + :working-directory "~/Documents/Github/MobileOrg/mobileorg.github.io/content/"
> + :online-suffix ".html"
> + :working-suffix "index.org")
> +@end lisp
> +
> +For blogs and date-style URI please see @ref{orgc5ad545, , Handle
> rewritten URLs}
The @ref needs to be rewritten to target the @node, not the @anchor.
> +There are two functions to help you fill @samp{org-protocol-project-alist} with
> +valid contents. One possibility is @samp{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 @samp{org-publish-project-alist}, try
> +
> +@example
> +M-x org-protocol-create-for-org RET
> +@end example
> +
> +@anchor{orgc5ad545}
> +
> +@node Handle rewritten URLs
> +@subsection Handle rewritten URLs
> +In some cases, replacing @samp{:base-url} with @samp{:working-directory} and
> +@samp{:online-suffix} with @samp{:working-suffix} will not yield the desired results.
> +
> +Suppose you maintain an online store located at @samp{http://example.com/}. The
> +local sources reside in @samp{/home/user/example/}. While most of the URLs map
> +directly to local file names by stripping URL parameters from the end and
> +replacing the @samp{:base-url} with @samp{:working-diretory} and @samp{:online-suffix} with
> +@samp{:working-suffix}, this might not work for rewritten URLs. It's common
> +practice to serve all products in such a store through one file and rewrite
> +URLs that do not match an existing file on the server.
> +
> +That way, a request to @samp{http://example.com/print/posters-A4.html} might be
> +rewritten on the server to something like
> +@samp{http://example.com/shop/products.php/posters-A4.html.php}, where
> +@samp{/posters-A4-digital.html.php} is the so called path info. Note that the
> +browser will not notice the rewrite.
> +
> +If you now click your @samp{org-protocol://open-source://} bookmark, the handler
> +will probably not find a file named
> +@samp{/home/user/example/print/posters-A4.html.php} and fail.
> +
> +Or, even more simple, assume you're browsing @samp{http://example.com/}. A file
> +named @samp{/home/user/example/.php} is not likely to exist.
> +
> +Since Org-mode commit @samp{69b46e10aab3b2374ecbc1a963ba56e77102a9a4} from 15th
> +Nov. 2009, such an entry in @samp{org-protocol-project-alist} may hold an
> +additional property @samp{:rewrites}. This property is a list of cons cells, each
> +of which maps a regular expression to a path relative to the
> +@samp{:working-directory}.
The archeology stuff can be removed.
> +Now map the URL to the path @samp{/home/user/example/products.php} by adding the
> +@samp{:rewrites} property like this:
> +
> +@lisp
> +(setq org-protocol-project-alist
> + '(("example.com"
> + :base-url "http://example.com/"
> + :working-directory "/home/user/example/"
> + :online-suffix ".php"
> + :working-suffix ".php"
> + :rewrites (("example.com/print/" . "products.php")
> + ("example.com/$" . "index.php"))
> + )))
> +@end lisp
> +
> +Guess what the second @samp{:rewrites} element does. Since @samp{example.com/$} is used as
> +a regular expression, it maps @samp{http://example.com/}, @samp{https://example.com},
> +@samp{http://www.example.com/} and similar to @samp{/home/user/example/index.php}.
> +
> +If you are using date style URLs like @samp{https://cool-blog.com/2017/05/20/cool-post/},
> +the following setup could be useful.
> +
> +@lisp
> +(setq org-protocol-project-alist
> + '(("Icarus based blog"
> + :base-url "https://cool-blog.com/"
> + :working-directory "~/MyBlog/themes/hugo-icarus-theme/exampleSite/content/post/"
> + :online-suffix ".html"
> + :working-suffix ".org" ;; or ".md"
> + :rewrites (("\\(https://cool-blog.com/[0-9]+/[0-9]+/[0-9]+/\\)" . ".org"))
> + )))
> +@end lisp
> +
> +The @samp{:rewrites} are searched as a last resort if and only if no existing file
> +name is matched.
> +
> +@menu
> +* Handle rewritten URLs::
> +@end menu
> +
> +@node Other browsers
> +@section Other browsers
I would remove this section.
> +@node Keybindings for Firefox
> +@subsection Keybindings for Firefox
> +Please note that the URIs used are of the old style before Org
> +9.0. You might want to change them to the new style.
We should do that in the documentation.
> +You can add key bindings for the @samp{org-protocol} commands using the keyconfig
> +Firefox extension.
> +
> +First, install keyconfig from @uref{http://mozilla.dorando.at/keyconfig.xpi}.
> +
> +Open the keyconfig dialog by going to Tools and then Keyconfig.
> +
> +Click the 'Add a new Key' button. Enter "Org store link" as the name.
> +Enter the following in the box with @emph{* CODE *} in it:
@samp{Add a new Key} button. Enter @samp{Org store link} as the name.
... @samp{* CODE *} in it
> +@example
> +var orgProtoString = 'org-protocol://store-link://'+
> + encodeURIComponent(gBrowser.currentURI.spec) + '/' +
> + encodeURIComponent(gBrowser.contentWindow.document.title) + '/' +
> + encodeURIComponent(gBrowser.contentWindow.getSelection());
> +
> +gBrowser.loadURI(orgProtoString);
> +@end example
> +
> +Click OK.
@samp{OK}
> You will then need to bind a key by clicking in the box next to the
> +'Apply' button and pressing whatever key combination you want. Click 'Apply' to
> +store the keybinding.
@samp{Apply}
> +
> +Repeat the steps, but call the next key "Org capture" and use the code below:
> +
> +@example
> +var orgProtoString = 'org-protocol://capture://'+
> + encodeURIComponent(gBrowser.currentURI.spec) + '/' +
> + encodeURIComponent(gBrowser.contentWindow.document.title) + '/' +
> + encodeURIComponent(content.window.getSelection());
> +
> +gBrowser.loadURI(orgProtoString);
> +@end example
> +
> +Click Close, then OK, and then restart Firefox. You should then be able to
> +access the org-protocol functions with your chosen keys.
Org protocol functions
> +
> +@anchor{orgcd7acf4}
> +
> +@menu
> +* Conkeror setup::
> +* Uzbl::
> +* Keybindings for Firefox::
> +@end menu
> +
> +@node Screencast small introduction to org-protocolel
> +@section Screencast: small introduction to org-protocol.el
This section can be removed.
Besides the changes suggested above, we should put some thinking in the
structure, which may be not adapter for a manual. In particular, it
should be made shorter.
Also, index entries are sorely missing for now.
Regards,
--
Nicolas Goaziou
next prev parent reply other threads:[~2017-06-29 12:42 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 [this message]
2017-06-29 18:30 ` Mario Martelli
2017-06-30 12:05 ` Mario Martelli
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=87lgobrmm7.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).