Merge branch 'maint' of code.orgmode.org:bzg/org-mode into maint
This commit is contained in:
Bastien
commit
1315315465
295
doc/org.texi
295
doc/org.texi
|
|
@ -324,7 +324,6 @@ Jambunathan K, Dan Davison, Thomas Dye, David O'Toole, and Philip Rooke.
|
|||
* Working with source code:: Export, evaluate, and tangle code blocks
|
||||
* Miscellaneous:: All the rest which did not fit elsewhere
|
||||
* Hacking:: How to hack your way around
|
||||
* MobileOrg:: Viewing and capture on a mobile device
|
||||
* History and acknowledgments:: How Org came into being
|
||||
* GNU Free Documentation License:: The license for this documentation.
|
||||
* Main Index:: An index of Org's concepts and features
|
||||
|
|
@ -759,12 +758,19 @@ Miscellaneous
|
|||
* TTY keys:: Using Org on a tty
|
||||
* Interaction:: With other Emacs packages
|
||||
* org-crypt:: Encrypting Org files
|
||||
* Org Mobile:: Viewing and capture on a mobile device
|
||||
|
||||
Interaction with other packages
|
||||
|
||||
* Cooperation:: Packages Org cooperates with
|
||||
* Conflicts:: Packages that lead to conflicts
|
||||
|
||||
Org Mobile
|
||||
|
||||
* Setting up the staging area:: For the mobile device
|
||||
* Pushing to the mobile application:: Uploading Org files and agendas
|
||||
* Pulling from the mobile application:: Integrating captured and flagged items
|
||||
|
||||
Hacking
|
||||
|
||||
* Hooks:: How to reach into Org's internals
|
||||
|
|
@ -787,12 +793,6 @@ Tables and lists in arbitrary syntax
|
|||
* Translator functions:: Copy and modify
|
||||
* Radio lists:: Sending and receiving lists
|
||||
|
||||
MobileOrg
|
||||
|
||||
* Setting up the staging area:: For the mobile device
|
||||
* Pushing to MobileOrg:: Uploading Org files and agendas
|
||||
* Pulling from MobileOrg:: Integrating captured and flagged items
|
||||
|
||||
@end detailmenu
|
||||
@end menu
|
||||
|
||||
|
|
@ -17256,6 +17256,7 @@ emacs -Q --batch --eval "
|
|||
* TTY keys:: Using Org on a tty
|
||||
* Interaction:: With other Emacs packages
|
||||
* org-crypt:: Encrypting Org files
|
||||
* Org Mobile:: Viewing and capture on a mobile device
|
||||
@end menu
|
||||
|
||||
|
||||
|
|
@ -18190,6 +18191,150 @@ Suggested Org crypt settings in Emacs init file:
|
|||
Excluding the crypt tag from inheritance prevents encrypting previously
|
||||
encrypted text.
|
||||
|
||||
@node Org Mobile
|
||||
@section Org Mobile
|
||||
|
||||
@cindex smartphone
|
||||
|
||||
Org Mobile is a protocol for synchronizing Org files between Emacs and
|
||||
other applications, e.g., on mobile devices. It enables offline-views
|
||||
and capture support for an Org mode system that is rooted on a ``real''
|
||||
computer. The external application can also record changes to
|
||||
existing entries.
|
||||
|
||||
This appendix describes Org's support for agenda view formats
|
||||
compatible with Org Mobile. It also describes synchronizing changes,
|
||||
such as to notes, between the mobile application and the computer.
|
||||
|
||||
To change tags and TODO states in the mobile application, first
|
||||
customize the variables @code{org-todo-keywords} and @code{org-tag-alist}.
|
||||
These should cover all the important tags and TODO keywords, even if
|
||||
Org files use only some of them. Though the mobile application is
|
||||
expected to support in-buffer settings, it is required to understand
|
||||
TODO states @emph{sets} (see @ref{Per-file keywords}) and
|
||||
@emph{mutually exclusive} tags (see @ref{Setting tags}) only for those set in
|
||||
these variables.
|
||||
|
||||
@menu
|
||||
* Setting up the staging area:: For the mobile device
|
||||
* Pushing to the mobile application:: Uploading Org files and agendas
|
||||
* Pulling from the mobile application:: Integrating captured and flagged items
|
||||
@end menu
|
||||
|
||||
@node Setting up the staging area
|
||||
@subsection Setting up the staging area
|
||||
|
||||
@vindex org-mobile-directory
|
||||
The mobile application needs access to a file directory on
|
||||
a server@footnote{For a server to host files, consider using a WebDAV server,
|
||||
such as @uref{https://nextcloud.com, Nextcloud}. Additional help is at this @uref{https://orgmode.org/worg/org-faq.html#mobileorg_webdav, FAQ entry}.} to interact with Emacs. Pass its location through
|
||||
the @code{org-mobile-directory} variable. If you can mount that directory
|
||||
locally just set the variable to point to that directory:
|
||||
|
||||
@lisp
|
||||
(setq org-mobile-directory "~/orgmobile/")
|
||||
@end lisp
|
||||
|
||||
@noindent
|
||||
Alternatively, by using TRAMP (see @ref{Top,TRAMP User Manual,,tramp,}),
|
||||
@code{org-mobile-directory} may point to a remote directory accessible
|
||||
through, for example, SSH and SCP:
|
||||
|
||||
@lisp
|
||||
(setq org-mobile-directory "/scpc:user@@remote.host:org/webdav/")
|
||||
@end lisp
|
||||
|
||||
@vindex org-mobile-encryption
|
||||
With a public server, consider encrypting the files. Org also
|
||||
requires OpenSSL installed on the local computer. To turn on
|
||||
encryption, set the same password in the mobile application and in
|
||||
Emacs. Set the password in the variable
|
||||
@code{org-mobile-use-encryption}@footnote{If Emacs is configured for safe storing of passwords, then
|
||||
configure the variable @code{org-mobile-encryption-password}; please read
|
||||
the docstring of that variable.}. Note that even after the mobile
|
||||
application encrypts the file contents, the file name remains visible
|
||||
on the file systems of the local computer, the server, and the mobile
|
||||
device.
|
||||
|
||||
@node Pushing to the mobile application
|
||||
@subsection Pushing to the mobile application
|
||||
|
||||
@findex org-mobile-push
|
||||
@vindex org-mobile-files
|
||||
The command @code{org-mobile-push} copies files listed in
|
||||
@code{org-mobile-files} into the staging area. Files include agenda files
|
||||
(as listed in @code{org-agenda-files}). Customize @code{org-mobile-files} to
|
||||
add other files. File names are staged with paths relative to
|
||||
@code{org-directory}, so all files should be inside this directory@footnote{Symbolic links in @code{org-directory} need to have the same name
|
||||
as their targets.}.
|
||||
|
||||
Push creates a special Org file @samp{agendas.org} with custom agenda views
|
||||
defined by the user@footnote{While creating the agendas, Org mode forces ID properties on
|
||||
all referenced entries, so that these entries can be uniquely
|
||||
identified if Org Mobile flags them for further action. To avoid
|
||||
setting properties configure the variable
|
||||
@code{org-mobile-force-id-on-agenda-items} to @code{nil}. Org mode then relies
|
||||
on outline paths, assuming they are unique.}.
|
||||
|
||||
Finally, Org writes the file @samp{index.org}, containing links to other
|
||||
files. The mobile application reads this file first from the server
|
||||
to determine what other files to download for agendas. For faster
|
||||
downloads, it is expected to only read files whose checksums@footnote{Checksums are stored automatically in the file
|
||||
@samp{checksums.dat}.}
|
||||
have changed.
|
||||
|
||||
@node Pulling from the mobile application
|
||||
@subsection Pulling from the mobile application
|
||||
|
||||
@findex org-mobile-pull
|
||||
The command @code{org-mobile-pull} synchronizes changes with the server.
|
||||
More specifically, it first pulls the Org files for viewing. It then
|
||||
appends captured entries and pointers to flagged or changed entries to
|
||||
the file @samp{mobileorg.org} on the server. Org ultimately integrates its
|
||||
data in an inbox file format, through the following steps:
|
||||
|
||||
@enumerate
|
||||
@item
|
||||
@vindex org-mobile-inbox-for-pull
|
||||
Org moves all entries found in @samp{mobileorg.org}@footnote{The file will be empty after this operation.} and appends
|
||||
them to the file pointed to by the variable
|
||||
@code{org-mobile-inbox-for-pull}. It should reside neither in the
|
||||
staging area nor on the server. Each captured entry and each
|
||||
editing event is a top-level entry in the inbox file.
|
||||
|
||||
@item
|
||||
@cindex @samp{FLAGGED}, tag
|
||||
After moving the entries, Org processes changes to the shared
|
||||
files. Some of them are applied directly and without user
|
||||
interaction. Examples include changes to tags, TODO state,
|
||||
headline and body text. Entries requiring further action are
|
||||
tagged as @samp{FLAGGED}. Org marks entries with problems with an error
|
||||
message in the inbox. They have to be resolved manually.
|
||||
|
||||
@item
|
||||
Org generates an agenda view for flagged entries for user
|
||||
intervention to clean up. For notes stored in flagged entries, Org
|
||||
displays them in the echo area when point is on the corresponding
|
||||
agenda item.
|
||||
|
||||
@table @asis
|
||||
@item @kbd{?}
|
||||
Pressing @kbd{?} displays the entire flagged note in
|
||||
another window. Org also pushes it to the kill ring. To
|
||||
store flagged note as a normal note, use @kbd{? z C-y C-c C-c}. Pressing @kbd{?} twice does these things: first
|
||||
it removes the @samp{FLAGGED} tag; second, it removes the flagged
|
||||
note from the property drawer; third, it signals that manual
|
||||
editing of the flagged entry is now finished.
|
||||
@end table
|
||||
@end enumerate
|
||||
|
||||
@kindex ? @r{(Agenda dispatcher)}
|
||||
From the agenda dispatcher, @kbd{?} returns to the view to finish
|
||||
processing flagged entries. Note that these entries may not be the
|
||||
most recent since the mobile application searches files that were last
|
||||
pulled. To get an updated agenda view with changes since the last
|
||||
pull, pull again.
|
||||
|
||||
@node Hacking
|
||||
@appendix Hacking
|
||||
@cindex hacking
|
||||
|
|
@ -18850,7 +18995,7 @@ Do not dim blocked tasks:
|
|||
@vindex org-agenda-inhibit-startup
|
||||
Stop preparing agenda buffers on startup:
|
||||
@lisp
|
||||
(setq org-agenda-inhibit-startup nil)
|
||||
(setq org-agenda-inhibit-startup t)
|
||||
@end lisp
|
||||
@item
|
||||
@vindex org-agenda-show-inherited-tags
|
||||
|
|
@ -19154,140 +19299,6 @@ The following example counts the number of entries with TODO keyword
|
|||
(length (org-map-entries t "/+WAITING" 'agenda))
|
||||
@end lisp
|
||||
|
||||
@node MobileOrg
|
||||
@appendix MobileOrg
|
||||
@cindex iPhone
|
||||
@cindex MobileOrg
|
||||
|
||||
MobileOrg is a companion mobile app that runs on iOS and Android devices.
|
||||
MobileOrg enables offline-views and capture support for an Org mode system
|
||||
that is rooted on a ``real'' computer. MobileOrg can record changes to
|
||||
existing entries.
|
||||
|
||||
The @uref{https://github.com/MobileOrg/, iOS implementation} for the
|
||||
@emph{iPhone/iPod Touch/iPad} series of devices, was started by Richard
|
||||
Moreland and is now in the hands Sean Escriva. Android users should check
|
||||
out @uref{http://wiki.github.com/matburt/mobileorg-android/, MobileOrg
|
||||
Android} by Matt Jones. Though the two implementations are not identical,
|
||||
they offer similar features.
|
||||
|
||||
This appendix describes Org's support for agenda view formats compatible with
|
||||
MobileOrg. It also describes synchronizing changes, such as to notes,
|
||||
between MobileOrg and the computer.
|
||||
|
||||
To change tags and TODO states in MobileOrg, first customize the variables
|
||||
@code{org-todo-keywords} and @code{org-tag-alist}. These should cover all
|
||||
the important tags and TODO keywords, even if Org files use only some of
|
||||
them. Though MobileOrg has in-buffer settings, it understands TODO states
|
||||
@emph{sets} (@pxref{Per-file keywords}) and @emph{mutually exclusive} tags
|
||||
(@pxref{Setting tags}) only for those set in these variables.
|
||||
|
||||
@menu
|
||||
* Setting up the staging area:: For the mobile device
|
||||
* Pushing to MobileOrg:: Uploading Org files and agendas
|
||||
* Pulling from MobileOrg:: Integrating captured and flagged items
|
||||
@end menu
|
||||
|
||||
@node Setting up the staging area
|
||||
@section Setting up the staging area
|
||||
|
||||
MobileOrg needs access to a file directory on a server to interact with
|
||||
Emacs. With a public server, consider encrypting the files. MobileOrg
|
||||
version 1.5 supports encryption for the iPhone. Org also requires
|
||||
@file{openssl} installed on the local computer. To turn on encryption, set
|
||||
the same password in MobileOrg and in Emacs. Set the password in the
|
||||
variable @code{org-mobile-use-encryption}@footnote{If Emacs is configured for
|
||||
safe storing of passwords, then configure the variable,
|
||||
@code{org-mobile-encryption-password}; please read the docstring of that
|
||||
variable.}. Note that even after MobileOrg encrypts the file contents, the
|
||||
file names will remain visible on the file systems of the local computer, the
|
||||
server, and the mobile device.
|
||||
|
||||
For a server to host files, consider options like
|
||||
@uref{http://dropbox.com,Dropbox.com} account@footnote{An alternative is to
|
||||
use webdav server. MobileOrg documentation has details of webdav server
|
||||
configuration. Additional help is at
|
||||
@uref{https://orgmode.org/worg/org-faq.html#mobileorg_webdav, FAQ entry}.}.
|
||||
On first connection, MobileOrg creates a directory @file{MobileOrg/} on
|
||||
Dropbox. Pass its location to Emacs through an init file variable as
|
||||
follows:
|
||||
|
||||
@lisp
|
||||
(setq org-mobile-directory "~/Dropbox/MobileOrg")
|
||||
@end lisp
|
||||
|
||||
Org copies files to the above directory for MobileOrg. Org also uses the
|
||||
same directory for sharing notes between Org and MobileOrg.
|
||||
|
||||
@node Pushing to MobileOrg
|
||||
@section Pushing to MobileOrg
|
||||
|
||||
Org pushes files listed in @code{org-mobile-files} to
|
||||
@code{org-mobile-directory}. Files include agenda files (as listed in
|
||||
@code{org-agenda-files}). Customize @code{org-mobile-files} to add other
|
||||
files. File names will be staged with paths relative to
|
||||
@code{org-directory}, so all files should be inside this
|
||||
directory@footnote{Symbolic links in @code{org-directory} should have the
|
||||
same name as their targets.}.
|
||||
|
||||
Push creates a special Org file @file{agendas.org} with custom agenda views
|
||||
defined by the user@footnote{While creating the agendas, Org mode will force
|
||||
ID properties on all referenced entries, so that these entries can be
|
||||
uniquely identified if MobileOrg flags them for further action. To avoid
|
||||
setting properties configure the variable
|
||||
@code{org-mobile-force-id-on-agenda-items} to @code{nil}. Org mode will then
|
||||
rely on outline paths, assuming they are unique.}.
|
||||
|
||||
Org writes the file @file{index.org}, containing links to other files.
|
||||
MobileOrg reads this file first from the server to determine what other files
|
||||
to download for agendas. For faster downloads, MobileOrg will read only
|
||||
those files whose checksums@footnote{Checksums are stored automatically in
|
||||
the file @file{checksums.dat}.} have changed.
|
||||
|
||||
@node Pulling from MobileOrg
|
||||
@section Pulling from MobileOrg
|
||||
|
||||
When MobileOrg synchronizes with the server, it pulls the Org files for
|
||||
viewing. It then appends to the file @file{mobileorg.org} on the server the
|
||||
captured entries, pointers to flagged and changed entries. Org integrates
|
||||
its data in an inbox file format.
|
||||
|
||||
@enumerate
|
||||
@item
|
||||
Org moves all entries found in
|
||||
@file{mobileorg.org}@footnote{@file{mobileorg.org} will be empty after this
|
||||
operation.} and appends them to the file pointed to by the variable
|
||||
@code{org-mobile-inbox-for-pull}. Each captured entry and each editing event
|
||||
is a top-level entry in the inbox file.
|
||||
@item
|
||||
After moving the entries, Org attempts changes to MobileOrg. Some changes
|
||||
are applied directly and without user interaction. Examples include changes
|
||||
to tags, TODO state, headline and body text. Entries for further action are
|
||||
tagged as @code{:FLAGGED:}. Org marks entries with problems with an error
|
||||
message in the inbox. They have to be resolved manually.
|
||||
@item
|
||||
Org generates an agenda view for flagged entries for user intervention to
|
||||
clean up. For notes stored in flagged entries, MobileOrg displays them in
|
||||
the echo area when the cursor is on the corresponding agenda item.
|
||||
|
||||
@table @kbd
|
||||
@kindex ?
|
||||
@item ?
|
||||
Pressing @kbd{?} displays the entire flagged note in another window. Org
|
||||
also pushes it to the kill ring. To store flagged note as a normal note, use
|
||||
@kbd{? z C-y C-c C-c}. Pressing @kbd{?} twice does these things: first it
|
||||
removes the @code{:FLAGGED:} tag; second, it removes the flagged note from
|
||||
the property drawer; third, it signals that manual editing of the flagged
|
||||
entry is now finished.
|
||||
@end table
|
||||
@end enumerate
|
||||
|
||||
@kindex C-c a ?
|
||||
@kbd{C-c a ?} returns to the agenda view to finish processing flagged
|
||||
entries. Note that these entries may not be the most recent since MobileOrg
|
||||
searches files that were last pulled. To get an updated agenda view with
|
||||
changes since the last pull, pull again.
|
||||
|
||||
@node History and acknowledgments
|
||||
@appendix History and acknowledgments
|
||||
@cindex acknowledgments
|
||||
|
|
|
|||
|
|
@ -1227,7 +1227,7 @@ These days get the special face `org-agenda-date-weekend' in the agenda."
|
|||
"Non-nil means jump to today when moving a past date forward in time.
|
||||
When using S-right in the agenda to move a a date forward, and the date
|
||||
stamp currently points to the past, the first key press will move it
|
||||
to today. WHen nil, just move one day forward even if the date stays
|
||||
to today. When nil, just move one day forward even if the date stays
|
||||
in the past."
|
||||
:group 'org-agenda-daily/weekly
|
||||
:version "24.1"
|
||||
|
|
|
|||
Loading…
Reference in New Issue