Cleanup dependencies.rst

docs/building/dependencies.rst

@@ -1,3 +1,5 @@
+.. _deps:
+
 ############
 Dependencies
 ############
@@ -8,14 +10,18 @@ Required to Build the Core OpenDDS Libraries
 
 .. note:: Perl is required to run the configure script; MPC, ACE, and TAO will be downloaded automatically by the configure script by default.
 
-.. _dependencies-perl:
+.. _deps-perl:
 
 Perl
 ====
 
-Perl is an interpreted language used in the configure script, the tests, and most other scripting in OpenDDS codebase.
+`Perl <https://www.perl.org/>`__ is an interpreted language used in the configure script, the tests, and most other scripting in OpenDDS codebase.
 Even if the configure script is not used, it is also required to run MPC, so it is required to build OpenDDS.
 
+Perl should be 5.18 or newer and be available on the system ``PATH``.
+Older versions of Perl will probably work, but are not tested anymore.
+`Strawberry Perl <https://strawberryperl.com>`__ is recommended for Windows.
+
 Testing scripts are written in Perl and use the common PerlACE modules provided by ACE.
 For scripts that will be part of automated testing, don't assume the presence of any non-standard (CPAN) modules.
 Perl offers many facilities for portability.
@@ -25,7 +31,7 @@ Perl core modules are a required part of Perl.
 Some Linux distributions install the Perl interpreter without including core modules.
 Using OpenDDS with this sort of partial Perl installation may fail unexpectedly when using configure, MPC, ``make depend``, or test scripts.
 
-.. _dependencies-mpc:
+.. _deps-mpc:
 
 MPC
 ===
@@ -36,6 +42,8 @@ The official repository is hosted on Github at `DOCGroup/MPC <https://github.com
 
 It is included in the release archive of ACE/TAO, which is downloaded by the configure script by default.
 
+.. _deps-ace-tao:
+
 ACE/TAO
 =======
 
@@ -59,7 +67,7 @@ DOC Group ACE 7.1/TAO 3.1
 
 Both can also be manually downloaded from https://github.com/DOCGroup/ACE_TAO/releases
 
-.. _dependencies-ace:
+.. _deps-ace:
 
 ACE
 ---
@@ -89,7 +97,7 @@ Some other features OpenDDS relies on ACE for:
 - ACE provides support for platforms that have a non-standard program entry point (``main``).
   All of our ``main`` functions are ``int ACE_TMAIN(int argc, ACE_TCHAR* argv[])``.
 
-.. _dependencies-tao:
+.. _deps-tao:
 
 TAO
 ---
@@ -105,88 +113,104 @@ TAO is a C++ CORBA Implementation built on ACE.
 The TAO Developer's Guide book can be requested for free from https://objectcomputing.com/products/tao/tao-developers-guide.
 The CORBA Programmers Guide can be downloaded for free from https://www.remedy.nl/opensource/corbapg.html.
 
+.. _deps-optional:
+
 *********************
 Optional Dependencies
 *********************
 
+.. _deps-cmake:
+
 CMake
 =====
 
-OpenDDS has a :ghfile:`CMake package included <cmake>`.
+OpenDDS has a :ghfile:`package included <cmake>` for `CMake <https://cmake.org/>`__.
 See :doc:`cmake` for how to build OpenDDS applications with CMake and without the need to use MPC in your application.
 
-CMake is required to build Google Test for OpenDDS tests if a prebuilt Google Test is not found or provided.
+CMake is required to build :ref:`deps-gtest` for OpenDDS tests if a prebuilt GoogleTest is not found or provided.
 See :ghfile:`tests/gtest_setup.txt` for details.
 
-A recent release of CMake from the 3.x series should be used.
+CMake should be version 3.3 or later.
 
-Google Test
-===========
+.. _deps-gtest:
 
-Google Test is required for OpenDDS tests.
+GoogleTest
+==========
 
-Google Test is a git submodule that will be downloaded automatically if the repository was recursively cloned or submodules were initialized separately.
+`GoogleTest <https://google.github.io/googletest/>`__ is required for OpenDDS tests.
 
-.. note:: If OpenDDS was downloaded from opendds.org or another source that's not a git repository, Google Test will have to be downloaded separately and configured manually.
+GoogleTest is a git submodule that will be downloaded automatically if the repository was recursively cloned or submodules were initialized separately.
 
-Google Test is available as package, at least in Debian based Linux distributions.
+.. note:: If OpenDDS is not a git repository or Git isn't available, GoogleTest will have to be downloaded separately and configured manually.
 
 See :ghfile:`tests/gtest_setup.txt` for details.
 
+.. _deps-java:
+
 Java
 ====
 
-OpenDDS has optional Java bindings.
+OpenDDS has optional :ref:`Java bindings <java>`.
 It requires the Java Development Kit (JDK).
-See :ghfile:`java/README`.
 
 There is also support for Java Message Server (JMS) v1.1.
-In addition to the JDK, it requires Ant and JBoss 4.2.x. See :ghfile:`java/jms/README`.
+In addition to the JDK, it requires Ant and JBoss 4.2.x.
+See :ghfile:`java/jms/README`.
+
+.. _deps-qt:
 
 Qt
 ==
 
-Qt5 is used for the :ghfile:`tools/monitor` utility program and the :ghfile:`examples/DCPS/ishapes` RTPS demo.
+`Qt5 <https://www.qt.io/>`__ is used for the :ghfile:`tools/monitor` utility program and the :ghfile:`examples/DCPS/ishapes` RTPS demo.
 
 See :ghfile:`docs/qt.md` for details on configuring OpenDDS to use Qt.
 
+.. _deps-wireshark:
+
 Wireshark
 =========
 
-A Wireshark dissector plugin for OpenDDS' non-RTPS transports is included with OpenDDS.
+A `Wireshark <https://www.wireshark.org/>`__ dissector plugin for OpenDDS' non-RTPS transports is included with OpenDDS.
 The dissector supports Wireshark 1.2 and onwards and supports displaying and filtering by sample contents and from Wireshark 1.12 onwards.
 
 Because of Wireshark's use of Glib, Glib is also required to build the dissector.
 
 See :ghfile:`tools/dissector/README.md` for details.
 
+.. _deps-rapidjson:
+
 RapidJSON
 =========
 
-RapidJSON is a C++ JSON Library used for :ghfile:`sample dissection in the Wireshark dissector <tools/dissector/README.md#sample-dissection>` and RapidJSON type support.
+`RapidJSON <https://rapidjson.org/>`__ is a C++ JSON Library used for :ghfile:`sample dissection in the Wireshark dissector <tools/dissector/README.md#sample-dissection>` and RapidJSON type support.
 Support for RapidJSON, if available, is enabled by default unless ``--no-rapidjson`` was passed.
 
 RapidJSON is a git submodule that will be downloaded automatically if the repository was recursively cloned or submodules were initialized separately.
 
-.. note:: If OpenDDS was downloaded from opendds.org or another source that's not a git repository, RapidJSON will have to be downloaded separately and configured manually.
+.. note:: If OpenDDS is not a git repository or Git isn't available, RapidJSON will have to be downloaded separately and configured manually.
 
-RapidJSON is also available as package, at least in Debian-based Linux distributions.
+.. _deps-xerces:
 
 Xerces
 ======
 
-Apache Xerces ("Xerces 3 C++" specifically) is used for parsing QoS XML and security XML configuration files.
+`Apache Xerces <https://xerces.apache.org/xerces-c/>`__ ("Xerces 3 C++" specifically) is used for parsing QoS XML and :ref:`sec` XML configuration files.
+
+.. _deps-openssl:
 
 OpenSSL
 =======
 
-OpenSSL is used for DDS Security for verifying security configurations and encryption and decryption.
+`OpenSSL <https://www.openssl.org/>`__ is used for :ref:`sec` for verifying security configurations and encryption and decryption.
 Versions 1.0, 1.1 and 3.0 (3.0.1 or later) are supported.
 
+.. _deps-python:
+
 Python
 ======
 
-Python is used for some scripts where Perl isn't as suitable.
+`Python <https://www.python.org/>`__ is used for some scripts where Perl isn't as suitable.
 Most notably this includes :doc:`this Sphinx-based documentation </internal/docs>` and processing the results of the CMake tests in :ghfile:`tests/auto_run_tests.pl` if ``--cmake`` is passed.
 
 Unless noted otherwise, Python should be version 3.6 or later.

docs/building/index.rst

@@ -27,8 +27,7 @@ Configuring and Building
   If not already done, download the source from :ghrelease:`GitHub`.
 
 Use the :ghfile:`configure` script to prepare to build OpenDDS.
-This script requires Perl 5.18 or newer to be installed and available on the system ``PATH``.
-Older versions of Perl will probably work, but are not tested.
+This script requires :ref:`deps-perl`.
 
 .. tab:: Linux, macOS, BSDs, etc.
 
@@ -49,7 +48,7 @@ Older versions of Perl will probably work, but are not tested.
     configure
 
 Optionally add ``--help`` to the command line to see the advanced options available for this script.
-The configure script will download ACE/TAO and configure it for your platform.
+The configure script will download :ref:`ACE/TAO <deps-ace-tao>` and configure it for your platform.
 To use an existing ACE/TAO installation, either set the :envvar:`ACE_ROOT` and :envvar:`TAO_ROOT` environment variables or pass the ``--ace`` and ``--tao`` (if TAO is not at ``$ACE_ROOT/TAO``) options to configure.
 
 .. seealso:: :doc:`dependencies` for a full list of dependencies including ones that can be configured with the configure script.
@@ -89,18 +88,18 @@ If configure runs successfully it will end with a message about the next steps f
 
   .. seealso:: `Microsoft MSBuild Documentation <https://learn.microsoft.com/en-us/visualstudio/msbuild/msbuild>`__
 
-  The configure script creates an environment setup file called ``setenv.sh`` that sets all the environment variables the build and test steps rely on.
+  The configure script creates an environment setup file called ``setenv.cmd`` that sets all the environment variables the build and test steps rely on.
   For the command prompt that ran the configure script, these variables were set automatically.
   If running in another command prompt, the variables need to be set again before building other projects and running tests:
 
   .. code-block::
 
-    setenv.cmd
+    setenv
 
 Java
 ====
 
-If you're building OpenDDS for use by Java applications, please see the file :ghfile:`java/INSTALL` instead of this one.
+If you're building OpenDDS for use by :ref:`Java applications <java>`, please see the file :ghfile:`java/INSTALL` instead of this one.
 
 .. _building-sec:
 
@@ -111,11 +110,7 @@ Security
     Sect<14.1>
 
 :ref:`sec` is disabled by default, and must be enabled by passing ``--security`` to the configure script.
-
-It requires the following libraries to be available:
-
-- Xerces-C++ v3.x
-- OpenSSL v1.0.2+, v1.1, or v3.0.1+
+It requires :ref:`deps-xerces` and :ref:`deps-openssl`.
 
 .. tab:: Linux, macOS, BSDs, etc.
 
@@ -184,8 +179,7 @@ It requires the following libraries to be available:
 
     Official OpenSSL instructions can be found `here <https://wiki.openssl.org/index.php/Compilation_and_Installation#Windows>`__.
 
-    #. Install Perl and add it to the Path environment variable.
-       For this guide, ActiveState is used.
+    #. Install :ref:`deps-perl` and add it to the ``PATH`` environment variable.
 
     #. Install Netwide Assembler (NASM).
        Click through the latest stable release and there is a win32 and win64 directory containing executable installers.

docs/glossary.rst

@@ -23,7 +23,7 @@ Common Terms
     ACE is an open source C++ framework that is maintained alongside :term:`TAO` and is extensively used by OpenDDS.
     It provides a platform abstraction layer and various utilities such as reactors for event handing.
 
-    See :ref:`dependencies-ace` for more information.
+    See :ref:`deps-ace` for more information.
 
   Built-in Topics
   BITs
@@ -105,7 +105,7 @@ Common Terms
     A build-system that generates GNU Makefiles, Visual Studio projects, and other such files.
     It serves the same role that CMake, Meson, and Automake do in other projects.
 
-    See :ref:`dependencies-mpc` for more information.
+    See :ref:`deps-mpc` for more information.
 
   Object Management Group
   OMG
@@ -142,7 +142,7 @@ Common Terms
     TAO is a :term:`CORBA` implementation that is maintained alongside :term:`ACE`.
     OpenDDS uses it for InfoRepo discovery and :term:`tao_idl`.
 
-    See :ref:`dependencies-tao` for more information.
+    See :ref:`deps-tao` for more information.
 
   ``tao_idl``
     A program that is part of :term:`TAO` that generates C++ code from :term:`IDL` for use in TAO and OpenDDS.

docs/internal/docs.rst

@@ -229,6 +229,8 @@ These come in the form of `RST roles <https://docutils.sourceforge.io/docs/ref/r
 
     :omgspec:`dds:2.2.2`
 
+    :omgspec:`dds:2.2.2 PIM Description`
+
     :omgspec:`dds:Annex B`
 
     :omgspec:`Somewhere in the XTypes spec <xtypes>`
@@ -243,6 +245,8 @@ These come in the form of `RST roles <https://docutils.sourceforge.io/docs/ref/r
 
     :omgspec:`dds:2.2.2`
 
+    :omgspec:`dds:2.2.2 PIM Description`
+
     :omgspec:`dds:Annex B`
 
     :omgspec:`Somewhere in the XTypes spec <xtypes>`
@@ -264,7 +268,8 @@ These come in the form of `RST roles <https://docutils.sourceforge.io/docs/ref/r
   - Section that start with section numbers, such as ``2.2.2``.
     This is based on the start of the full name of the section in the table of contents.
   - All others can be linked using the section title, either part or whole, such as ``Annex B`` or ``Annex B - Syntax for Queries and Filters``.
-    This can be used to link to sections that don't have section numbers, but can be ambiguous, so it should be most or all of the title.
+    This can be used to link to sections that don't have section numbers, but can be ambiguous, so should be most or all of the title.
+    It can also be used to link to numbered sections in case the numbers change, such as ``2.2.2 PIM Description``.
 
   See :doc:`here <omg_spec_links>` for all the possible sections.
 

docs/sphinx_extensions/links.py

@@ -239,8 +239,8 @@ def add_omg_spec(app, slug, version, our_name=None, display_name=None):
                 del section_stack[level - len(section_stack):]
 
             kind = dest['kind']
-            # PDFs have two kinds of internal links. One is named and the the
-            # other is page and coordinate based.
+            # PDFs have two kinds of internal links. One is named and the other
+            # is page and coordinate based.
             # See https://pdfobject.com/pdf/pdf_open_parameters_acro8.pdf for URL syntax
             if kind == fitz.LINK_GOTO:
                 loc = 'page={}&view=FitH,{}'.format(page, dest['to'].y)