Documentation improvements.

Author: anthony-tuininga

Diff for: doc/src/user_guide/initialization.rst

@@ -21,16 +21,8 @@ default Thin mode to the Thick mode requires the addition of a call to
 :func:`oracledb.init_oracle_client()` and an application restart.  Other small
 changes may also be required.
 
-The Thick mode is enabled by:
-
-- Calling :func:`~oracledb.init_oracle_client()` in the application as shown in
-  sections below.
-
-- If you are changing from the default Thin mode, then refer to :ref:`featuresummary`
-  and :ref:`driverdiff` for other changes that may be needed.
-
-- If you are upgrading a cx_Oracle application to python-oracledb, then refer
-  to :ref:`upgrading83` for other changes that may be needed.
+The Thick mode is enabled by calling :func:`~oracledb.init_oracle_client()` in
+the application as shown in sections below.
 
 .. note::
 
@@ -44,6 +36,13 @@ The Thick mode is enabled by:
     Once the Thick mode is enabled, all connections will be in Thick mode and you
     cannot go back to Thin mode.
 
+If you are changing from the default Thin mode, then refer to
+:ref:`featuresummary` and :ref:`driverdiff` for other changes that may be
+needed.
+
+If you are upgrading a cx_Oracle application to python-oracledb, then refer to
+:ref:`upgrading83` for other changes that may be needed.
+
 You can validate the python-oracledb mode by querying the ``CLIENT_DRIVER``
 column of ``V$SESSION_CONNECT_INFO`` and verifying if the value of the column
 begins with ``python-oracledb thk``. See :ref:`vsessconinfo`.
@@ -223,12 +222,15 @@ Linux, you might use::
 Using oracledb.init_oracle_client() to set the Oracle Client directory
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
-Applications must call the function :meth:`oracledb.init_oracle_client()` to
-specify the directory containing Oracle Instant Client libraries.  The Oracle
-Client Libraries are loaded when ``init_oracle_client()`` is called.  For
-example, if the Oracle Instant Client Libraries are in
+Oracle Client Libraries are loaded when :meth:`oracledb.init_oracle_client()`
+is called.  In some environments, applications can use the ``lib_dir``
+parameter to specify the directory containing the Oracle Client libraries.
+Otherwise, the system library search path should contain the relevant library
+directory before Python is invoked.
+
+For example, if the Oracle Instant Client Libraries are in
 ``C:\oracle\instantclient_19_9`` on Windows or
-``$HOME/Downloads/instantclient_19_8`` on macOS, then you can use:
+``$HOME/Downloads/instantclient_19_8`` on macOS (Intel x86), then you can use:
 
 .. code-block:: python
 
@@ -237,7 +239,7 @@ example, if the Oracle Instant Client Libraries are in
     import platform
 
     d = None  # default suitable for Linux
-    if platform.system() == "Darwin":
+    if platform.system() == "Darwin" and platform.machine() == "x86_64":
         d = os.environ.get("HOME")+"/Downloads/instantclient_19_8")
     elif platform.system() == "Windows":
         d = r"C:\oracle\instantclient_19_14"
@@ -409,7 +411,7 @@ The `oraaccess.xml` file has other uses including:
 
 - Changing the value of Fast Application Notification :ref:`FAN <fan>` events which affects notifications and Runtime Load Balancing (RLB).
 - Configuring `Client Result Caching <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-D2FA7B29-301B-4AB8-8294-2B1B015899F9>`__ parameters
-- Turning on `Client Statement Cache Auto-tuning <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&d=GUID-6E21AA56-5BBE-422A-802C-197CAC8AAEA4>`__
+- Turning on `Client Statement Cache Auto-tuning <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-75169FE4-DE2C-431F-BBA7-3691C7C33360>`__
 
 Refer to the documentation on `oraaccess.xml
 <https://www.oracle.com/pls/topic/lookup?

Diff for: doc/src/user_guide/installation.rst

@@ -86,7 +86,7 @@ quickly.
 4. In your integrated development environment (IDE) or terminal window, set
    the three environment variables used by the test program.
 
-  Simple :ref:`connection <connhandling>` to the database requires an Oracle
+  A simple :ref:`connection <connhandling>` to the database requires an Oracle
   Database `user name and password
   <https://www.youtube.com/watch?v=WDJacg0NuLo>`_ and a database
   :ref:`connection string <connstr>`. Set the environment variables to your
@@ -414,7 +414,7 @@ Installing python-oracledb on Windows
 Install python-oracledb
 ------------------------
 
-Use Python's `Pip <https://pip.readthedocs.io/en/latest/installing/>`__ package
+Use Python's `pip <https://pip.pypa.io/en/latest/installation/>`__ package
 to install python-oracledb from Python's package repository `PyPI
 <https://pypi.org/project/oracledb/>`__::
 
@@ -587,7 +587,7 @@ architectures.
 Install python-oracledb
 -----------------------
 
-Use Python's `Pip <https://pip.readthedocs.io/en/latest/installing/>`__ package
+Use Python's `pip <https://pip.pypa.io/en/latest/installation/>`__ package
 to install python-oracledb from Python's package repository `PyPI
 <https://pypi.org/project/oracledb/>`__:
 

Diff for: doc/src/user_guide/introduction.rst

@@ -15,20 +15,20 @@ information, see :ref:`upgrading83`.
 
 Python-oracledb is typically installed from Python's package repository
 `PyPI <https://pypi.org/project/oracledb/>`__ using `pip
-<https://pip.pypa.io/en/latest/installing/>`__. See :ref:`installation` for
+<https://pip.pypa.io/en/latest/installation/>`__. See :ref:`installation` for
 more information.
 
 Architecture
 ============
 
-The python-oracledb driver can run in either the Thin mode or Thick mode,
-which is determined by an application setting.
+Python-oracledb is a 'Thin' driver with an optional 'Thick' mode enabled by an
+application setting.
 
 python-oracledb Thin Mode Architecture
 --------------------------------------
 
-By default, python-oracledb runs in a 'Thin' mode which connects directly to
-Oracle Database 12.1 or later.  This mode does not need Oracle Client libraries.
+By default, python-oracledb allows connecting directly to Oracle Database 12.1
+or later.  This Thin mode does not need Oracle Client libraries.
 
 .. _thinarchfig:
 .. figure:: /images/python-oracledb-thin-arch.png
@@ -48,9 +48,9 @@ The Oracle Net behavior can optionally be configured by using a
 python-oracledb Thick Mode Architecture
 ---------------------------------------
 
-Python-oracledb is said to be in 'Thick' mode when Oracle Client libraries are
-used.  An application script runtime option enables this mode by loading the
-libraries, see :ref:`enablingthick`.  This gives you some :ref:`additional
+Python-oracledb is said to be in 'Thick' mode when it links with Oracle Client
+libraries.  An application script runtime option enables this mode by loading
+the libraries, see :ref:`enablingthick`.  This gives you some :ref:`additional
 functionality <featuresummary>`. Depending on the version of the Oracle Client
 libraries, this mode of python-oracledb can connect to Oracle Database 9.2 or
 later.
@@ -99,7 +99,7 @@ The python-oracledb feature highlights are:
 
     *   Easy installation from PyPI
     *   Support for multiple Oracle Database versions
-    *   Works with common frameworks and ORMs
+    *   Supports the `Python Database API v2.0 Specification <https://www.python.org/dev/peps/pep-0249/>`__ with a considerable number of additions and a couple of exclusions.    *   Works with common frameworks and ORMs
     *   Execution of SQL and PL/SQL statements
     *   Extensive Oracle data type support, including JSON, large objects (``CLOB`` and
         ``BLOB``) and binding of SQL objects
@@ -123,5 +123,5 @@ Runnable examples are in the `GitHub samples directory
 <https://github.com/oracle/python-oracledb/tree/main/samples>`__.
 A tutorial `Python and Oracle Database Tutorial: The New Wave of Scripting
 <https://oracle.github.io/python-oracledb
-/samples/tutorial/Python-and-Oracle-Database-Scripting-for-the-Future.html>`__
+/samples/tutorial/Python-and-Oracle-Database-The-New-Wave-of-Scripting.html>`__
 is also available.