Re: org-protocol documentation

[Nicolas Goaziou <mail@nicolasgoaziou.fr>]

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