Improve documentation

doc/org.texi

@@ -11685,13 +11685,20 @@ The following example counts the number of entries with TODO keyword
 @i{MobileOrg} is an application for the @i{iPhone/iPod Touch} series of
 devices, developed by Richard Moreland.  @i{MobileOrg} offers offline viewing
 and capture support for an Org-mode system rooted on a ``real'' computer.  It
-does also allow you to edit existing entries.
+does also allow you to record changes to existing entries.  For information
+about @i{MobileOrg}, see @uref{http://mobileorg.ncogni.to/}).
 
 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 and changes made by @i{MobileOrg} into the main system.  It does not
-cover the operation of @i{MobileOrg} itself (see
-@uref{http://mobileorg.ncogni.to/}).
+captured and changes made by @i{MobileOrg} into the main system.
+
+For changing tags and TODO states in MobileOrg, you should have set up the
+customization variables @code{org-todo-keywords} and {org-tags-alist} to
+cover all important tags and todo keywords, even if individual files use only
+part of these.  MobileOrg will also offer you states and tags set up with
+in-buffer settings, but it will understand the logistics of todo state
+@i{sets} (@pxref{Per-file keywords}) and @i{mutually exclusive} tags
+(@pxref{Setting tags}) only for those set in these variables.
 
 @menu
 * Setting up the staging area::  Where to interact with the mobile device
@@ -11704,8 +11711,8 @@ cover the operation of @i{MobileOrg} itself (see
 
 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}.
+WebDAV directory accessed by @i{MobileOrg}, just 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
@@ -11713,18 +11720,15 @@ 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
+@smallexample
 (setq org-mobile-directory "~/stage/")
 (add-hook 'org-mobile-post-push-hook
-  (lambda ()
-   (shell-command "scp ~/stage/* user@@webdavhost:mobile/")))
+  (lambda () (shell-command "scp -r ~/stage/* user@@wdhost:mobile/")))
 (add-hook 'org-mobile-pre-pull-hook
-  (lambda ()
-   (shell-command "scp user@@webdavhost:mobile/mobileorg.org ~/stage/ ")))
+  (lambda () (shell-command "scp user@@wdhost:mobile/mobileorg.org ~/stage/ ")))
 (add-hook 'org-mobile-post-pull-hook
-  (lambda ()
-   (shell-command "scp ~/stage/mobileorg.org user@@webdavhost:mobile/")))
-@end example
+  (lambda () (shell-command "scp ~/stage/mobileorg.org user@@wdhost:mobile/")))
+@end smallexample
 
 @node Pushing to MobileOrg, Pulling from MobileOrg, Setting up the staging area, MobileOrg
 @section Pushing to MobileOrg
@@ -11742,7 +11746,7 @@ 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.  To speed up the download, MobileOrg will only read files whose
+device.  To speed up the download, MobileOrg will only read files whose
 checksums@footnote{stored automatically in the file @file{checksums.dat}}
 have changed.
 
@@ -11751,26 +11755,27 @@ have changed.
 
 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{mobileorg.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:
+flagged and changed entries to the file @file{mobileorg.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{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 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.
+@code{org-mobile-inbox-for-pull}.  Each captured entry and each editing event
+will be a top-level entry in the inbox file.
+@item
+After moving the entries, Org will attempt to implement the changes made in
+@i{MobileOrg}.  Some changes are applied directly and without user
+interaction.  Examples are all changes to tags, TODO state, headline and body
+text that can be cleanly applied.  Entries that have been flagged for further
+action will receive a tag @code{:FLAGGED:}, so that they can be easily found
+again.  When there is a problem finding an entry or applying the change, the
+pointer entry will remain in the inbox and will be marked with an error
+message.  You need to later resolve these issues by hand.
 @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.
@@ -11785,7 +11790,8 @@ 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).
+in a property).  In this way you indicate, that the intended processing for
+this flagged entry is finished.
 @end table
 @end enumerate