Re: [O] org-protocol documentation

[Nicolas Goaziou]

Hello,

Mario Martelli <address@hidden> writes:

> I created a pretty short documentation of org-protocol. It’s still
> mainly copied from the old documentation. But distilled :)

Thank you.

> It might be an idea to link to the old documentation at worg.

I'd rather not do that. Ideally, Org internal documentation should be
self-contained.

> Any comments?

Always ;)

> +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}.  Stores an
> +Org-link and pushes the URL to the kill-ring.

triggered -> Triggered

Stores -> Store

pushes -> push

Org-link -> Org link -> link (since we can assume in an Org manual,
links default to Org link).

> 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}.

This should be consistent with the previous wording, e.g.:

    Triggered through the sub-protocol @code{capture}. Fill
    a @samp{Capture} buffer with ... calling @code{org-capture}
    function.

> address@hidden @code{org-protocol-open-source}
> +     @code{open-source}.  Maps URLs to local filenames.  Use this to open
> +sources of already published contents in Emacs for editing.

See above.

> +To configure handling of @code{open-source} the location of the website and 
> the
> +location of the corresponding source must be configured.  In addition the 
> mapping
> +needs to be defined.

I suggest to rewrite this using a more direct style.

> +To open files published on Worg locally, @code{org-protocol-project-alist}
> +should look like this.

  For example, in order to open files published on Worg locally, you can
  set @code{org-protocol-project-alist} 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
> +
> +There are two functions to help you fill @code{org-protocol-project-alist} 
> with
> +valid contents. One possibility is @code{org-protocol-create} that guides 
> you through

Missing space after dot.  Are there really two functions? You only
document one.

Also, more direct:

  Two functions can help you filling... @code{org-protocol-create}
  guides...

> +the process. If you're editing an Org-mode file that is part of a publishing

Missing space.

Also, 

  Org-mode file -> Org file

> +project in @code{org-publish-project-alist}, try
> +
> address@hidden
> +M-x org-protocol-create-for-org RET
> address@hidden example

  @example
  @kbd{M-x org-protocol-create-for org @key{RET}}
  @end example

But is the example really necessary?

> address@hidden Using Org protocol
> address@hidden Using Org protocol
> +
> +To actually use org-protocol add a bookmark to your browser.

  org-protocol -> Org protocol

Is Org protocol really limited to bookmarks in browsers?

> +Here is the URL to use as @emph{Location} for browser bookmarks.  Just 
> remove the
> +line breaks and replace @code{sub-protocol} with the real sub-protocol to 
> use:
> +
> address@hidden
> +javascript:location.href='org-protocol://sub-protocol?
> +template=x&url='+encodeURIComponent(window.location.href)+
> +'&title='+encodeURIComponent(document.title)+
> +'&body='+encodeURIComponent(window.getSelection());
> address@hidden example
> +
> +This URL may be used for all three standard handlers in
> address@hidden  Some of the values will be ignored,
> +e.g. @code{store-link} will use the URL and title only.

will be ignored -> are ignored

will use -> uses

> address@hidden @asis
> address@hidden @code{org-store-link}
> +      stores an Org-link insertable through @code{M-x org-insert-link} and
> +      pushes the URL found onto the kill-ring for yanking.
> +      The sub-protocol used is @code{store-link}:

  stores an Org-link -> Store a link

  @kbd{M-x org-insert-link}

  pushes -> push

> address@hidden
> +emacsclient org-protocol://store-link?url=URL&title=TITLE
> address@hidden example
> +
> +will store this Org-link:

will store this Org-link > stores the following link

> address@hidden
> +[[URL][TITLE]]
> address@hidden example
> +
> +In addition, @code{URL} will be pushed on the kill-ring for yanking.

In addition, @samp{URL} is pushed...

> +You will have to encode @code{URL} and @code{TITLE} if

You will have to -> You need to (or something equivalent)

@samp{URL} ... @samp{TITLE}

> +they contain slashes, and probably quote those for the shell.
> +
> +To use this feature, add a bookmark with an arbitrary name, e.g.
> address@hidden: store-link} and enter this as @samp{Location}:
> +
> address@hidden
> +javascript:location.href='org-protocol://store-link?
> +           url='+encodeURIComponent(location.href);
> address@hidden example
> +
> address@hidden @code{org-capture}
> +This one is triggered through the sub-protocol @code{capture} and consumes up
> +to four data fields:
> +
> address@hidden
> address@hidden org-protocol:/capture?template=\
> +TEMPLATE?url=URL?title=TITLE?body=BODY
> address@hidden example
> +
> +will pop up a @samp{Capture} buffer and fill the template with the data
> +submitted.

@noindent
pops up a ...

> +To use this feature, add a bookmark with an arbitrary name, e.g.
> address@hidden: capture} and enter this as @code{Location}:

@samp{Location}:

> address@hidden
> +javascript:location.href='org-protocol://
> +template=x&url='+encodeURIComponent(window.location.href)+
> +'&title='+encodeURIComponent(document.title)+
> +'&body='+encodeURIComponent(window.getSelection());
> address@hidden example
> +
> +The result depends on the template used.
> +
> address@hidden table

Genuine question: is this documentation actually complete enough to use
the feature?

Regards,

-- 
Nicolas Goaziou