From 9b01d64f4dc8636604494f32ac847fbddee95ed3 Mon Sep 17 00:00:00 2001
From: Jeffrey Novotny <jnovotny@amd.com>
Date: Thu, 18 Jul 2024 17:32:36 -0400
Subject: [PATCH] Additional edits based on the external review

---
 docs/how-to/profiling-python-scripts.rst       | 12 ++++++++----
 docs/how-to/understanding-omnitrace-output.rst | 13 +++++++------
 docs/install/install.rst                       |  2 ++
 docs/reference/development-guide.rst           | 10 +++++-----
 4 files changed, 22 insertions(+), 15 deletions(-)

diff --git a/docs/how-to/profiling-python-scripts.rst b/docs/how-to/profiling-python-scripts.rst
index f080f47a3..c1185f679 100644
--- a/docs/how-to/profiling-python-scripts.rst
+++ b/docs/how-to/profiling-python-scripts.rst
@@ -54,13 +54,17 @@ This means the following commands are effectively equivalent:
 
    omnitrace-python --help
 
+and
+
+.. code-block:: shell
+
    export PYTHONPATH=/opt/omnitrace/lib/python3.8/site-packages:${PYTHONPATH}
    python3.8 -m omnitrace --help
 
 .. note::
 
    ``omnitrace-python`` and ``python -m omnitrace`` use the same command-line syntax 
-   as the ``omnitrace`` executable (``omnitrace-python <OMNITRACE_ARGS> -- <SCRIPT> <SCRIPT_ARGS>``) 
+   as the other ``omnitrace`` executables (``omnitrace-python <OMNITRACE_ARGS> -- <SCRIPT> <SCRIPT_ARGS>``) 
    and has similar options.
 
 Command line options
@@ -109,10 +113,10 @@ Use ``omnitrace-python --help`` to view the available options:
 Selective instrumentation
 -----------------------------------
 
-Similar to the ``omnitrace`` executable, command-line options exist for restricting, 
+Similar to the ``omnitrace-instrument`` executable, command-line options exist for restricting, 
 including, and excluding certain functions and modules, for example, ``--function-exclude "^__init__$"``.
-Alternatively, adding the ``@profile`` decorator to the primary function of interest 
-in combination with the ``-b`` / ``--builtin`` option will narrow the scope of the
+Alternatively, add the ``@profile`` decorator to the primary function of interest 
+in your program and use the ``-b`` / ``--builtin`` command-line option to narrow the scope of the
 instrumentation to this function and its children.
 
 Consider the following Python code (``example.py``):
diff --git a/docs/how-to/understanding-omnitrace-output.rst b/docs/how-to/understanding-omnitrace-output.rst
index b6ac40797..b7301f414 100644
--- a/docs/how-to/understanding-omnitrace-output.rst
+++ b/docs/how-to/understanding-omnitrace-output.rst
@@ -240,7 +240,7 @@ Metadata JSON Sample
 Configuring the Omnitrace output
 ========================================
 
-Omnitrace includes a core set of settings for controlling the format 
+Omnitrace includes a core set of options for controlling the format 
 and contents of the output files. For additional information, see the guide on
 :doc:`configuring runtime options <./configuring-runtime-options>`.
 
@@ -249,7 +249,7 @@ Core configuration settings
 
 .. csv-table:: 
    :header: "Setting", "Value", "Description"
-   :widths: 30, 20, 100
+   :widths: 30, 30, 100
 
    "``OMNITRACE_OUTPUT_PATH``", "Any valid path", "Path to folder where output files should be placed"
    "``OMNITRACE_OUTPUT_PREFIX``", "String", "Useful for multiple runs with different arguments. See the next section on output prefix keys."
@@ -349,9 +349,10 @@ Use ``omnitrace-avail --components --filename`` to view the base filename for ea
    | sampling_wall_clock             |     true      | sampling_wall_clock    |
    |---------------------------------|---------------|------------------------|
 
-With the settings ``OMNITRACE_COLLAPSE_THREADS=ON`` and ``OMNITRACE_COLLAPSE_PROCESSES=ON``, which is only valid 
-with full MPI support, the Timemory output
-combines the per-thread and/or per-rank data, which have identical call stacks.
+The ``OMNITRACE_COLLAPSE_THREADS`` and ``OMNITRACE_COLLAPSE_PROCESSES`` settings are 
+only valid when full `MPI support is enabled <../install/install.html#mpi-support-within-omnitrace>`_. 
+When they are set, Timemory combines the per-thread and per-rank data (respectively) of 
+identical call stacks.
 
 The ``OMNITRACE_FLAT_PROFILE`` setting removes all call stack hierarchy. 
 Using ``OMNITRACE_FLAT_PROFILE=ON`` in combination
@@ -360,7 +361,7 @@ min/max measurements regardless of the calling context.
 The ``OMNITRACE_TIMELINE_PROFILE`` setting (with ``OMNITRACE_FLAT_PROFILE=OFF``) effectively 
 generates similar data to that found
 in Perfetto. Enabling timeline and flat profiling effectively generates 
-similar data to ``strace``. However, while Timemory in general
+similar data to ``strace``. However, while Timemory generally
 requires significantly less memory than Perfetto, this is not the case in timeline 
 mode, so use this setting with caution.
 
diff --git a/docs/install/install.rst b/docs/install/install.rst
index 7ae90e92d..8cdc0b31a 100644
--- a/docs/install/install.rst
+++ b/docs/install/install.rst
@@ -271,6 +271,8 @@ in `the Perfetto UI <https://ui.perfetto.dev>`_.
    cmake --build omnitrace-build --target install
    source /opt/omnitrace/share/omnitrace/setup-env.sh
 
+.. _mpi-support-omnitrace:
+
 MPI support within Omnitrace
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/docs/reference/development-guide.rst b/docs/reference/development-guide.rst
index d580d22dd..0fb79902d 100644
--- a/docs/reference/development-guide.rst
+++ b/docs/reference/development-guide.rst
@@ -394,12 +394,12 @@ integer indicating how many times to repeat the delay and duration cycle. It is
 possible to perform tasks such as periodically enabling tracing for brief periods
 of time in between long periods without data collection while the application runs. The
 syntax follows the format ``clock_identifier:delay:capture_duration:cycles``, so a value of 
-``10:1:3`` represents the following sequence of operations:
+``10:1:3`` for the last three parameters represents the following sequence of operations:
 
-* 10 seconds where no data is collected, then one second where it is
-* 10 seconds where no data is collected, then one second where it is 
-* 10 seconds where no data is collected, then one second where it is 
-* stop
+* Ten seconds where no data is collected, then one second where it is
+* Ten seconds where no data is collected, then one second where it is 
+* Ten seconds where no data is collected, then one second where it is 
+* Stop
 
 As another example, ``OMNITRACE_TRACE_PERIODS = realtime:10:1:5 process_cputime:10:2:20`` translates
 to this sequence: