doc: fix tools docs formatting and clarity

This continues the editing from PR #276 with formatting and clarity
edits to have these tool documents blend in with the rest of the ACRN
documentation.  It also builds on PR #307 that set up the doc build
infrastructure to allow leaving these tool docs within the tools/
folder.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>

tools/acrn-manager/README.rst

@@ -1,98 +1,100 @@
-``acrnctl``
-===========
+.. _acrnctl:
+
+acrnctl
+#######
 
 
-DESCRIPTION
-___________
+Description
+***********
 
-``acrnctl``: The ``acrnctl`` tool can help user create, delete, launch and stop UOSs.
-It runs under Service OS, and UOSs should be based on ``acrn-dm`` 
+The ``acrnctl`` tool helps users create, delete, launch, and stop a User
+OS (UOS).  The tool runs under the Service OS, and UOSs should be based
+on ``acrn-dm``.
 
 
-USAGE
-_____
 
-To see what it can do, just run:
+Usage
+*****
 
-::
+You can see the available ``acrnctl`` commands by running:
 
-# acrnctl
+.. code-block:: none
 
+   # acrnctl help
+   support:
+     list
+     start
+     stop
+     del
+     add
+   Use acrnctl [cmd] help for details
 
-or
+Here are some usage examples:
 
-::
+Add a VM
+========
 
-# acrnctl help
+The ``add`` command lets you add a VM by specifying a
+script that will launch a UOS, for example ``launch_UOS.sh``:
 
-you may see:
+.. code-block:: none
 
-::
+   # acrnctl add launch_UOS.sh -U 1
+   vm1-14:59:30 added
 
-  support:
-    list
-    start
-    stop
-    del
-    add
-  Use acrnctl [cmd] help for details
+Note that the launch script must only launch one UOS instance.
+The VM name is important. ``acrnctl`` searches VMs by their
+names so duplicate VM names are not allowed. If the
+launch script changes the VM name at launch time, ``acrnctl``
+will not recognize it.
 
-There are examples:
+Delete VMs
+==========
 
-(1) add a VM
-    Each time you can just add one VM. Suppose you have an UOS
-    launch script, such as launch_UOS.sh
+Use the ``delete`` command with a VM name to delete that VM:
 
-    you can run:
+.. code-block:: none
 
-::
+   # acrnctl del vm1-14:59:30
 
-  # acrnctl add launch_UOS.sh -U 1
-    vm1-14:59:30 added
+List VMs
+========
 
-Note that, launch script shoud be able to launch ONE UOS. If
-it fail, it is better to print some error logs, to tell user
-the reason, so that he knows how to solve it.
-The vmname is important, the acrnctl searchs VMs by their
-names. so duplicated VM names are not allowed. Beside, if the
-launch script changes VM name at launch time, acrnctl will
-not recgonize it.
+Use the ``list`` command to display VMs and their state:
 
-(2) delete VMs
+.. code-block:: none
 
-::
+   # acrnctl list
+   vm1-14:59:30            untracked
+   vm-yocto                stopped
+   vm-android              stopped
 
-  # acrnctl del vm1-14:59:30
+Start VM
+========
 
-(3) show VMs
+If a VM is in a ``stopped`` state, you can start it with the ``start``
+command:
 
-::
+.. code-block:: none
 
-  # acrnctl list
-    vm1-14:59:30            untracked
-    vm-yocto                stop
-    vm-android              stop
+   # acrnctl start vm-yocto
 
-(4) start VM
+Stop VM
+=======
 
-    you can start a vm with 'stop' status, each time can start
-    one VM.
+Use the ``stop`` command to stop one or more running VM:
 
-::
+.. code-block:: none
 
-  # acrnctl start vm-yocto
+   # acrnctl stop vm-yocto vm1-14:59:30 vm-android
 
-(5) stop VM
+Build and Install
+*****************
 
-    you can stop VMs, if their status is not 'stop'
+Source code for ``acrnctl`` is in the ``tools/acrn-manager`` folder.
+Change to that folder and run:
 
-::
+.. code-block:: none
 
-  # acrnctl stop vm-yocto vm1-14:59:30 vm-android
-
-BUILD
-_____
-
-::
-
-  # make
+   # make
+   # make install