Polishing instructions.

README.md

@@ -2,7 +2,7 @@
 
 A number of development environments have been set up, adapted to different tasks.  The development environments provide many additional functionalities related to the core system, including those functionalities that are present in the tutorials.
 
-Please note that the instructions for the development environments are written for developers.  They do not necessarily explain every step in detail and have not necessarily been tested on every combination of hardware, operating system, software setup and so on.  You are welcome to contact us for assistance in troubleshooting problems that may arise. 
+Please note that the instructions for the development environments are written for developers.  They do not necessarily explain every step in detail and have not necessarily been tested on every combination of hardware, operating system, software setup and so on.  You are welcome to contact us for assistance in troubleshooting problems that may arise or to discuss various functionalities in the development environments. 
 
 To install and configure a development environment, follow these steps:
 
@@ -10,7 +10,7 @@ To install and configure a development environment, follow these steps:
 
 - [Install local software on your development system](doc/install_playbooks.md) using Ansible Playbooks
 
-- [Log in to the Docker Registry](doc/docker_login.md) using a Deploy Key or Gitlab user/keyword
+- [Log in to the LRS Docker Registry](doc/docker_login.md) using a Deploy Key or Gitlab user/keyword
 
 - [Install Nvidia Docker drivers](doc/docker_nvidia.md) if you have an Nvidia graphics card and you are not using a virtual machine
 

doc/docker_install.md

 # Using LRS Dockers
 
-To install the Docker-based LRS modules, you should first clone the `lrs_devenv_common` repo:
+To install the Docker-based LRS modules, you must first have [logged in to the LRS Docker Registry](doc/docker_login.md) and possibly [installed Nvidia Docker drivers].
+
+Then you should clone the `lrs_devenv_common` repo, which (among other things) contains a number of scripts to be used together with the development environments:
 
 ```bash
 git clone git@gitlab.liu.se:lrs/lrs_devenv_common.git

doc/docker_login.md

-# Logging In to the Docker Registry
+# Logging In to the LRS Docker Registry
 
-A large part of the software for the development environments is made available in Docker images.  To access these images you need to log in to our Docker Registry using one of the following methods.
+A large part of the software for the development environments is made available in Docker images.  To access these images you need to log in to our Docker Registry using one of the following methods.  (Another page describes how to actually download/pull the relevant Docker image.)
 
 - If you have received a Deploy Key from us, use this to log in according to the instructions we specified at that point.
 

doc/install_os.md

 # Using Ubuntu LTS
 
-Unlike the *tutorials*, the development environments cannot be entirely encapsulated in Docker images that can be executed on a wider variety of operating systems.  For almost all development purposes, you will also need a "real" or virtual Ubuntu Linux system, with ROS installed, for the actual development of your own software.
+Unlike the *tutorials*, the development environments cannot be entirely encapsulated in Docker images.  For almost all development purposes, you will also need a "real" or virtual Ubuntu Linux system, with ROS installed, for the actual development of your own software.
 
-The supported operating system versions are **Ubuntu 20.04 and 18.04 LTS** (Long Term Support).  Other versions, such as the more recent 20.10, are not supported by ROS or by the software in the development environment.  We recommend **version 20.04**, which you can install either directly on your hardware (recommended) or in a virtual machine.
+The supported operating system versions are **Ubuntu 20.04 and 18.04 LTS** (Long Term Support).  Other versions, such as the more recent 20.10, are not supported by ROS or by the software in the development environment.  If you are installing an operating system now (as opposed to continuing with an existing installation), we definitely recommend **Ubuntu 20.04**, which you can install either directly on your hardware (recommended) or in a virtual machine.
 
 ## Terminology
 
@@ -14,11 +14,11 @@ The supported operating system versions are **Ubuntu 20.04 and 18.04 LTS** (Long
 
 You can develop in one of the following ways:
 
-- **Use Ubuntu 20.04 as the main operating system** on your computer, and do not upgrade until the next long term support version is released (22.04), a new ROS version for Ubuntu 22.04 LTS is released, and a new version of the development environments.  This is the main alternative for many developers as the long term support versions provide a stable development system that minimizes the risk of incompatibility.
+- **Use Ubuntu 20.04 as the main operating system** on your computer, and do not upgrade until the release of (a) Ubuntu 22.04 LTS, (b) a new ROS version for Ubuntu 22.04 LTS, and (c) a new version of the development environments adapted to these new systems.  This is the main alternative for many developers as the long term support versions provide a stable development system that minimizes the risk of incompatibility.
 
 - Use **Ubuntu 20.04 in a virtual machine running on another version of Linux**, such as a newer version of Ubuntu.  This is the best supported alternative to using Ubuntu 20.04 directly on your computer.  However, there can be issues with 3D graphics, in particular when new driver versions are released.  --- 3D graphics will work, but will be slower???, especially if you use Gazebo??? +++++++++++ What is the precise meaning of "not recommended if Gazebo should be used because of 3D graphics requirements"?
 
-- Use **Ubuntu 20.04 in a virtual machine running on a Windows machine**.  This will lead to some issues in terms of using 3D graphics, but 2D graphics will work if you install an X Windows server on the Windows machine.  There are some [initial instructions](https://gitlab.liu.se/lrs/symbicloud_docker_images/-/blob/master/doc/itn.md) for this, and we will do our best to help out in case of problems, but cannot guarantee that absolutely all aspects of a development environment will work as expected.
+- Use **Ubuntu 20.04 in a virtual machine running on a Windows machine**.  This will lead to some issues in terms of using 3D graphics, but 2D graphics should work if you install an X Windows server on the Windows machine.  There are some [initial instructions](https://gitlab.liu.se/lrs/symbicloud_docker_images/-/blob/master/doc/itn.md) for this, and we will do our best to help out in case of problems, but cannot guarantee that absolutely all aspects of a development environment will work as expected.
 
 - Use **Ubuntu 20.04 in a virtual machine running on MacOS**.  This will lead to some issues in terms of using 3D graphics, but 2D graphics will work if you install an X Windows server.   +++++ Tested/untested? +++++
 

doc/install_playbooks.md

@@ -18,7 +18,7 @@ Test if you can SSH from the development system into itself without providing th
 ```bash
 ssh ${USER}@localhost
 ```
-If you are asked to enter the password, cancel the command (Ctrl+C) and execute the following command to install the needed SSH key:
+If you are asked to enter a password, cancel the command (Ctrl+C) and execute the following command to install the needed SSH key:
 ```bash
 ssh-copy-id -i ${USER}@localhost
 ```
@@ -27,9 +27,10 @@ If you don't have an SSH key generated on the development system yet, execute:
 ```bash
 ssh-keygen
 ```
-and repeat the previous step. 
 
-You should now be able to login to the development system using `ssh ${USER}@localhost`.
+Then repeat the previous step. 
+
+You should now be able to log in from the development system to itself using `ssh ${USER}@localhost` without a password.  (This does not mean that you can log in from elsewhere without a password -- you first need to log in to the system with a password, and *then* you have access to the SSH key that is needed to log in from your account on the development system to the *same* account on the development system.)
 
 ## Installing Ansible
 
@@ -58,10 +59,12 @@ cd ...some suitable location...
 git clone https://gitlab.liu.se/lrs/lrs_playbooks.git
 ```
 
-Run the `wara_develop` playbook as follows to install and update the WARA PS developer software. It can take several minutes to complete.
+Run the `wara_develop` playbook as follows to install and update the WARA PS developer software. This can take several minutes to complete.
 
 - Make sure you replace the last argument with the actual password of the root/administrator on the development system.
 
++++++++++++ The root/admin or an ordinary user account doing sudo?  Do you need to configure sudo in some specific way so that the user has access to sudo? +++++++++++++++
+
 ```bash
 cd lrs_playbooks
 git pull
@@ -72,10 +75,10 @@ Among other things, this will:
 
 - Install certain software such as cmake, g++, gcc, git, screen, joe if not already installed 
 - Install the [DJI SDK](https://github.com/dji-sdk/Onboard-SDK.git)
-- Install Docker
+- Install [Docker](https://www.docker.com/)
 - Install [ROS 1](https://www.ros.org/)
-- Install a number of development repositories for the ROS-based LRS system 
-- Compile a number of source files
+- Clone a number of development repositories for the ROS-based LRS system 
+- Compile some source files
 
 
 ## Finishing Up
@@ -103,7 +106,7 @@ CONTAINER ID        IMAGE               COMMAND             CREATED
 tompe@philo:~$ 
 ```
 
-At this point your system now has the necessary software installed.
+At this point your system has the necessary software installed.
 
 You can use the following commands on the development system to test the 3D graphics hardware and driver setup on your system:
 
@@ -120,7 +123,8 @@ roslaunch lrs_wara_gazebo gazebo.launch
 roslaunch lrs_wara_gazebo dji_to_gazebo.launch name:=dji0 with_laser:=true x:=5
 ```
 
-All files to run these tests should be available in lrs_wara_gazebo
-which is installed in wara_ws by the Playbook above. The first command
+All files to run these tests should be available in the `lrs_wara_gazebo`
+repository 
+which is installed in `wara_ws` by the Playbook above. The first command
 starts Gazebo and the second command adds a model of a DJI M100 to the
 Gazebo world.