Add tutorial tweaks (#380)

John Shepherd · web-flow · commit ab0042edbb81 · 2020-09-25T18:19:51.000-07:00
Signed-off-by: John Shepherd &lt;john@openrobotics.org&gt;
diff --git a/README.md b/README.md
@@ -14,7 +14,7 @@ Ubuntu Bionic | [![Build Status](https://build.osrfoundation.org/buildStatus/ico
 Homebrew      | [![Build Status](https://build.osrfoundation.org/buildStatus/icon?job=ignition_gazebo-ci-master-homebrew-amd64)](https://build.osrfoundation.org/job/ignition_gazebo-ci-master-homebrew-amd64)
 Windows       | [![Build Status](https://build.osrfoundation.org/buildStatus/icon?job=ignition_gazebo-ci-master-windows7-amd64)](https://build.osrfoundation.org/job/ignition_gazebo-ci-master-windows7-amd64)
 
-Ignition Gazebo is an open source robotics simulator. Through Ignition Gazebo users have access to high fidelity physics, rendering, and sensor models. Additionally, users and developers have multiple points of entry to simulation including a graphical user interface, plugins, and asynchronous message passing and services.
+Ignition Gazebo is an open source robotics simulator. Through Ignition Gazebo, users have access to high fidelity physics, rendering, and sensor models. Additionally, users and developers have multiple points of entry to simulation including a graphical user interface, plugins, and asynchronous message passing and services.
 
 Ignition Gazebo is derived from [Gazebo](http://gazebosim.org) and represents over 16 years of development and experience in robotics and simulation. This library is part of the [Ignition Robotics](https://ignitionrobotics.org) project.
 
@@ -61,7 +61,7 @@ of environments with high-quality lighting, shadows, and textures.
 
 * **Sensors and noise models**: Generate sensor data, optionally with noise,
 from laser range finders, 2D/3D cameras, Kinect style sensors, contact sensors,
-force-torque, IMU, GPS, and more, powered by
+force-torque, IMU, GPS, and more, all powered by
 [Ignition Sensors](https://github.com/ignitionrobotics/ign-sensors)
 
 * **Plugins**: Develop custom plugins for robot, sensor, and
diff --git a/tutorials/battery.md b/tutorials/battery.md
@@ -43,12 +43,17 @@ model:
 
 Next, you can find a description of the SDF parameters used:
 
-`<battery_name>`: The name of the battery.
-`<voltage>`: Initial voltage of the battery (V).
-`<open_circuit_voltage_constant_coef>`: Voltage at full charge (V).
-`<capacity>`: Total charge that the battery can hold (Ah).
-`<power_load>`: Power load on battery (W).
-`<fix_issue_225>`: As reported [here](https://github.com/ignitionrobotics/ign-gazebo/issues/225),
+* `<battery_name>`: The name of the battery.
+
+* `<voltage>`: Initial voltage of the battery (V).
+
+* `<open_circuit_voltage_constant_coef>`: Voltage at full charge (V).
+
+* `<capacity>`: Total charge that the battery can hold (Ah).
+
+* `<power_load>`: Power load on battery (W).
+
+* `<fix_issue_225>`: As reported [here](https://github.com/ignitionrobotics/ign-gazebo/issues/225),
 there are some issues affecting batteries in Ignition Blueprint and Citadel.
 This parameter fixes the issues. Feel free to omit the parameter if you have
 legacy code and want to preserve the old behavior.
@@ -71,10 +76,13 @@ In this case, the battery runtime should be calculated as follows:
 If you need to model a more realistic battery, you can use the following
 advanced SDF parameters:
 
-`<open_circuit_voltage_linear_coef>`: Amount of voltage decrease when no charge (V).
-`<initial_charge>`: Initial charge of the battery (Ah).
-`<resistance>`: Internal resistance (Ohm)
-`<smooth_current_tau>`: Coefficient for smoothing current.
+* `<open_circuit_voltage_linear_coef>`: Amount of voltage decrease when no charge (V).
+
+* `<initial_charge>`: Initial charge of the battery (Ah).
+
+* `<resistance>`: Internal resistance (Ohm)
+
+* `<smooth_current_tau>`: Coefficient for smoothing current.
 
 Please, refer to the battery specification to set the advanced values.
 
@@ -84,11 +92,13 @@ Please, refer to the battery specification to set the advanced values.
 A battery can be charged if the SDF parameter `<enable_recharge>` is set to true.
 Here are the relevant SDF parameters related with charging:
 
-`<enable_recharge>`: As mentioned, it should be `true` to enable recharging.
-`<charging_time>`: Hours taken to fully charge the battery. Keep in mind that
+* `<enable_recharge>`: As mentioned, it should be `true` to enable recharging.
+
+* `<charging_time>`: Hours taken to fully charge the battery. Keep in mind that
 this value assumes no battery load while charging. If the battery is under load,
 it will take a longer time to recharge.
-`<recharge_by_topic>`: If true, the start/stop signals for recharging the
+
+* `<recharge_by_topic>`: If true, the start/stop signals for recharging the
 battery will also be available via topics. The regular Ignition services will
 still be available.
 
diff --git a/tutorials/detachable_joints.md b/tutorials/detachable_joints.md
@@ -1,7 +1,7 @@
 \page detachablejoints Detachable Joints
 
 The `DetachableJoint` system allows two models to start off rigidly attached
-and then get detached during simulation by publishing to a topic. The system
+and then detach during simulation by publishing to a topic. The system
 internally uses a fixed joint between two links, each belonging to two separate
 models. Because the system uses joints to connect models, the resulting
 kinematic topology has to be a tree, i.e., kinematic loops are not currently
@@ -39,13 +39,13 @@ or child models be in collision in their initial (attached) state.
 
 The system has the following parameters:
 
-* parent_link: Name of the link in the model containing this system that will be
+* `<parent_link>`: Name of the link in the model containing this system that will be
 used as the parent link in the detachable joint.
 
-* child_model: The name of the model containing the child link in the detachable
+* `<child_model>`: The name of the model containing the child link in the detachable
 joint.
 
-* child_model_link:  Name of the link in the child_model that will be used
+* `<child_model_link>`:  Name of the link in the `<child_model>` that will be used
 as the child link in the detachable joint.
 
 * topic (optional): Topic name to be used for detaching connections. If empty,
diff --git a/tutorials/distributed_simulation.md b/tutorials/distributed_simulation.md
@@ -68,25 +68,6 @@ The secondary instances will only read the role command line option
 * **--network-role=secondary** - Dictates that the role of this
     participant is a Secondary. Capitalization of "secondary" is not important.
 
-#### Environment variables
-
-**WARNING:** Environment variables for distributed simulation configuration
-is deprecated in version 2.x.x of Ignition Gazebo. Please use the
-command-line options instead.
-
-The primary instance will read several environment variables to dictate its behavior.
-
-* **IGN_GAZEBO_NETWORK_ROLE=PRIMARY** - Dictates that the role of this
-    participant is a Primary. Capitalization of "primary" is not important.
-* **IGN_GAZEBO_NETWORK_SECONDARIES=<N>** - The number of secondaries expected
-    to join. Simulation will not begin until **N** secondaries have been
-    discovered.
-
-The secondary instances will only read the role environment variable
-
-* **IGN_GAZEBO_NETWORK_ROLE=SECONDARY** - Dictates that the role of this
-    participant is a Secondary. Capitalization of "secondary" is not important.
-
 ### Discovery
 
 Once the `ign gazebo` instance is started, it will begin a process of
@@ -134,22 +115,22 @@ containing:
     * The latest secondary-to-performer affinity changes.
     * **Upcoming**: The updated state of all performers which are changing secondaries.
 
-1. Each secondary receives the step message, and:
+2. Each secondary receives the step message, and:
 
     * Loads / unloads performers according to the received affinities
     * Runs one simulation update iteration
     * Then publishes its updated  performer states on the `/step_ack` topic.
 
-1. The primary waits until it gets step acks from all secondaries.
+3. The primary waits until it gets step acks from all secondaries.
 
-1. The primary runs a step update:
+4. The primary runs a step update:
 
     * Update its state with the states received from secondaries.
     * The `LevelManager` checks for level changes according to these new states
     * The `SceneBroadcaster` plugin publishes an updated scene to the GUI
       for any level changes.
 
-1. The primary initiates a new iteration.
+5. The primary initiates a new iteration.
 
 ### Interaction
 
diff --git a/tutorials/erb_template.md b/tutorials/erb_template.md
@@ -36,22 +36,22 @@ Below is a step-by-step tutorial to generate 1000 box shapes in a simulation wor
 You can copy-and-paste the code block into an editor to try it out.
 
 First is to create a world using SDFormat syntax.
-You need to specify both the ``xml`` and ``sdf`` versions you are using.
+You need to specify both the `xml` and `sdf` versions you are using.
 And don't forget to give your simulation world a name.
 
 ```
 <?xml version="1.0" ?>
 <sdf version="1.6">
   <world name="shapes">
-    <!-- This is where you put ``<plugin>``, ``<model>`` and etc. tags -->
+    <!-- This is where you put `<plugin>`, `<model>` and etc. tags -->
   </world>
 </sdf>
 ```
 
-To create 1000 instances of simple box shapes, you can use a ``for`` loop in Ruby syntax in the ERB template.
-This code block can be inserted in between the "``<world>`` ... ``</world>``" tags.
-Note that the ``<model>`` tags are wrapped in between the ERB template.
-``<% end %>`` is to mark the end of loops or ``if`` statements.
+To create 1000 instances of simple box shapes, you can use a `for` loop in Ruby syntax in the ERB template.
+This code block can be inserted in between the `<world>` tags.
+Note that the `<model>` tags are wrapped in between the ERB template.
+`<% end %>` is to mark the end of loops or `if` statements.
 Each box model also has a different name and pose to ensure they show up as individuals in simulation.
 
 ```
@@ -148,7 +148,7 @@ Instead of simple shapes, you can also use a nested loop to generate 100 actors
  
 ## Generate SDF from ERB template
 
-Now that an ERB template file is ready and saved as ``my_first_erb.erb``, you can run the following terminal command to generate SDF file.
+Now that an ERB template file is ready and saved as `my_first_erb.erb`, you can run the following terminal command to generate the corresponding SDF file.
 
 ```{.sh}
 # generate SDF with the ERB template
@@ -157,11 +157,11 @@ erb my_first_erb.erb > my_first_erb.sdf
 
 ## Run simulation world
 
-To test if the ERB template works, run the SDF file with igniton command
+To test if the ERB template works, run the SDF file with the `ign gazebo` command
 
 ```{.sh}
 # run with Ignition Gazebo
 ign gazebo my_first_erb.sdf
 ```
 
-If there is any error or warning from running the SDF file, you would need to go back to the ERB file and see if any coding mistakes are made.
+If there are any errors or warnings from running the SDF file, you would need to go back to the ERB file and see if any coding mistakes were made.
diff --git a/tutorials/levels.md b/tutorials/levels.md
@@ -24,8 +24,7 @@ as described below, and to launch Gazebo with the `--levels` flag.
 All the situations described here refer to simulation running in a single
 server.
 
-> Take a look at the [terminology](terminology.html) tutorial to get familiar with
-> concepts used in this tutorial.
+\note Take a look at the [terminology](terminology.html) tutorial to get familiar with concepts used in this tutorial.
 
 ## Try it out
 
@@ -87,7 +86,7 @@ but the same logic can be extended to multiple performers.
 levels (`L1`~`L3`).
 
 * The **light blue area** represents the buffer zone for level `L1`. Zones
-  for `L2` and `L3` have been ommitted.
+  for `L2` and `L3` have been omitted.
 
 * Each **orange shape** represents a static model in the world (`M1`~`M6`)
 
@@ -198,7 +197,7 @@ In addition, the `<performer>` tag contains information about the volume
 occupied by the performer. This volume is specified by the `<geometry>` tag.
 Only the `<box>` tag is currently supported.
 
-\note The volume for a performer maybe automatically generated in future
+\note The volume for a performer may be automatically generated in future
 versions of Gazebo.
 
 Example snippet:
@@ -216,7 +215,7 @@ Example snippet:
 
 ### Runtime performers
 
-Performers can be specified at runtime using an Igntion Transport service.
+Performers can be specified at runtime using an Ignition Transport service.
 This functionality can be used when a performer is not known at load time. For
 example, you may need to start simulation with an empty world and spawn
 models (performers) into simulation at a later time.
diff --git a/tutorials/log.md b/tutorials/log.md
@@ -64,20 +64,11 @@ Recording can be specified in the SDF, under `<world>` tag:
     <plugin
       filename="ignition-gazebo-log-system"
       name="ignition::gazebo::systems::LogRecord">
-      <!--
-         Deprecated: Specifying the path on SDF is deprecated on Blueprint and
-         Citadel, and will be removed on Dome. Use one of the other methods to
-         speficy the path instead.
-      -->
-      <!--path>/tmp/log</path-->
     </plugin>
     ...
 </world>
 ```
 
-Use of `<path>` results in the console log and state recording being written
-to different locations. Existing paths are overwritten by default. See below.
-
 Currently, it is enforced that only one recording instance is allowed to
 start during a Gazebo run.
 
@@ -95,12 +86,6 @@ The final record path will depend on a few options:
         * If no `--log-overwrite`, logs are recorded to a new path with a number
           appended, i.e. `/tmp/log(1)`, `/tmp/log(2)`...
         * If `--log-overwrite`, the directory is cleared and logs recorded to it.
-* If `<path>` in SDF (deprecated, not recommended):
-    * It will be used unless the path is specified through the command line or API.
-    * The SDF doesn't affect the console log, so that file will still go to the
-      timestamped directory.
-    * If the path exists, it will always be overwritten and there's no way to
-      disable this behaviour.
 
 ## Playback
 
diff --git a/tutorials/migrating_ardupilot_plugin.md b/tutorials/migrating_ardupilot_plugin.md
@@ -24,7 +24,7 @@ documentation](https://ardupilot.org/dev/docs/using-gazebo-simulator-with-sitl.h
 As context to understand what we're migrating, here's a system diagram for how
 the ArduPilot Gazebo plugin works is used:
 
-<img src="https://raw.githubusercontent.com/ignitionrobotics/ign-gazebo/add_ardupilot_migration_tutorial2/tutorials/files/ardupilot_diagram.png"/>
+<img src="https://raw.githubusercontent.com/ignitionrobotics/ign-gazebo/master/tutorials/files/ardupilot_diagram.png"/>
 
 *UAV icon credit: By Julian Herzog, CC BY 4.0, https://commons.wikimedia.org/w/index.php?curid=60965475*
 
diff --git a/tutorials/migration_plugins.md b/tutorials/migration_plugins.md
@@ -1,8 +1,8 @@
 \page migrationplugins
 
-# Migration from Gazebo-classic: Plugins
+# Migration from Gazebo Classic: Plugins
 
-Classic Gazebo supports
+Gazebo Classic supports
 [6 different C++ plugin types](http://gazebosim.org/tutorials?tut=plugins_hello_world&cat=write_plugin),
 each providing access to different parts of the API, like physics, rendering,
 sensors, GUI, etc. Due to Ignition Gazebo's architecture based on an
@@ -15,7 +15,7 @@ while others are specific plugin types from other Ignition libraries.
 
 For example, plugins which get and set properties of simulation entities would be
 Ignition Gazebo systems. On the other hand, there are now plugin interfaces which didn't
-exist in Gazebo, such as integrating a new physics or rendering engine, and these can
+exist in Gazebo Classic, such as integrating a new physics or rendering engine, and these can
 be also used in projects outside of Ignition Gazebo.
 
 Take a look at the comparison below:
@@ -39,14 +39,14 @@ System | Access command line arguments | TBD | -
 ---
 
 Another key difference is that systems will be able to access all entity
-properties at once, despite the entity type. So while in Gazebo you may
+properties at once, despite the entity type. So while in Gazebo Classic you may
 need 3 different plugins to interact with physics, rendering and sensors, on
 Ignition you could, for example, set a camera's visual color, its velocity and
 frame rate, all from a single plugin.
 
 ## Plugin interfaces
 
-Let's take a look at a typical Gazebo plugin which accesses a property from an
+Let's take a look at a typical Gazebo Classic plugin which accesses a property from an
 entity and does something with it. In this case, it will print the current pose
 of a link.
 
@@ -223,7 +223,7 @@ IGNITION_ADD_PLUGIN(MyPlugin,
 IGNITION_ADD_PLUGIN_ALIAS(MyPlugin,"ignition::gazebo::systems::MyPlugin")
 ```
 
-In summary, the key differences between classic and Igntion Gazebo are:
+In summary, the key differences between Gazebo Classic and Ignition Gazebo are:
 
 * Plugins must inherit from the `ISystemConfigure` class to be able to override
   the `Configure` callback that gives access to many things, such as the SDF
@@ -234,7 +234,7 @@ In summary, the key differences between classic and Igntion Gazebo are:
 
 * Plugins don't have direct access to physics objects such as `physics::Model`.
   Instead, they can either deal directly with entities and their components by
-  calling functions in the ECM, or use convenient objects such as
+  calling functions in the ECM, or using convenient objects such as
   `ignition::gazebo::Model` which wrap the ECM interface.
 
 All these changes are meant to give plugin developers more flexibility to
diff --git a/tutorials/point_cloud_to_mesh.md b/tutorials/point_cloud_to_mesh.md
@@ -93,7 +93,7 @@ Our tunnel has turned into a blob shape.
 This is because the mesh that CloudCompare creates will always be water tight even if it has to add polygons where there are no points.
 We just want our tunnels, though, so we need to remove those unnecessary polygons.
 
-![The "blob shape"](https://raw.githubusercontent.com/ignitionrobotics/ign-gazebo/master/tutorials/files/point_cloud_to_mesh/blob2.png)
+![The blob shape](https://raw.githubusercontent.com/ignitionrobotics/ign-gazebo/master/tutorials/files/point_cloud_to_mesh/blob2.png)
 
 This is where our scalar field comes in.
 In the mesh's `Properties` window go to `SF display params` and take the left handle in the graph and drag it to the right until it hits the area where the bulk of the scalar field starts.
diff --git a/tutorials/resources.md b/tutorials/resources.md
@@ -123,8 +123,8 @@ Ignition will look for URIs (path / URL) in the following, in order:
     1. Cache (i.e. `$HOME/.ignition/fuel`)
     2. Web server
 
-> \* The `SDF_PATH` environment variable also works in some scenarios, but
-    it's not recommended when using Ignition Gazebo.
+\* The `SDF_PATH` environment variable also works in some scenarios, but
+  it's not recommended when using Ignition Gazebo.
 
 ## Meshes
 
@@ -141,8 +141,8 @@ Ignition will look for URIs (path / URL) in the following, in order:
 2. All paths on the `IGN_GAZEBO_RESOURCE_PATH`\* environment variable (if path
    is URI, scheme is stripped)
 
-> \* The `IGN_FILE_PATH` environment variable also works in some scenarios, but
-    it's not recommended when using Ignition Gazebo.
+\* The `IGN_FILE_PATH` environment variable also works in some scenarios, but
+  it's not recommended when using Ignition Gazebo.
 
 ### GUI configuration
 
diff --git a/tutorials/terminology.md b/tutorials/terminology.md
diff --git a/tutorials/triggered_publisher.md b/tutorials/triggered_publisher.md
