Document support for MobileOrg

doc/ChangeLog

@@ -1,3 +1,7 @@
+2009-09-15  Carsten Dominik  <carsten.dominik@gmail.com>
+
+	* org.texi (MobileOrg): New section.
+
 2009-08-29  Carsten Dominik  <carsten.dominik@gmail.com>
 
 	* orgcard.tex: Document new effort setting commands.

doc/org.texi

@@ -109,6 +109,7 @@ license to the document, as described in section 6 of the license.
 * Publishing::                  Create a web site of linked Org files
 * 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
 * Main Index::                  An index of Org's concepts and features
 * Key Index::                   Key bindings and where they are described
@@ -420,6 +421,12 @@ Tables and lists in arbitrary syntax
 * Translator functions::        Copy and modify
 * Radio lists::                 Doing the same for lists
 
+MobileOrg
+
+* Setting up the staging area::  Where to interact with the mobile device
+* Pushing to MobileOrg::        Uploading Org files and agendas
+* Pulling from MobileOrg::      Integrating captured and flagged items
+
 @end detailmenu
 @end menu
 
@@ -10690,7 +10697,8 @@ in the paragraph above about CUA mode also applies here.
 
 @end table
 
-@node Hacking, History and Acknowledgments, Miscellaneous, Top
+
+@node Hacking, MobileOrg, Miscellaneous, Top
 @appendix Hacking
 @cindex hacking
 
@@ -11456,19 +11464,6 @@ foreach $line (split(/\n/,$agenda)) @{
 @}
 @end example
 
-
-
-
-
-
-
-
-
-
-
-
-
-
 @node Using the property API, Using the mapping API, Extracting agenda information, Hacking
 @section Using the property API
 @cindex API, for properties
@@ -11648,7 +11643,124 @@ The following example counts the number of entries with TODO keyword
 (length (org-map-entries t "/+WAITING" 'agenda))
 @end lisp
 
-@node History and Acknowledgments, Main Index, Hacking, Top
+@node MobileOrg, History and Acknowledgments, Hacking, Top
+@appendix MobileOrg
+@cindex iPhone
+@cindex MobileOrg
+
+@i{MobileOrg} is an application for the @i{iPhone/iPod Touch} series of
+devices, developed by Richard Moreland.  Instead of trying to implement the
+full feature set of Org and fighting with synchronization issues, this
+application chooses a different path.  @i{MobileOrg} provides offline viewing
+and capture support for an Org-mode system rooted on a ``real'' computer.
+Synchronization issues are avoided by making @i{MobileOrg} only @i{write} to
+a special capture file, that is only @i{read} by the computer-based system.
+
+This appendix describes the support Org has for creating agenda views in a
+format that can be displayed by @i{MobileOrg}, and for integrating notes
+captured by @i{MobileOrg} into the main system.  It does not cover the
+operation of @i{MobileOrg} itself (see @uref{http://ncogni.to/mobileorg/}).
+
+@menu
+* Setting up the staging area::  Where to interact with 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, Pushing to MobileOrg, MobileOrg, MobileOrg
+@section Setting up the staging area
+
+Org-mode has commands to prepare a directory with files for @i{MobileOrg}, and to
+read captured notes from there.  If Emacs can directly write to the WebDAV
+directory accessed by @i{MobileOrg}, all you need to do is to point to this
+directory using the variable @code{org-mobile-directory}.
+
+If Emacs cannot access the WebDAV directory directly, you can use a local
+directory for staging.  Other means must then be used to keep this directory
+in sync with the WebDAV directory.  In the following example, files are
+staged in @file{~/stage}, and Org-mode hooks take care of moving files to and
+from the WebDAV directory using @file{scp}.
+
+@example
+(setq org-mobile-directory "~/MobileOrg/stage/")
+(add-hook 'org-mobile-post-push-hook
+  (lambda ()
+   (shell-command "scp ~/stage/* user@@webdavhost:mobile/")))
+(add-hook 'org-mobile-pre-pull-hook
+  (lambda ()
+   (shell-command "scp user@@webdavhost:mobile/mobile-capture.org ~/stage/ ")))
+(add-hook 'org-mobile-post-pull-hook
+  (lambda ()
+   (shell-command "scp ~/stage/mobile-capture.org user@@webdavhost:mobile/")))
+@end example
+
+@node Pushing to MobileOrg, Pulling from MobileOrg, Setting up the staging area, MobileOrg
+@section Pushing to MobileOrg
+
+
+This operation copies all files currently listed in @code{org-agenda-files}
+to the directory @code{org-mobile-directory}.  It also creates (in the same
+directory) a special Org file @file{agendas.org}.  This file is an Org-mode
+style outline, containing every custom agenda view defined by the user.
+While creating the agendas, Org-mode will force@footnote{See the variable
+@code{org-mobile-force-id-on-agenda-items}.} an ID property on all entries
+referenced by the agendas, so that these entries can be uniquely identified
+if @i{MobileOrg} flags them for further action.  Finally, Org writes the file
+@file{index.org}, containing links to all other files.  If @i{MobileOrg} is
+configured to request this file from the WebDAV server, all agendas and Org
+files will be downloaded to the iPhone.
+
+@node Pulling from MobileOrg,  , Pushing to MobileOrg, MobileOrg
+@section Pulling from MobileOrg
+
+When @i{MobileOrg} synchronizes with the WebDAV server, it not only pulls the
+Org files for viewing.  It also appends captured entries and pointers to
+flagged entries to the file @file{mobile-capture.org} on the server.  Org has
+a @emph{pull} operation that integrates this information into an inbox file
+and operates on the pointers to flagged entries.  Here is how it works:
+
+@enumerate
+@item
+Org moves all entries found in @file{mobile-capture.org} and appends them to
+the file pointed to by the variable @code{org-mobile-inbox-for-pull}.  Each
+captured entry will be a top-level entry in the inbox file.
+@item
+After moving the entries, Org will attempt to act on the flags.  Some flags
+specify simple operations that will be executed directly and without user
+interaction.  Examples are marking an entry as DONE and/or archiving
+it@footnote{as specified by the variable @code{org-archive-default-action}}.
+All other flagged entries will receive a tag @code{:FLAGGED:}, so that they
+can be easily found again.  When there is a problem finding the entry that
+should be flagged, the pointer entry will remain in the inbox and will be
+marked with an error message.
+@item
+Org will then generate an agenda view with all flagged entries.  The user
+should then go through these entries and do whatever actions are necessary.
+If a note has been stored while flagging an entry in @i{MobileOrg}, that note
+will be displayed in the echo area when the cursor is on the corresponding
+agenda line.
+@table @kbd
+@kindex ?
+@item ?
+Pressing @kbd{?} in that special agenda will display the full flagging note in
+another window and also push it onto the kill ring.  So you could use @kbd{?
+z C-y C-c C-c} to store that flagging note as a normal note in the entry.
+Pressing @kbd{?} twice in succession will offer to remove the
+@code{:FLAGGED:} tag along with the recorded flagging note (which is stored
+in a property).
+@end table
+@end enumerate
+
+@kindex C-c a ?
+If you are not able to process all flagged entries directly, you can always
+return to this agenda view using @kbd{C-c a ?}.  Note, however, that there is
+a subtle difference.  The view created automatically by @kbd{M-x
+org-mobile-pull RET} is guaranteed to search all files that have been
+addressed by the last pull.  This might include a file that is not currently
+in your list of agenda files.  If you later use @kbd{C-c a ?} to regenerate
+the view, only the current agenda files will be searched.
+
+@node History and Acknowledgments, Main Index, MobileOrg, Top
 @appendix History and Acknowledgments
 @cindex acknowledgments
 @cindex history
@@ -11775,6 +11887,8 @@ basis.
 @i{Stefan Monnier} provided a patch to keep the Emacs-Lisp compiler
 happy.
 @item
+@i{Richard Moreland} wrote @i{MobileOrg} for the iPhone.
+@item
 @i{Rick Moynihan} proposed allowing multiple TODO sequences in a file
 and being able to quickly restrict the agenda to a subtree.
 @item
@@ -11913,3 +12027,5 @@ org-customize @key{RET}} and then klick yourself through the tree.
 @c fill-column: 77
 @c End:
 
+
+@c  LocalWords:  webdavhost pre