Changes to address comments from the internal review

docs/conceptual/how-omnitrace-works.rst

@@ -196,7 +196,7 @@ Callback APIs and dynamic symbol interception can be utilized with either tool.
 Binary instrumentation
 -----------------------------------
 
-Binary instrumentation allows you to record deterministic measurements for 
+Binary instrumentation lets you record deterministic measurements for 
 every single invocation of a given function.
 Binary instrumentation effectively adds instructions to the target application to 
 collect the required information. It therefore has the potential to cause performance 
@@ -218,8 +218,8 @@ Statistical sampling
 
 Statistical call-stack sampling periodically interrupts the application at 
 regular intervals using operating system interrupts.
-Sampling is typically less numerically accurate and specific, but allows the 
-target program to run nearly at full speed.
+Sampling is typically less numerically accurate and specific, but the 
+target program runs at nearly full speed.
 In contrast to the data derived from binary instrumentation, the resulting 
 data is not exact but is instead a statistical approximation.
 However, sampling often provides a more accurate picture of the application 
@@ -280,7 +280,7 @@ which contain fewer than 1024 instructions.
 
 However, recording every single invocation of the function can be extremely 
 useful for detecting anomalies, such as profiles that show minimum or maximum values much smaller or larger
-than the average or a high standard deviation. In this case, traces allow you to 
+than the average or a high standard deviation. In this case, the traces help you 
 identify exactly when and where those instances deviated from the norm.
 Compare the level of detail in the following traces. In the top image, 
 every instance of the ``fib`` function is instrumented, while in the bottom image,

docs/how-to/configuring-runtime-options.rst

@@ -9,7 +9,7 @@ Configuring runtime options
 The ``omnitrace.cfg`` file maintains a list of the `Omnitrace <https://github.com/ROCm/omnitrace>`_ runtime options. To create this configuration 
 file and view the current runtime options, use the ``omnitrace-avail`` executable.
 
-The ``omnitrace-avail`` executable
+The omnitrace-avail executable
 ========================================
 
 The ``omnitrace-avail`` executable provides information about the runtime settings, 
@@ -123,7 +123,7 @@ Here is a sample configuration for hardware counters:
    # using perf identifiers
    OMNITRACE_PAPI_EVENTS   = perf::INSTRUCTIONS perf::CACHE-REFERENCES perf::CACHE-MISSES
 
-``OMNITRACE_PAPI_EVENTS``
+OMNITRACE_PAPI_EVENTS
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 In order to collect the majority of hardware counters via PAPI, ensure the ``/proc/sys/kernel/perf_event_paranoid``
@@ -171,7 +171,7 @@ PAPI components from different namespaces:
    installed with the prefix ``omnitrace-`` with
    underscores replaced with hypens, for example ``papi_avail`` becomes ``omnitrace-papi-avail``.
 
-``OMNITRACE_ROCM_EVENTS``
+OMNITRACE_ROCM_EVENTS
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Omnitrace reads the ROCm events from the ``${ROCM_PATH}/lib/rocprofiler/metrics.xml`` 
@@ -202,7 +202,7 @@ The following example:
 
    OMNITRACE_ROCM_EVENTS = GPUBusy     SQ_WAVES:device=0    SQ_INSTS_VALU:device=1
 
-``omnitrace-avail`` examples
+omnitrace-avail examples
 -----------------------------------
 
 The following examples demonstrate how to use ``omnitrace-avail`` to perform several common 

docs/how-to/configuring-validating-environment.rst

@@ -6,7 +6,7 @@
 Configuring and validating the environment
 ****************************************************
 
-After installing the `Omnitrace <https://github.com/ROCm/omnitrace>`_ application, some additional steps are required to set up
+After installing `Omnitrace <https://github.com/ROCm/omnitrace>`_, additional steps are required to set up
 and validate the environment.
 
 .. note::

docs/how-to/instrumenting-rewriting-binary-application.rst

@@ -48,7 +48,7 @@ Here is a comparison of the three modes:
     application is in one specific dynamic library,
     see :ref:`binary-rewriting-library-label` for help
 
-The ``omnitrace-instrument`` executable
+The omnitrace-instrument executable
 ========================================
 
 Instrumentation is performed with the ``omnitrace-instrument`` executable. For more details, use the ``-h`` or ``--help`` option to
@@ -541,7 +541,7 @@ not satisfy their regular expression.
 
 To narrow the scope of the instrumentation to a specific set 
 of libraries and/or functions, use the ``--module-restrict`` and ``--function-restrict`` options.
-These options allow you to exclusively select the union of one or more 
+These options let you exclusively select the union of one or more 
 regular expressions, regardless of whether or not the functions satisfy the
 previously-mentioned default heuristics. Any function or module that is not within 
 the union of these regular expressions is excluded from instrumentation.

docs/how-to/performing-causal-profiling.rst

@@ -206,7 +206,7 @@ or
 To make the paranoid level persistent after a reboot, add ``kernel.perf_event_paranoid=<N>``
 (where ``<N>`` is the desired paranoid level) to the ``/etc/sysctl.conf`` file.
 
-Speed-up prediction variability and the ``omnitrace-causal`` executable
+Speed-up prediction variability and the omnitrace-causal executable
 -----------------------------------------------------------------------
 
 Causal profiling typically requires running the application several times in 
@@ -541,7 +541,7 @@ Examples
       --                                      \
       ./lulesh-omni -i 50 -s 200 -r 20 -b 5 -c 5 -p
 
-Using ``omnitrace-causal`` with other launchers like ``mpirun``
+Using omnitrace-causal with other launchers like mpirun
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The ``omnitrace-causal`` executable is intended to assist with application replay 

docs/how-to/profiling-python-scripts.rst

@@ -19,7 +19,7 @@ be the same size.
 
 .. note::
 
-   When using Omnitrace for Python, the Python interpreter major and minor version (e.g. 3.7) 
+   When using Omnitrace with Python programs, the Python interpreter major and minor version (e.g. 3.7) 
    must match the interpreter major and minor version
    used when compiling the Python bindings. When building Omnitrace, 
    the shared object file ``libpyomnitrace.<IMPL>-<VERSION>-<ARCH>-<OS>-<ABI>.so`` is generated

docs/how-to/sampling-call-stack.rst

@@ -63,7 +63,7 @@ is not necessary. This is for a number of reasons:
     performing a binary rewrite of the executable and then using the instrumented executable 
     in lieu of the original executable. ``omnitrace-sample`` is therefore much easier to use with MPI.
 
-The ``omnitrace-sample`` executable
+The omnitrace-sample executable
 ========================================
 
 View the help menu of ``omnitrace-sample`` with the ``-h`` / ``--help`` option:
@@ -337,7 +337,7 @@ The following snippets show how ``omnitrace-sample`` runs with various environme
       OMNITRACE_PROFILE=true
       ...
 
-An ``omnitrace-sample`` example
+An omnitrace-sample example
 ========================================
 
 Here is the full output from the previous 

docs/how-to/troubleshooting-omnitrace-linux.rst

@@ -3,16 +3,21 @@
    :keywords: Omnitrace, ROCm, profiler, tracking, visualization, tool, Instinct, accelerator, AMD
 
 ****************************************************
-Troubleshooting Omnitrace on Linux
+Troubleshooting Omnitrace
 ****************************************************
 
+This guide explains how to resolve certain issues when installing or running Omnitrace.
+
+Troubleshooting Omnitrace instrumentation on RHEL
+==================================================
+
 RHEL (Red Hat Enterprise Linux) distributions of Linux automatically enable a security feature 
 called SELinux that prevents `Omnitrace <https://github.com/ROCm/omnitrace>`_ from operating successfully.
 This issue applies to systems running the CentOS 9 operating system using
-AMD ROCm Software version 6.1.x alongside an MI300 GPU.
+AMD ROCm Software version 6.1.x alongside an AMD Instinct MI300 GPU.
 
 Steps to reproduce the issue
-========================================
+-------------------------------
 
 The problem occurs after the following operations:
 
@@ -43,7 +48,7 @@ Instead of successfully running the binary with call-stack sampling,
 Omnitrace crashes with a segmentation fault.
 
 Temporary and permanent workarounds
-========================================
+------------------------------------
 
 A workaround for this problem can be applied permanently or to the current session:
 

docs/how-to/using-omnitrace-api.rst

@@ -11,7 +11,7 @@ The following example shows how a program can use the Omnitrace API to analyze a
 Omnitrace user API example program
 ========================================
 
-The Omnitrace API allows you to define custom regions to profile and trace.
+You can use the Omnitrace API to define custom regions to profile and trace.
 The following C++ program demonstrates this technique by calling several functions from the 
 Omnitrace API, such as ``omnitrace_user_push_region`` and 
 ``omnitrace_user_stop_thread_trace``.

docs/index.rst

@@ -42,7 +42,7 @@ The documentation is structured as follows:
     * :doc:`Performing causal profiling <./how-to/performing-causal-profiling>`
     * :doc:`Understanding the Omnitrace output <./how-to/understanding-omnitrace-output>`
     * :doc:`Profiling Python scripts <./how-to/profiling-python-scripts>`
-    * :doc:`Troubleshooting Omnitrace on Linux <./how-to/troubleshooting-omnitrace-linux>`
+    * :doc:`Troubleshooting Omnitrace <./how-to/troubleshooting-omnitrace-linux>`
     * :doc:`Using the Omnitrace API <./how-to/using-omnitrace-api>`
 
   .. grid-item-card:: Conceptual

docs/install/install.rst

@@ -15,8 +15,8 @@ Release links
 
 To review and install either the current Omnitrace release or earlier releases, use these links:
 
-* `Latest Omnitrace Release <https://github.com/ROCm/omnitrace/releases/latest>`_ 
-* `All Omnitrace Releases <https://github.com/ROCm/omnitrace/releases>`_ 
+* Latest Omnitrace Release: `<https://github.com/ROCm/omnitrace/releases/latest>`_ 
+* All Omnitrace Releases: `<https://github.com/ROCm/omnitrace/releases>`_ 
 
 Operating system support
 ========================================
@@ -31,7 +31,7 @@ Omnitrace is only supported on Linux. The following distributions are tested in
 * Red Hat 9.0
 * Red Hat 9.1
 
-Other OS distributions might be supported but are not tested.
+Other OS distributions might function but are not supported or tested.
 
 Identifying the operating system
 -----------------------------------

docs/reference/development-guide.rst

@@ -15,7 +15,7 @@ Executables
 
 This section lists the Omnitrace executables.
 
-``omnitrace-avail``: `source/bin/omnitrace-avail <https://github.com/ROCm/omnitrace/tree/main/source/bin/omnitrace-avail>`_
+omnitrace-avail: `source/bin/omnitrace-avail <https://github.com/ROCm/omnitrace/tree/main/source/bin/omnitrace-avail>`_
 -------------------------------------------------------------------------------------------------------------------------------
 
 The ``main`` routine of ``omnitrace-avail`` has three important sections:
@@ -24,15 +24,15 @@ The ``main`` routine of ``omnitrace-avail`` has three important sections:
 * Printing options
 * Printing hardware counters
 
-``omnitrace-sample``: `source/bin/omnitrace-sample <https://github.com/ROCm/omnitrace/tree/main/source/bin/omnitrace-sample>`_
+omnitrace-sample: `source/bin/omnitrace-sample <https://github.com/ROCm/omnitrace/tree/main/source/bin/omnitrace-sample>`_
 -------------------------------------------------------------------------------------------------------------------------------
 
 * Requires a command-line format of ``omnitrace-sample <options> -- <command> <command-args>``
 * Translates command-line options into environment variables
 * Adds ``libomnitrace-dl.so`` to ``LD_PRELOAD``
 * Is launched by using ``execvpe`` with ``<command> <command-args>`` and a modified environment
 
-``omnitrace-casual``: `source/bin/omnitrace-causal <https://github.com/ROCm/omnitrace/tree/main/source/bin/omnitrace-causal>`_
+omnitrace-casual: `source/bin/omnitrace-causal <https://github.com/ROCm/omnitrace/tree/main/source/bin/omnitrace-causal>`_
 -------------------------------------------------------------------------------------------------------------------------------
 
 When there is exactly one causal profiling configuration variant (which enables debugging),
@@ -45,7 +45,7 @@ the following actions take place for each variant:
 * the child process launches ``<command> <command-args>`` using ``execvpe``, which modifies the environment for the variant
 * the parent process waits for the child process to finish
 
-``omnitrace-instrument``: `source/bin/omnitrace-instrument <https://github.com/ROCm/omnitrace/tree/main/source/bin/omnitrace-instrument>`_
+omnitrace-instrument: `source/bin/omnitrace-instrument <https://github.com/ROCm/omnitrace/tree/main/source/bin/omnitrace-instrument>`_
 -------------------------------------------------------------------------------------------------------------------------------------------
 
 * Requires a command-line format of ``omnitrace-instrument <options> -- <command> <command-args>``
@@ -89,12 +89,12 @@ Binary library: `source/lib/binary <https://github.com/ROCm/omnitrace/tree/main/
 * Mostly used by the causal profiling sections of ``libomnitrace``.
 * Not installed or exported outside of the build tree.
 
-``libomnitrace``: `source/lib/omnitrace <https://github.com/ROCm/omnitrace/tree/main/source/lib/omnitrace>`_
+libomnitrace: `source/lib/omnitrace <https://github.com/ROCm/omnitrace/tree/main/source/lib/omnitrace>`_
 --------------------------------------------------------------------------------------------------------------------------------
 
 This is the main library encapsulating all the capabilities.
 
-``libomnitrace-dl``: `source/lib/omnitrace-dl <https://github.com/ROCm/omnitrace/tree/main/source/lib/omnitrace-dl>`_
+libomnitrace-dl: `source/lib/omnitrace-dl <https://github.com/ROCm/omnitrace/tree/main/source/lib/omnitrace-dl>`_
 --------------------------------------------------------------------------------------------------------------------------------
 
 This is a lightweight, front-end library for ``libomnitrace`` which serves three primary purposes:
@@ -105,7 +105,7 @@ This is a lightweight, front-end library for ``libomnitrace`` which serves three
 * Prevents re-entry if ``libomnitrace`` calls an instrumented function internally
 * Coordinates communication between ``libomnitrace-user`` and ``libomnitrace``
 
-``libomnitrace-user``: `source/lib/omnitrace-user <https://github.com/ROCm/omnitrace/tree/main/source/lib/omnitrace-user>`_
+libomnitrace-user: `source/lib/omnitrace-user <https://github.com/ROCm/omnitrace/tree/main/source/lib/omnitrace-user>`_
 --------------------------------------------------------------------------------------------------------------------------------
 
 * Provides a set of functions and types for the users to add to their code, for example,
@@ -375,7 +375,7 @@ the sampler hands the buffer off to its allocator thread and maps a new buffer w
 before taking the next sample. The allocator thread takes this data 
 and either dynamically stores it in memory or writes it to a file depending on the 
 value of ``OMNITRACE_USE_TEMPORARY_FILES``.
-This schema avoids all allocations in the signal handler, allows the data to grow 
+This schema avoids all allocations in the signal handler, lets the data grow 
 dynamically, avoids potentially slow I/O within the signal handler, and also enables 
 the capability of avoiding I/O altogether.
 The maximum number of samplers handled by each allocator is governed by the 

docs/sphinx/_toc.yml.in

@@ -39,7 +39,7 @@ subtrees:
     - file: how-to/profiling-python-scripts.rst
       title: Profiling Python scripts  
     - file: how-to/troubleshooting-omnitrace-linux.rst
-      title: Troubleshooting Omnitrace on Linux
+      title: Troubleshooting Omnitrace
     - file: how-to/using-omnitrace-api.rst
       title: Using the Omnitrace API
 
@@ -54,9 +54,6 @@ subtrees:
     entries:
     - file: reference/development-guide.rst
       title: Development guide
-
-  - caption: API
-    entries:
     - file: doxygen/html/files
       title: API library
     - file: doxygen/html/globals