Various small changes to the manual
* doc/org-manual.org: Compactify the summary of in-buffer options. Move Org Protocol section to the Miscellaneous chapter.
This commit is contained in:
Carsten Dominik
parent
f8d81f4aaa
commit
16f3fd69c3
|
|
@ -7255,8 +7255,9 @@ An important part of any organization system is the ability to quickly
|
|||
capture new ideas and tasks, and to associate reference material with
|
||||
them. Org does this using a process called /capture/. It also can
|
||||
store files related to a task (/attachments/) in a special directory.
|
||||
Finally, it can parse RSS feeds for information and react to calls
|
||||
from other applications.
|
||||
Finally, it can parse RSS feeds for information. To learn how to let
|
||||
external programs (for example a web browser) trigger Org to capture
|
||||
material, see [[*Protocols for External Access]].
|
||||
|
||||
** Capture
|
||||
:PROPERTIES:
|
||||
|
|
@ -7801,7 +7802,7 @@ named by a unique ID of each entry, or by a =DIR= property.
|
|||
|
||||
*** Attachment defaults and dispatcher
|
||||
:PROPERTIES:
|
||||
:UNNUMBERED: notoc
|
||||
:DESCRIPTION: How to access attachment commands
|
||||
:END:
|
||||
By default, org-attach will use ID properties when adding attachments
|
||||
to outline nodes. This makes working with attachments fully
|
||||
|
|
@ -7920,7 +7921,7 @@ The following commands deal with attachments:
|
|||
|
||||
*** Attachment options
|
||||
:PROPERTIES:
|
||||
:UNNUMBERED: notoc
|
||||
:DESCRIPTION: Configuring the attachment system
|
||||
:END:
|
||||
There are a couple of options for attachments that are worth
|
||||
mentioning.
|
||||
|
|
@ -8011,7 +8012,7 @@ default settings.
|
|||
|
||||
*** Attachment links
|
||||
:PROPERTIES:
|
||||
:UNNUMBERED: notoc
|
||||
:DESCRIPTION: Hyperlink access to attachments
|
||||
:END:
|
||||
Attached files and folders can be referenced using attachment links.
|
||||
This makes it easy to refer to the material added to an outline node.
|
||||
|
|
@ -8029,7 +8030,7 @@ See [[*External Links]] for more information about these links.
|
|||
|
||||
*** Automatic version-control with Git
|
||||
:PROPERTIES:
|
||||
:UNNUMBERED: notoc
|
||||
:DESCRIPTION: Everything safely stored away
|
||||
:END:
|
||||
If the directory attached to an outline node is a Git repository, Org
|
||||
can be configured to automatically commit changes to that repository
|
||||
|
|
@ -8044,7 +8045,7 @@ the following to your Emacs config:
|
|||
|
||||
*** Attach from Dired
|
||||
:PROPERTIES:
|
||||
:UNNUMBERED: notoc
|
||||
:DESCRIPTION: Using dired to select an attachment
|
||||
:END:
|
||||
#+cindex: attach from Dired
|
||||
#+findex: org-attach-dired-to-subtree
|
||||
|
|
@ -8125,197 +8126,6 @@ adding the same item several times.
|
|||
For more information, including how to read atom feeds, see
|
||||
=org-feed.el= and the docstring of ~org-feed-alist~.
|
||||
|
||||
** Protocols for External Access
|
||||
:PROPERTIES:
|
||||
:DESCRIPTION: External access to Emacs and Org.
|
||||
:ALT_TITLE: Protocols
|
||||
:END:
|
||||
#+cindex: protocols, for external access
|
||||
|
||||
Org protocol is a means to trigger custom actions in Emacs from
|
||||
external applications. Any application that supports calling external
|
||||
programs with an URL as argument may be used with this functionality.
|
||||
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 (see [[*Capture]]). You can also create a bookmark that tells
|
||||
Emacs to open the local source file of a remote website you are
|
||||
browsing.
|
||||
|
||||
#+cindex: Org protocol, set-up
|
||||
#+cindex: Installing Org protocol
|
||||
In order to use Org protocol from an application, you need to register
|
||||
=org-protocol://= as a valid scheme-handler. External calls are
|
||||
passed to Emacs through the =emacsclient= command, so you also need to
|
||||
ensure an Emacs server is running. More precisely, when the
|
||||
application calls
|
||||
|
||||
: emacsclient org-protocol://PROTOCOL?key1=val1&key2=val2
|
||||
|
||||
#+texinfo: @noindent
|
||||
Emacs calls the handler associated to {{{var(PROTOCOL)}}} with
|
||||
argument =(:key1 val1 :key2 val2)=.
|
||||
|
||||
#+cindex: protocol, new protocol
|
||||
#+cindex: defining new protocols
|
||||
Org protocol comes with three predefined protocols, detailed in the
|
||||
following sections. Configure ~org-protocol-protocol-alist~ to define
|
||||
your own.
|
||||
|
||||
*** ~store-link~ protocol
|
||||
:PROPERTIES:
|
||||
:DESCRIPTION: Store a link, push URL to kill-ring.
|
||||
:END:
|
||||
#+cindex: store-link protocol
|
||||
#+cindex: protocol, store-link
|
||||
|
||||
Using ~store-link~ handler, you can copy links, insertable through
|
||||
{{{kbd(M-x org-insert-link)}}} or yanking thereafter. More precisely,
|
||||
the command
|
||||
|
||||
: emacsclient org-protocol://store-link?url=URL&title=TITLE
|
||||
|
||||
#+texinfo: @noindent
|
||||
stores the following link:
|
||||
|
||||
: [[URL][TITLE]]
|
||||
|
||||
In addition, {{{var(URL)}}} is pushed on the kill-ring for yanking.
|
||||
You need to encode {{{var(URL)}}} and {{{var(TITLE)}}} if they contain
|
||||
slashes, and probably quote those for the shell.
|
||||
|
||||
To use this feature from a browser, add a bookmark with an arbitrary
|
||||
name, e.g., =Org: store-link= and enter this as /Location/:
|
||||
|
||||
#+begin_example
|
||||
javascript:location.href='org-protocol://store-link?url='+
|
||||
encodeURIComponent(location.href);
|
||||
#+end_example
|
||||
|
||||
*** ~capture~ protocol
|
||||
:PROPERTIES:
|
||||
:DESCRIPTION: Fill a buffer with external information.
|
||||
:END:
|
||||
#+cindex: capture protocol
|
||||
#+cindex: protocol, capture
|
||||
|
||||
Activating "capture" handler pops up a =Capture= buffer and fills the
|
||||
capture template associated to the =X= key with them.
|
||||
|
||||
: emacsclient org-protocol://capture?template=X?url=URL?title=TITLE?body=BODY
|
||||
|
||||
To use this feature, add a bookmark with an arbitrary name, e.g.,
|
||||
=Org: capture=, and enter this as =Location=:
|
||||
|
||||
#+begin_example
|
||||
javascript:location.href='org-protocol://capture?template=x'+
|
||||
'&url='+encodeURIComponent(window.location.href)+
|
||||
'&title='+encodeURIComponent(document.title)+
|
||||
'&body='+encodeURIComponent(window.getSelection());
|
||||
#+end_example
|
||||
|
||||
#+vindex: org-protocol-default-template-key
|
||||
The result depends on the capture template used, which is set in the
|
||||
bookmark itself, as in the example above, or in
|
||||
~org-protocol-default-template-key~.
|
||||
|
||||
The following template placeholders are available:
|
||||
|
||||
#+begin_example
|
||||
%:link The URL
|
||||
%:description The webpage title
|
||||
%:annotation Equivalent to [[%:link][%:description]]
|
||||
%i The selected text
|
||||
#+end_example
|
||||
|
||||
*** ~open-source~ protocol
|
||||
:PROPERTIES:
|
||||
:DESCRIPTION: Edit published contents.
|
||||
:END:
|
||||
#+cindex: open-source protocol
|
||||
#+cindex: protocol, open-source
|
||||
|
||||
The ~open-source~ handler is designed to help with editing local
|
||||
sources when reading a document. To that effect, you can use
|
||||
a bookmark with the following location:
|
||||
|
||||
#+begin_example
|
||||
javascript:location.href='org-protocol://open-source?&url='+
|
||||
encodeURIComponent(location.href)
|
||||
#+end_example
|
||||
|
||||
#+vindex: org-protocol-project-alist
|
||||
The variable ~org-protocol-project-alist~ maps URLs to local file
|
||||
names, by stripping URL parameters from the end and replacing the
|
||||
~:base-url~ with ~:working-directory~ and ~:online-suffix~ with
|
||||
~:working-suffix~. For example, assuming you own a local copy of
|
||||
=https://orgmode.org/worg/= contents at =/home/user/worg=, you can set
|
||||
~org-protocol-project-alist~ to the following
|
||||
|
||||
#+begin_src emacs-lisp
|
||||
(setq org-protocol-project-alist
|
||||
'(("Worg"
|
||||
:base-url "https://orgmode.org/worg/"
|
||||
:working-directory "/home/user/worg/"
|
||||
:online-suffix ".html"
|
||||
:working-suffix ".org")))
|
||||
#+end_src
|
||||
|
||||
#+texinfo: @noindent
|
||||
If you are now browsing
|
||||
=https://orgmode.org/worg/org-contrib/org-protocol.html= and find
|
||||
a typo or have an idea about how to enhance the documentation, simply
|
||||
click the bookmark and start editing.
|
||||
|
||||
#+cindex: rewritten URL in open-source protocol
|
||||
#+cindex: protocol, open-source rewritten URL
|
||||
However, such mapping may not yield the desired results. Suppose you
|
||||
maintain an online store located at =http://example.com/=. The local
|
||||
sources reside in =/home/user/example/=. It is 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 =http://example.com/print/posters.html= might be rewritten on the
|
||||
server to something like
|
||||
=http://example.com/shop/products.php/posters.html.php=. The
|
||||
~open-source~ handler probably cannot find a file named
|
||||
=/home/user/example/print/posters.html.php= and fails.
|
||||
|
||||
Such an entry in ~org-protocol-project-alist~ may hold an additional
|
||||
property ~:rewrites~. This property is a list of cons cells, each of
|
||||
which maps a regular expression to a path relative to the
|
||||
~:working-directory~.
|
||||
|
||||
Now map the URL to the path =/home/user/example/products.php= by
|
||||
adding ~:rewrites~ rules like this:
|
||||
|
||||
#+begin_src emacs-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_src
|
||||
|
||||
#+texinfo: @noindent
|
||||
Since =example.com/$= is used as a regular expression, it maps
|
||||
=http://example.com/=, =https://example.com=,
|
||||
=http://www.example.com/= and similar to
|
||||
=/home/user/example/index.php=.
|
||||
|
||||
The ~:rewrites~ rules are searched as a last resort if and only if no
|
||||
existing file name is matched.
|
||||
|
||||
#+cindex: protocol, open-source, set-up mapping
|
||||
#+cindex: mappings in open-source protocol
|
||||
#+findex: org-protocol-create
|
||||
#+findex: org-protocol-create-for-org
|
||||
Two functions can help you filling ~org-protocol-project-alist~ with
|
||||
valid contents: ~org-protocol-create~ and
|
||||
~org-protocol-create-for-org~. The latter is of use if you're editing
|
||||
an Org file that is part of a publishing project.
|
||||
|
||||
* Agenda Views
|
||||
:PROPERTIES:
|
||||
:DESCRIPTION: Collecting information into views.
|
||||
|
|
@ -18490,14 +18300,12 @@ shortcuts.
|
|||
|
||||
Complete word at point.
|
||||
|
||||
- At the beginning of a headline, complete TODO keywords.
|
||||
- At the beginning of an empty headline, complete TODO keywords.
|
||||
|
||||
- After =\=, complete TeX symbols supported by the exporter.
|
||||
|
||||
- After =*=, complete headlines in the current buffer so that they
|
||||
can be used in search links like:
|
||||
|
||||
: [[*find this headline]]
|
||||
can be used in search links like: =[[*find this headline]]=
|
||||
|
||||
- After =:= in a headline, complete tags. Org deduces the list of
|
||||
tags from the =TAGS= in-buffer option (see [[*Setting Tags]]), the
|
||||
|
|
@ -18909,46 +18717,25 @@ changes.
|
|||
settings is ~org-startup-folded~ with a default value of ~t~, which
|
||||
is the same as ~overview~.
|
||||
|
||||
- =overview= ::
|
||||
|
||||
Top-level headlines only.
|
||||
|
||||
- =content= ::
|
||||
|
||||
All headlines.
|
||||
|
||||
- =showall= ::
|
||||
|
||||
No folding on any entry.
|
||||
|
||||
- =showeverything= ::
|
||||
|
||||
Show even drawer contents.
|
||||
|
||||
| =overview= | Top-level headlines only. |
|
||||
| =content= | All headlines. |
|
||||
| =showall= | No folding on any entry. |
|
||||
| =showeverything= | Show even drawer contents. |
|
||||
|
||||
#+vindex: org-startup-indented
|
||||
Dynamic virtual indentation is controlled by the variable
|
||||
~org-startup-indented~[fn:146].
|
||||
|
||||
- =indent= ::
|
||||
|
||||
Start with ~org-indent-mode~ turned on.
|
||||
|
||||
- =noindent= ::
|
||||
|
||||
Start with ~org-indent-mode~ turned off.
|
||||
|
||||
| =indent= | Start with ~org-indent-mode~ turned on. |
|
||||
| =noindent= | Start with ~org-indent-mode~ turned off. |
|
||||
|
||||
#+vindex: org-startup-align-all-tables
|
||||
Aligns tables consistently upon visiting a file. The
|
||||
corresponding variable is ~org-startup-align-all-tables~ with
|
||||
~nil~ as default value.
|
||||
|
||||
- =align= ::
|
||||
|
||||
Align all tables.
|
||||
|
||||
- =noalign= ::
|
||||
|
||||
Do not align tables on startup.
|
||||
| =align= | Align all tables. |
|
||||
| =noalign= | Do not align tables on startup. |
|
||||
|
||||
#+vindex: org-startup-shrink-all-tables
|
||||
Shrink table columns with a width cookie. The corresponding
|
||||
|
|
@ -18961,13 +18748,8 @@ changes.
|
|||
~org-startup-with-inline-images~, with a default value ~nil~ to
|
||||
avoid delays when visiting a file.
|
||||
|
||||
- =inlineimages= ::
|
||||
|
||||
Show inline images.
|
||||
|
||||
- =noinlineimages= ::
|
||||
|
||||
Do not show inline images on startup.
|
||||
| =inlineimages= | Show inline images. |
|
||||
| =noinlineimages= | Do not show inline images on startup. |
|
||||
|
||||
#+vindex: org-log-done
|
||||
#+vindex: org-log-note-clock-out
|
||||
|
|
@ -18976,73 +18758,23 @@ changes.
|
|||
intervals can be configured using these options (see variables
|
||||
~org-log-done~, ~org-log-note-clock-out~, and ~org-log-repeat~).
|
||||
|
||||
- =logdone= ::
|
||||
|
||||
Record a timestamp when an item is marked as done.
|
||||
|
||||
- =lognotedone= ::
|
||||
|
||||
Record timestamp and a note when DONE.
|
||||
|
||||
- =nologdone= ::
|
||||
|
||||
Do not record when items are marked as done.
|
||||
|
||||
- =logrepeat= ::
|
||||
|
||||
Record a time when reinstating a repeating item.
|
||||
|
||||
- =lognoterepeat= ::
|
||||
|
||||
Record a note when reinstating a repeating item.
|
||||
|
||||
- =nologrepeat= ::
|
||||
|
||||
Do not record when reinstating repeating item.
|
||||
|
||||
- =lognoteclock-out= ::
|
||||
|
||||
Record a note when clocking out.
|
||||
|
||||
- =nolognoteclock-out= ::
|
||||
|
||||
Do not record a note when clocking out.
|
||||
|
||||
- =logreschedule= ::
|
||||
|
||||
Record a timestamp when scheduling time changes.
|
||||
|
||||
- =lognotereschedule= ::
|
||||
|
||||
Record a note when scheduling time changes.
|
||||
|
||||
- =nologreschedule= ::
|
||||
|
||||
Do not record when a scheduling date changes.
|
||||
|
||||
- =logredeadline= ::
|
||||
|
||||
Record a timestamp when deadline changes.
|
||||
|
||||
- =lognoteredeadline= ::
|
||||
|
||||
Record a note when deadline changes.
|
||||
|
||||
- =nologredeadline= ::
|
||||
|
||||
Do not record when a deadline date changes.
|
||||
|
||||
- =logrefile= ::
|
||||
|
||||
Record a timestamp when refiling.
|
||||
|
||||
- =lognoterefile= ::
|
||||
|
||||
Record a note when refiling.
|
||||
|
||||
- =nologrefile= ::
|
||||
|
||||
Do not record when refiling.
|
||||
| =logdone= | Record a timestamp when an item is marked as done. |
|
||||
| =lognotedone= | Record timestamp and a note when DONE. |
|
||||
| =nologdone= | Do not record when items are marked as done. |
|
||||
| =logrepeat= | Record a time when reinstating a repeating item. |
|
||||
| =lognoterepeat= | Record a note when reinstating a repeating item. |
|
||||
| =nologrepeat= | Do not record when reinstating repeating item. |
|
||||
| =lognoteclock-out= | Record a note when clocking out. |
|
||||
| =nolognoteclock-out= | Do not record a note when clocking out. |
|
||||
| =logreschedule= | Record a timestamp when scheduling time changes. |
|
||||
| =lognotereschedule= | Record a note when scheduling time changes. |
|
||||
| =nologreschedule= | Do not record when a scheduling date changes. |
|
||||
| =logredeadline= | Record a timestamp when deadline changes. |
|
||||
| =lognoteredeadline= | Record a note when deadline changes. |
|
||||
| =nologredeadline= | Do not record when a deadline date changes. |
|
||||
| =logrefile= | Record a timestamp when refiling. |
|
||||
| =lognoterefile= | Record a note when refiling. |
|
||||
| =nologrefile= | Do not record when refiling. |
|
||||
|
||||
#+vindex: org-hide-leading-stars
|
||||
#+vindex: org-odd-levels-only
|
||||
|
|
@ -19052,29 +18784,12 @@ changes.
|
|||
~org-odd-levels-only~, both with a default setting ~nil~
|
||||
(meaning =showstars= and =oddeven=).
|
||||
|
||||
- =hidestars= ::
|
||||
|
||||
Make all but one of the stars starting a headline invisible.
|
||||
|
||||
- =showstars= ::
|
||||
|
||||
Show all stars starting a headline.
|
||||
|
||||
- =indent= ::
|
||||
|
||||
Virtual indentation according to outline level.
|
||||
|
||||
- =noindent= ::
|
||||
|
||||
No virtual indentation according to outline level.
|
||||
|
||||
- =odd= ::
|
||||
|
||||
Allow only odd outline levels (1, 3, ...).
|
||||
|
||||
- =oddeven= ::
|
||||
|
||||
Allow all outline levels.
|
||||
| =hidestars= | Make all but one of the stars starting a headline invisible. |
|
||||
| =showstars= | Show all stars starting a headline. |
|
||||
| =indent= | Virtual indentation according to outline level. |
|
||||
| =noindent= | No virtual indentation according to outline level. |
|
||||
| =odd= | Allow only odd outline levels (1, 3, ...). |
|
||||
| =oddeven= | Allow all outline levels. |
|
||||
|
||||
#+vindex: org-put-time-stamp-overlays
|
||||
#+vindex: org-time-stamp-overlay-formats
|
||||
|
|
@ -19082,21 +18797,14 @@ changes.
|
|||
~org-put-time-stamp-overlays~ and
|
||||
~org-time-stamp-overlay-formats~), use:
|
||||
|
||||
- =customtime= ::
|
||||
|
||||
Overlay custom time format.
|
||||
| =customtime= | Overlay custom time format. |
|
||||
|
||||
#+vindex: constants-unit-system
|
||||
The following options influence the table spreadsheet (variable
|
||||
~constants-unit-system~).
|
||||
|
||||
- =constcgs= ::
|
||||
|
||||
=constants.el= should use the c-g-s unit system.
|
||||
|
||||
- =constSI= ::
|
||||
|
||||
=constants.el= should use the SI unit system.
|
||||
| =constcgs= | =constants.el= should use the c-g-s unit system. |
|
||||
| =constSI= | =constants.el= should use the SI unit system. |
|
||||
|
||||
#+vindex: org-footnote-define-inline
|
||||
#+vindex: org-footnote-auto-label
|
||||
|
|
@ -19105,61 +18813,28 @@ changes.
|
|||
corresponding variables are ~org-footnote-define-inline~,
|
||||
~org-footnote-auto-label~, and ~org-footnote-auto-adjust~.
|
||||
|
||||
- =fninline= ::
|
||||
|
||||
Define footnotes inline.
|
||||
|
||||
- =fnnoinline= ::
|
||||
|
||||
Define footnotes in separate section.
|
||||
|
||||
- =fnlocal= ::
|
||||
|
||||
Define footnotes near first reference, but not inline.
|
||||
|
||||
- =fnprompt= ::
|
||||
|
||||
Prompt for footnote labels.
|
||||
|
||||
- =fnauto= ::
|
||||
|
||||
Create =[fn:1]=-like labels automatically (default).
|
||||
|
||||
- =fnconfirm= ::
|
||||
|
||||
Offer automatic label for editing or confirmation.
|
||||
|
||||
- =fnadjust= ::
|
||||
|
||||
Automatically renumber and sort footnotes.
|
||||
|
||||
- =nofnadjust= ::
|
||||
|
||||
Do not renumber and sort automatically.
|
||||
| =fninline= | Define footnotes inline. |
|
||||
| =fnnoinline= | Define footnotes in separate section. |
|
||||
| =fnlocal= | Define footnotes near first reference, but not inline. |
|
||||
| =fnprompt= | Prompt for footnote labels. |
|
||||
| =fnauto= | Create =[fn:1]=-like labels automatically (default). |
|
||||
| =fnconfirm= | Offer automatic label for editing or confirmation. |
|
||||
| =fnadjust= | Automatically renumber and sort footnotes. |
|
||||
| =nofnadjust= | Do not renumber and sort automatically. |
|
||||
|
||||
#+vindex: org-hide-block-startup
|
||||
To hide blocks on startup, use these keywords. The
|
||||
corresponding variable is ~org-hide-block-startup~.
|
||||
|
||||
- =hideblocks= ::
|
||||
|
||||
Hide all begin/end blocks on startup.
|
||||
|
||||
- =nohideblocks= ::
|
||||
|
||||
Do not hide blocks on startup.
|
||||
| =hideblocks= | Hide all begin/end blocks on startup. |
|
||||
| =nohideblocks= | Do not hide blocks on startup. |
|
||||
|
||||
#+vindex: org-pretty-entities
|
||||
The display of entities as UTF-8 characters is governed by the
|
||||
variable ~org-pretty-entities~ and the keywords
|
||||
|
||||
- =entitiespretty= ::
|
||||
|
||||
Show entities as UTF-8 characters where possible.
|
||||
|
||||
- =entitiesplain= ::
|
||||
|
||||
Leave entities plain.
|
||||
| =entitiespretty= | Show entities as UTF-8 characters where possible. |
|
||||
| =entitiesplain= | Leave entities plain. |
|
||||
|
||||
- =#+TAGS: TAG1(c1) TAG2(c2)= ::
|
||||
|
||||
|
|
@ -19588,6 +19263,195 @@ further based on their usage needs. For example, the normal
|
|||
| {{{kbd(C-S-LEFT)}}} | {{{kbd(C-c C-x LEFT)}}} | | |
|
||||
| {{{kbd(C-S-RIGHT)}}} | {{{kbd(C-c C-x RIGHT)}}} | | |
|
||||
|
||||
** Protocols for External Access
|
||||
:PROPERTIES:
|
||||
:DESCRIPTION: External access to Emacs and Org.
|
||||
:ALT_TITLE: Protocols
|
||||
:END:
|
||||
#+cindex: protocols, for external access
|
||||
|
||||
Org protocol is a tool to trigger custom actions in Emacs from
|
||||
external applications. Any application that supports calling external
|
||||
programs with an URL as argument may be used with this functionality.
|
||||
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 (see [[*Capture]]). You can also create a bookmark that tells
|
||||
Emacs to open the local source file of a remote website you are
|
||||
browsing.
|
||||
|
||||
#+cindex: Org protocol, set-up
|
||||
#+cindex: Installing Org protocol
|
||||
In order to use Org protocol from an application, you need to register
|
||||
=org-protocol://= as a valid scheme-handler. External calls are
|
||||
passed to Emacs through the =emacsclient= command, so you also need to
|
||||
ensure an Emacs server is running. More precisely, when the
|
||||
application calls
|
||||
|
||||
: emacsclient org-protocol://PROTOCOL?key1=val1&key2=val2
|
||||
|
||||
#+texinfo: @noindent
|
||||
Emacs calls the handler associated to {{{var(PROTOCOL)}}} with
|
||||
argument =(:key1 val1 :key2 val2)=.
|
||||
|
||||
#+cindex: protocol, new protocol
|
||||
#+cindex: defining new protocols
|
||||
Org protocol comes with three predefined protocols, detailed in the
|
||||
following sections. Configure ~org-protocol-protocol-alist~ to define
|
||||
your own.
|
||||
|
||||
*** The ~store-link~ protocol
|
||||
:PROPERTIES:
|
||||
:DESCRIPTION: Store a link, push URL to kill-ring.
|
||||
:END:
|
||||
#+cindex: store-link protocol
|
||||
#+cindex: protocol, store-link
|
||||
|
||||
Using the ~store-link~ handler, you can copy links, to that they can
|
||||
be inserted using {{{kbd(M-x org-insert-link)}}} or yanking. More
|
||||
precisely, the command
|
||||
|
||||
: emacsclient org-protocol://store-link?url=URL&title=TITLE
|
||||
|
||||
#+texinfo: @noindent
|
||||
stores the following link:
|
||||
|
||||
: [[URL][TITLE]]
|
||||
|
||||
In addition, {{{var(URL)}}} is pushed on the kill-ring for yanking.
|
||||
You need to encode {{{var(URL)}}} and {{{var(TITLE)}}} if they contain
|
||||
slashes, and probably quote those for the shell.
|
||||
|
||||
To use this feature from a browser, add a bookmark with an arbitrary
|
||||
name, e.g., =Org: store-link= and enter this as /Location/:
|
||||
|
||||
#+begin_example
|
||||
javascript:location.href='org-protocol://store-link?url='+
|
||||
encodeURIComponent(location.href);
|
||||
#+end_example
|
||||
|
||||
*** The ~capture~ protocol
|
||||
:PROPERTIES:
|
||||
:DESCRIPTION: Fill a buffer with external information.
|
||||
:END:
|
||||
#+cindex: capture protocol
|
||||
#+cindex: protocol, capture
|
||||
|
||||
Activating the "capture" handler pops up a =Capture= buffer in Emacs,
|
||||
using acapture template.
|
||||
|
||||
: emacsclient org-protocol://capture?template=X?url=URL?title=TITLE?body=BODY
|
||||
|
||||
To use this feature, add a bookmark with an arbitrary name, e.g.,
|
||||
=Org: capture=, and enter this as =Location=:
|
||||
|
||||
#+begin_example
|
||||
javascript:location.href='org-protocol://capture?template=x'+
|
||||
'&url='+encodeURIComponent(window.location.href)+
|
||||
'&title='+encodeURIComponent(document.title)+
|
||||
'&body='+encodeURIComponent(window.getSelection());
|
||||
#+end_example
|
||||
|
||||
#+vindex: org-protocol-default-template-key
|
||||
The capture template to be used can be specified in the bookmark (like
|
||||
=X= above). If unspecified, the template key is set in the variable
|
||||
~org-protocol-default-template-key~. The following template
|
||||
placeholders are available:
|
||||
|
||||
#+begin_example
|
||||
%:link The URL
|
||||
%:description The webpage title
|
||||
%:annotation Equivalent to [[%:link][%:description]]
|
||||
%i The selected text
|
||||
#+end_example
|
||||
|
||||
*** The ~open-source~ protocol
|
||||
:PROPERTIES:
|
||||
:DESCRIPTION: Edit published contents.
|
||||
:END:
|
||||
#+cindex: open-source protocol
|
||||
#+cindex: protocol, open-source
|
||||
|
||||
The ~open-source~ handler is designed to help with editing local
|
||||
sources when reading a document. To that effect, you can use
|
||||
a bookmark with the following location:
|
||||
|
||||
#+begin_example
|
||||
javascript:location.href='org-protocol://open-source?&url='+
|
||||
encodeURIComponent(location.href)
|
||||
#+end_example
|
||||
|
||||
#+vindex: org-protocol-project-alist
|
||||
The variable ~org-protocol-project-alist~ maps URLs to local file
|
||||
names, by stripping URL parameters from the end and replacing the
|
||||
~:base-url~ with ~:working-directory~ and ~:online-suffix~ with
|
||||
~:working-suffix~. For example, assuming you own a local copy of
|
||||
=https://orgmode.org/worg/= contents at =/home/user/worg=, you can set
|
||||
~org-protocol-project-alist~ to the following
|
||||
|
||||
#+begin_src emacs-lisp
|
||||
(setq org-protocol-project-alist
|
||||
'(("Worg"
|
||||
:base-url "https://orgmode.org/worg/"
|
||||
:working-directory "/home/user/worg/"
|
||||
:online-suffix ".html"
|
||||
:working-suffix ".org")))
|
||||
#+end_src
|
||||
|
||||
#+texinfo: @noindent
|
||||
If you are now browsing
|
||||
=https://orgmode.org/worg/org-contrib/org-protocol.html= and find
|
||||
a typo or have an idea about how to enhance the documentation, simply
|
||||
click the bookmark and start editing.
|
||||
|
||||
#+cindex: rewritten URL in open-source protocol
|
||||
#+cindex: protocol, open-source rewritten URL
|
||||
However, such mapping may not always yield the desired results.
|
||||
Suppose you maintain an online store located at =http://example.com/=.
|
||||
The local sources reside in =/home/user/example/=. It is 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 =http://example.com/print/posters.html= might be
|
||||
rewritten on the server to something like
|
||||
=http://example.com/shop/products.php/posters.html.php=. The
|
||||
~open-source~ handler probably cannot find a file named
|
||||
=/home/user/example/print/posters.html.php= and fails.
|
||||
|
||||
Such an entry in ~org-protocol-project-alist~ may hold an additional
|
||||
property ~:rewrites~. This property is a list of cons cells, each of
|
||||
which maps a regular expression to a path relative to the
|
||||
~:working-directory~.
|
||||
|
||||
Now map the URL to the path =/home/user/example/products.php= by
|
||||
adding ~:rewrites~ rules like this:
|
||||
|
||||
#+begin_src emacs-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_src
|
||||
|
||||
#+texinfo: @noindent
|
||||
Since =example.com/$= is used as a regular expression, it maps
|
||||
=http://example.com/=, =https://example.com=,
|
||||
=http://www.example.com/= and similar to
|
||||
=/home/user/example/index.php=.
|
||||
|
||||
The ~:rewrites~ rules are searched as a last resort if and only if no
|
||||
existing file name is matched.
|
||||
|
||||
#+cindex: protocol, open-source, set-up mapping
|
||||
#+cindex: mappings in open-source protocol
|
||||
#+findex: org-protocol-create
|
||||
#+findex: org-protocol-create-for-org
|
||||
Two functions can help you filling ~org-protocol-project-alist~ with
|
||||
valid contents: ~org-protocol-create~ and
|
||||
~org-protocol-create-for-org~. The latter is of use if you're editing
|
||||
an Org file that is part of a publishing project.
|
||||
** Org Crypt
|
||||
:PROPERTIES:
|
||||
:DESCRIPTION: Encrypting Org files.
|
||||
|
|
|
|||
Loading…
Reference in New Issue