diff --git a/doc/org-manual.org b/doc/org-manual.org index 54a25cf2c..56ce736cc 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -19248,6 +19248,134 @@ can operate on the reports with the following keys: | {{{kbd(i)}}} | Also remove them from all subsequent checks | | {{{kbd(S)}}} | Sort reports by the column at point | +** MobileOrg +:PROPERTIES: +:DESCRIPTION: Viewing and capture on a mobile device. +:APPENDIX: Appendix +:END: +#+cindex: iPhone +#+cindex: smartphone +#+cindex: android +#+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 [[https://github.com/MobileOrg/][iOS implementation]] for the /iPhone/iPod Touch/iPad/ series of +devices, was started by Richard Moreland and is now in the hands of +Sean Escriva. Android users should check out [[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 ~org-todo-keywords~ and ~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 /sets/ (see [[*Setting up keywords for individual files]]) and +/mutually exclusive/ tags (see [[*Setting Tags]]) only for those set in +these variables. + +*** Setting Up the Staging Area +:PROPERTIES: +:DESCRIPTION: For the mobile device. +:END: + +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 =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 ~org-mobile-use-encryption~[fn:148]. Note +that even after MobileOrg encrypts the file contents, the file name +remains visible on the file systems of the local computer, the server, +and the mobile device. + +For a server to host files, consider options like [[http://dropbox.com][Dropbox.com]] +account[fn:149]. On first connection, MobileOrg creates a directory +=MobileOrg= on Dropbox. Pass its location to Emacs through an +initialisation file variable as follows: + +#+begin_src emacs-lisp +(setq org-mobile-directory "~/Dropbox/MobileOrg") +#+end_src + +Org copies files to the above directory for MobileOrg. Org also uses +the same directory for sharing notes between Org and MobileOrg. + +*** Pushing to MobileOrg +:PROPERTIES: +:DESCRIPTION: Uploading Org files and agendas. +:END: + +#+vindex: org-mobile-files +#+vindex: org-directory +Org pushes files listed in ~org-mobile-files~ to +~org-mobile-directory~. Files include agenda files (as listed in +~org-agenda-files~). Customize ~org-mobile-files~ to add other files. +File names are staged with paths relative to ~org-directory~, so all +files should be inside this directory[fn:150]. + +Push creates a special Org file =agendas.org= with custom agenda views +defined by the user[fn:151]. + +Finally, Org writes the 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 only reads files whose checksums[fn:152] have changed. + +*** Pulling from MobileOrg +:PROPERTIES: +:DESCRIPTION: Integrating captured and flagged items. +:END: + +When MobileOrg synchronizes with the server, it pulls the Org files +for viewing. It then appends to the file =mobileorg.org= on the +server the captured entries, pointers to flagged and changed entries. +Org integrates its data in an inbox file format. + +1. + #+vindex: org-mobile-inbox-for-pull + Org moves all entries found in =mobileorg.org=[fn:153] and appends + them to the file pointed to by the variable + ~org-mobile-inbox-for-pull~. Each captured entry and each editing + event is a top-level entry in the inbox file. + +2. 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 =FLAGGED=. Org + marks entries with problems with an error message in the inbox. + They have to be resolved manually. + +3. 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 point is on the + corresponding agenda item. + + - {{{kbd(?)}}} :: + #+kindex: ? + + 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 =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. + +#+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 MobileOrg searches files that were last pulled. To +get an updated agenda view with changes since the last pull, pull +again. + * Hacking :PROPERTIES: :DESCRIPTION: How to hack your way around. @@ -20234,134 +20362,6 @@ The following example counts the number of entries with TODO keyword (length (org-map-entries t "/+WAITING" 'agenda)) #+end_src -* MobileOrg -:PROPERTIES: -:DESCRIPTION: Viewing and capture on a mobile device. -:APPENDIX: Appendix -:END: -#+cindex: iPhone -#+cindex: smartphone -#+cindex: android -#+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 [[https://github.com/MobileOrg/][iOS implementation]] for the /iPhone/iPod Touch/iPad/ series of -devices, was started by Richard Moreland and is now in the hands of -Sean Escriva. Android users should check out [[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 ~org-todo-keywords~ and ~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 /sets/ (see [[*Setting up keywords for individual files]]) and -/mutually exclusive/ tags (see [[*Setting Tags]]) only for those set in -these variables. - -** Setting Up the Staging Area -:PROPERTIES: -:DESCRIPTION: For the mobile device. -:END: - -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 =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 ~org-mobile-use-encryption~[fn:148]. Note -that even after MobileOrg encrypts the file contents, the file name -remains visible on the file systems of the local computer, the server, -and the mobile device. - -For a server to host files, consider options like [[http://dropbox.com][Dropbox.com]] -account[fn:149]. On first connection, MobileOrg creates a directory -=MobileOrg= on Dropbox. Pass its location to Emacs through an -initialisation file variable as follows: - -#+begin_src emacs-lisp -(setq org-mobile-directory "~/Dropbox/MobileOrg") -#+end_src - -Org copies files to the above directory for MobileOrg. Org also uses -the same directory for sharing notes between Org and MobileOrg. - -** Pushing to MobileOrg -:PROPERTIES: -:DESCRIPTION: Uploading Org files and agendas. -:END: - -#+vindex: org-mobile-files -#+vindex: org-directory -Org pushes files listed in ~org-mobile-files~ to -~org-mobile-directory~. Files include agenda files (as listed in -~org-agenda-files~). Customize ~org-mobile-files~ to add other files. -File names are staged with paths relative to ~org-directory~, so all -files should be inside this directory[fn:150]. - -Push creates a special Org file =agendas.org= with custom agenda views -defined by the user[fn:151]. - -Finally, Org writes the 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 only reads files whose checksums[fn:152] have changed. - -** Pulling from MobileOrg -:PROPERTIES: -:DESCRIPTION: Integrating captured and flagged items. -:END: - -When MobileOrg synchronizes with the server, it pulls the Org files -for viewing. It then appends to the file =mobileorg.org= on the -server the captured entries, pointers to flagged and changed entries. -Org integrates its data in an inbox file format. - -1. - #+vindex: org-mobile-inbox-for-pull - Org moves all entries found in =mobileorg.org=[fn:153] and appends - them to the file pointed to by the variable - ~org-mobile-inbox-for-pull~. Each captured entry and each editing - event is a top-level entry in the inbox file. - -2. 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 =FLAGGED=. Org - marks entries with problems with an error message in the inbox. - They have to be resolved manually. - -3. 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 point is on the - corresponding agenda item. - - - {{{kbd(?)}}} :: - #+kindex: ? - - 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 =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. - -#+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 MobileOrg searches files that were last pulled. To -get an updated agenda view with changes since the last pull, pull -again. - * History and Acknowledgments :PROPERTIES: :DESCRIPTION: How Org came into being.