Improve Android documentation

* INSTALL.android: Say where building Emacs is supported.
* doc/emacs/android.texi (Android Startup): Describe how to
connect via ADB.

2 files changed, 39 insertions, 4 deletions

diff --git a/INSTALL.android b/INSTALL.android
index 442bfef6422..24877d88aef 100644
--- a/INSTALL.android
+++ b/INSTALL.android
@@ -14,7 +14,7 @@ Android is an unusual operating system in that program binaries cannot
 be produced on computers running Android themselves.  Instead, they
 must be built on some other computer using a set of tools known as the
 ``Android SDK'' (Software Development Kit) and the ``Android NDK''
-(Native Development Kit).  Appropriate versions of both must be
+(Native Development Kit.)  Appropriate versions of both must be
 obtained to build GNU Emacs; after being built, the generated binaries
 will work on almost all Android devices.  This document does not
 elaborate on how both sets of tools can be obtained.  However, for
@@ -23,6 +23,9 @@ Debian project.
 
 In addition to the Android SDK and Android NDK, Emacs also requires
 the Java compiler from OpenJDK 1.7.0 to be installed on your system.
+Building on GNU systems is all that is officially supported.  We are
+told that Mac OS works too, and other Unix systems will likely work
+as well, but MS Windows and Cygwin will not.
 
 Once all of those tools are obtained, you may invoke the `configure'
 script like so:
diff --git a/doc/emacs/android.texi b/doc/emacs/android.texi
index 4e5402f5f40..4feb3f0c3ef 100644
--- a/doc/emacs/android.texi
+++ b/doc/emacs/android.texi
@@ -72,11 +72,11 @@ application icon is clicked.
 
   During startup, Emacs will display messages in the system log
 buffer; reading that buffer requires the Android Debug Bridge
-(@code{adb}) utility to be installed on another computer; it cannot be
-read on the computer running Android itself.
+(@command{adb}) utility to be installed on another computer; it cannot
+be read on the computer running Android itself.
 
   After enabling the ``USB Debugging'' feature on the Android system,
-and connecting it via USB to another system with the @code{adb}
+and connecting it via USB to another system with the @command{adb}
 utility installed, the log can be viewed by running the following
 command on that other system:
 
@@ -84,6 +84,38 @@ command on that other system:
 $ adb logcat | grep -E "(android_run_debug_thread|[Ee]macs)"
 @end example
 
+  Assuming that the @command{adb} utility is installed on a GNU/Linux
+or Unix system, follow the steps below to connect to your device.
+
+@enumerate
+@item
+Enable ``developer options'' on your device, by going to the ``About''
+page in the system settings application and clicking on the ``build
+version'' or ``kernel version'' items five to seven times.
+
+@item
+Turn on the switch ``USB debugging''.
+
+@item
+Connect one end of a USB cable to your device, and the other end to
+your computer's USB port.
+
+@item
+Run the command @command{adb shell} on your computer.  This will fail
+or hang because you have not yet granted your computer permission to
+access the connected device.
+
+@item
+Confirm the pop-up displayed on your device asking whether or not it
+should allow access from your computer.
+@end enumerate
+
+  Depending on the versions of Android and @command{adb} installed,
+there may be other ways to establish a connection.  See the official
+documentation at
+@url{https://developer.android.com/studio/command-line/adb} for more
+details.
+
 @cindex emacsclient wrapper, android
   Since there is no other way to start the @command{emacsclient}
 program (@pxref{Emacs Server}) from another Android program, Emacs