Hello,
Mario Martelli <tl...@schnuddelhuddel.de> 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:
> +@table @asis
> +@item @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).
> +@item @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.
> +@item @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
> +@lisp
> +(setq org-protocol-project-alist
> + '(("Worg"
> + :base-url "http://orgmode.org/worg/";
> + :working-directory "/home/user/worg/"
> + :online-suffix ".html"
> + :working-suffix ".org")))
> +@end 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
> +
> +@example
> +M-x org-protocol-create-for-org RET
> +@end example
@example
@kbd{M-x org-protocol-create-for org @key{RET}}
@end example
But is the example really necessary?
> +@node Using Org protocol
> +@subsection 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:
> +
> +@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
> +@code{org-protocol.el}. 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
> +@table @asis
> +@item @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
> +@example
> +emacsclient org-protocol://store-link?url=URL&title=TITLE
> +@end example
> +
> +will store this Org-link:
will store this Org-link > stores the following link
> +@example
> +[[URL][TITLE]]
> +@end 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.
> +@samp{Org: store-link} and enter this as @samp{Location}:
> +
> +@example
> +javascript:location.href='org-protocol://store-link?
> + url='+encodeURIComponent(location.href);
> +@end example
> +
> +@item @code{org-capture}
> +This one is triggered through the sub-protocol @code{capture} and consumes up
> +to four data fields:
> +
> +@example
> +@file{emacsclient} org-protocol:/capture?template=\
> +TEMPLATE?url=URL?title=TITLE?body=BODY
> +@end 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.
> +@samp{Org: capture} and enter this as @code{Location}:
@samp{Location}:
> +@example
> +javascript:location.href='org-protocol://
> +template=x&url='+encodeURIComponent(window.location.href)+
> +'&title='+encodeURIComponent(document.title)+
> +'&body='+encodeURIComponent(window.getSelection());
> +@end example
> +
> +The result depends on the template used.
> +
> +@end table
Genuine question: is this documentation actually complete enough to use
the feature?
Regards,
--
Nicolas Goaziou
