Re: [O] org-protocol documentation

[Nicolas Goaziou]

Mario Martelli <address@hidden> writes:

>> 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’s more than we have at the moment :)

That is true.

> I’m not happy with that there is so much information - although
> outdated - in the old Worg documentation which might be hidden to the
> reader.

Note that

> +Org protocol comes with three predefined handlers:
> address@hidden @asis
> address@hidden @code{org-protocol-store-link}
> +     Triggered through the sub-protocol @code{store-link}.  Store a
> +link and push the URL to the kill-ring.
> address@hidden @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}.
> address@hidden @code{org-protocol-open-source}
> +     @code{open-source}.  Map a URL to local filename.  Use this to open
> +sources of already published contents in Emacs for editing.

You probably missed my remark about this part. I think each sub-protocol
should be introduced in a similar way.

> address@hidden table
> +
> address@hidden Setting up Org protocol
> address@hidden Setting up Org protocol

This is the trick part. We need to feed the index. For example, we could
add the following right below the @subsection line

    @cindex Org protocol, set-up
    @cindex Installing Org protocol

Feel free to adapt.

> +You need to set up a custom URL handler on your system to trigger Emacs by a
> +URL.  This URL handler could be already installed by Emacs.  Please consult 
> the
> +handbook of your operating system how to install a custom URL handler if you
> +need to.
> +
> +To map a website with @code{open-source} to local files you have to set up
> +the mapping in @code{org-protocol-project-alist}.

Just above this paragraph, you need

  @vindex org-protocol-project-alist

> +For example, in order to open files published on Worg locally, you can set
> address@hidden to the following
> +
> address@hidden
> +(setq org-protocol-project-alist
> +      '(("Worg"
> +      :base-url "http://orgmode.org/worg/";
> +      :working-directory "/home/user/worg/"
> +      :online-suffix ".html"
> +      :working-suffix ".org")))
> address@hidden lisp
> +
> +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.

Just above this paragraph, we need

  @findex org-protocol-project-alist
  @findex org-protocol-create

Though, I'm puzzled, `org-publish-project-alist' is a variable, not a function.

> address@hidden Using Org protocol
> address@hidden Using Org protocol

See above about the @cindex:

  @cindex Org protocol, usage
  ...

> +Org protocol is triggered by @file{emacsclient}. If you want to use Org
                                                  ^^^
                                                 Gotcha
                                                 
> +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

> address@hidden @asis
> address@hidden @code{org-store-link}
> +      store a link, insertable through @kbd{M-x org-insert-link} and

 -> Store
 
> Subject: [PATCH 2/2] org.texi: Fixes missing space after dot.
>
> * org.texi Minor change regarding missing space

Good catch. Applied. Thank you.

Regards,