From e2d0f32e0063555e14524ff5abd0aa529cc9c52b Mon Sep 17 00:00:00 2001 From: Nicolas Goaziou Date: Sat, 29 Sep 2018 16:40:42 +0200 Subject: [PATCH 1/3] Backport commit 6a7a869c3 from Emacs * doc/org.texi (Org Mobile): Rewritten from "MobileOrg" section. Remove all references to non-free software. Moved into "Miscellaneous", much like Org Crypt library. No longer an appendix. (Footnotes): Remove a reference to "MobileOrg". (Bug#32722) Org manual: Rewrite the Org Mobile section 6a7a869c33bb69efd93bb0ce8d8322083dbbcbac Nicolas Goaziou Sun Sep 30 14:40:14 2018 +0300 --- doc/org.texi | 293 ++++++++++++++++++++++++++------------------------- 1 file changed, 152 insertions(+), 141 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 60cc412fd..cf9236bac 100644 --- a/doc/org.texi +++ b/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 @@ -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 From e2f2502757d3593b1d7d683e0d9efb16730eb426 Mon Sep 17 00:00:00 2001 From: Kyle Meyer Date: Sat, 13 Oct 2018 11:55:04 -0400 Subject: [PATCH 2/3] Fix typo in docstring * lisp/org-agenda.el (org-agenda-move-date-from-past-immediately-to-today): Fix typo. --- lisp/org-agenda.el | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lisp/org-agenda.el b/lisp/org-agenda.el index 322480cf2..cabdbeef4 100644 --- a/lisp/org-agenda.el +++ b/lisp/org-agenda.el @@ -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" From 01c419426701aebf2421268b8686e4a0ceb98756 Mon Sep 17 00:00:00 2001 From: Kyle Meyer Date: Sat, 13 Oct 2018 11:55:33 -0400 Subject: [PATCH 3/3] org.texi: Correct suggested value for org-agenda-inhibit-startup * doc/org.texi (Speeding up your agendas): Adjust org-agenda-inhibit-startup snippet to match the text. --- doc/org.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/org.texi b/doc/org.texi index cf9236bac..35fe8e08b 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -18995,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