Merge from origin/emacs-26

9c028d6 * lisp/savehist.el (savehist-mode): Doc fix.  (Bug#32889)
3a2b5a7 ; * lisp/bindings.el (bindings--define-key): Doc fix.  (Bug#3...
6a7a869 Org manual: Rewrite the Org Mobile section

# Conflicts:
#	lisp/savehist.el

3 files changed, 176 insertions, 145 deletions

diff --git a/doc/misc/org.texi b/doc/misc/org.texi
index ccb5f88f93d..9ea78f5ace9 100644
--- a/doc/misc/org.texi
+++ b/doc/misc/org.texi
@@ -325,7 +325,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
@@ -760,12 +759,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
@@ -788,12 +794,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
 
@@ -17251,6 +17251,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
 
 
@@ -18185,6 +18186,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
@@ -19149,140 +19294,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
diff --git a/lisp/bindings.el b/lisp/bindings.el
index 9797052725a..76383ad2cef 100644
--- a/lisp/bindings.el
+++ b/lisp/bindings.el
@@ -309,7 +309,10 @@ Normally nil in most modes, since there is no process to display.")
 (make-variable-buffer-local 'mode-line-process)
 
 (defun bindings--define-key (map key item)
-  "Make as much as possible of the menus pure."
+  "Define KEY in keymap MAP according to ITEM from a menu.
+This is like `define-key', but it takes the definition from the
+specified menu item, and makes pure copies of as much as possible
+of the menu's data."
   (declare (indent 2))
   (define-key map key
     (cond
diff --git a/lisp/savehist.el b/lisp/savehist.el
index e555450c209..329929be515 100644
--- a/lisp/savehist.el
+++ b/lisp/savehist.el
@@ -173,9 +173,26 @@ minibuffer history.")
   "Toggle saving of minibuffer history (Savehist mode).
 
 When Savehist mode is enabled, minibuffer history is saved
-periodically and when exiting Emacs.  When Savehist mode is
-enabled for the first time in an Emacs session, it loads the
-previous minibuffer history from `savehist-file'.
+to `savehist-file' periodically and when exiting Emacs.  When
+Savehist mode is enabled for the first time in an Emacs session,
+it loads the previous minibuffer histories from `savehist-file'.
+The variable `savehist-autosave-interval' controls the
+periodicity of saving minibuffer histories.
+
+If `savehist-save-minibuffer-history' is non-nil (the default),
+all recorded minibuffer histories will be saved.  You can arrange
+for additional history variables to be saved and restored by
+customizing `savehist-additional-variables', which by default is
+an empty list.  For example, to save the history of commands
+invoked via \\[execute-extended-command], add `command-history' to the list in
+`savehist-additional-variables'.
+
+Alternatively, you could customize `savehist-save-minibuffer-history'
+to nil, and add to `savehist-additional-variables' only those
+history variables you want to save.
+
+To ignore some history variables, add their symbols to the list
+in `savehist-ignored-variables'.
 
 This mode should normally be turned on from your Emacs init file.
 Calling it at any other time replaces your current minibuffer