Add glossary and disambiguate cabal vs Cabal

doc/cabal-commands.rst

@@ -258,7 +258,7 @@ cabal user-config
 
 ``cabal user-config [init|diff|update]`` prints and updates user's global
 cabal preferences. It is very useful when you are e.g. first configuring
-``cabal`` on a new machine.
+:term:`cabal` on a new machine.
 
 - ``cabal user-config init`` creates a new configuration file.
 
@@ -288,7 +288,7 @@ cabal preferences. It is very useful when you are e.g. first configuring
 cabal path
 ^^^^^^^^^^
 
-``cabal path`` allows to query for paths used by ``cabal``.
+``cabal path`` allows to query for paths used by :term:`cabal`.
 For example, it allows to query for the directories of the cache, store,
 installed binaries, and so on.
 
@@ -695,7 +695,7 @@ Examples:
     Read dependency version bounds from the v2-style freeze file
     (by default, ``cabal.project.freeze``) instead of the package
     description file. ``--new-freeze-file`` is an alias for this flag
-    that can be used with pre-2.4 ``cabal``.
+    that can be used with pre-2.4 :term:`cabal`.
 
 .. option:: --project-file=FILE
 
@@ -796,8 +796,8 @@ symlinks/copies their executables in ``installdir`` (usually ``~/.local/bin``).
   than ``all`` as the target. To overwrite an installation, use
   ``--overwrite-policy=always`` as the default policy is ``never``.
 
-For example this command will build the latest ``cabal-install`` and symlink
-its ``cabal`` executable:
+For example this command will build the latest :term:`cabal-install:exe:cabal` and symlink
+its :term:`cabal` executable:
 
 ::
 
@@ -806,7 +806,7 @@ its ``cabal`` executable:
 In addition, it's possible to use ``cabal install`` to install components
 of a local project. For example, with an up-to-date Git clone of the Cabal
 repository, this command will build cabal-install HEAD and symlink the
-``cabal`` executable:
+:term:`cabal` executable:
 
 ::
 

doc/cabal-context.rst

@@ -5,7 +5,7 @@ Haskell_ software. It helps people to
 configure, build and install Haskell software and to distribute it
 easily to other users and developers.
 
-There is a command line tool called ``cabal`` for working with Cabal
+There is a command line tool called :term:`cabal` for working with Cabal
 packages. It helps with installing existing packages and also helps
 people developing their own packages. It can be used to work with local
 packages or to install packages from online package archives, including
@@ -52,7 +52,7 @@ other Haskell implementations).
 A tool for working with packages
 --------------------------------
 
-There is a command line tool, called "``cabal``", that users and
+There is a command line tool, called ":term:`cabal`", that users and
 developers can use to build and install Cabal packages. It can be used
 for both local packages and for packages available remotely over the
 network. It can automatically install Cabal packages plus any other
@@ -76,7 +76,7 @@ It is also possible to install several local packages at once, e.g.
     $ cabal install foo/ bar/
 
 Developers and users can use the tool to install packages from remote
-Cabal package archives. By default, the ``cabal`` tool is configured to
+Cabal package archives. By default, the :term:`cabal` tool is configured to
 use the central Haskell package archive called
 Hackage_ but it is possible to use it
 with any other suitable archive.
@@ -102,7 +102,7 @@ which Haskell implementation to use and whether to build optimised code
 or build with the ability to profile code. It is not expected that users
 will have to modify any of the information in the ``.cabal`` file.
 
-Note that ``cabal`` is not the only tool for working with Cabal
+Note that :term:`cabal` is not the only tool for working with Cabal
 packages. Due to the standardised format and a library for reading
 ``.cabal`` files, there are several other special-purpose tools.
 
@@ -134,7 +134,7 @@ Cabal and its associated tools and websites covers:
 -  packaging for distribution
 -  automated package management
 
-   -  natively using the ``cabal`` command line tool; or
+   -  natively using the :term:`cabal` command line tool; or
    -  by translation into native package formats such as RPM or deb
 
 -  web and local Cabal package archives

doc/cabal-package-description-file.rst

@@ -353,7 +353,7 @@ describe the package as a whole:
     what syntax to expect and what each part means.
 
     The version number you specify will affect both compatibility and
-    behaviour. Most tools (including the Cabal library and the ``cabal``
+    behaviour. Most tools (including the Cabal library and the :term:`cabal`
     program) understand a range of versions of the Cabal specification.
     Older tools will of course only work with older versions of the
     Cabal specification that was known at the time. Most of the time,
@@ -429,7 +429,7 @@ describe the package as a whole:
 
     If the build type is anything other than ``Custom``, then the
     ``Setup.hs`` file *must* be exactly the standardized content
-    discussed below. This is because in these cases, ``cabal`` will
+    discussed below. This is because in these cases, :term:`cabal` will
     ignore the ``Setup.hs`` file completely, whereas other methods of
     package management, such as ``runhaskell Setup.hs [CMD]``, still
     rely on the ``Setup.hs`` file.
@@ -467,7 +467,7 @@ describe the package as a whole:
         main = defaultMain
 
     For build type ``Custom``, the file ``Setup.hs`` can be customized,
-    and will be used both by ``cabal`` and other tools.
+    and will be used both by :term:`cabal` and other tools.
 
     For most packages, the build type ``Simple`` is sufficient. For more exotic
     needs, the ``Hooks`` build type is recommended; see :ref:`setup-hooks`.

doc/cabal-project-description-file.rst

@@ -42,7 +42,7 @@ directories when there is none in the current directory.
 Conditionals and imports
 ------------------------
 
-As of ``cabal-install`` version 3.8, cabal supports conditional logic and
+As of :term:`cabal-install:exe:cabal` version 3.8, cabal supports conditional logic and
 imports in ``cabal.project`` files.
 
     .. warning::
@@ -92,7 +92,7 @@ You *must* provide a non-empty list of local packages in your project, filling
 out either a ``packages`` field or an ``optional-packages`` field or both to
 satisfy this requirement.
 
-When ``cabal.project`` doesn't exist, ``cabal-install`` fabricates an ephemeral
+When ``cabal.project`` doesn't exist, :term:`cabal-install:exe:cabal` fabricates an ephemeral
 project for its own use with this simple content, a glob that will find any (but
 expects to find one) package in the current directory:
 
@@ -315,7 +315,7 @@ package, and thus apply globally:
 
     :default: 1
 
-    Control the verbosity of ``cabal`` commands, valid values are from 0
+    Control the verbosity of :term:`cabal` commands, valid values are from 0
     to 3.
 
     The command line variant of this field is ``--verbose=2``; a short
@@ -346,7 +346,7 @@ package, and thus apply globally:
     This option instructs cabal to control parallelism by creating a new system semaphore,
     whose number of tokens is specified by ``--jobs`` (or ``-j``).
     This semaphore is passed to GHC, which allows it to use any leftover parallelism
-    that ``cabal-install`` is not using.
+    that :term:`cabal-install:exe:cabal` is not using.
 
     Requires ``ghc >= 9.8``.
 
@@ -420,9 +420,9 @@ package, and thus apply globally:
     :since: 3.7
 
     By modifying ``package-dbs`` you can modify the default package environment
-    which ``cabal`` will see. The package databases you add using ``package-dbs``
+    which :term:`cabal` will see. The package databases you add using ``package-dbs``
     will not be written into and only used as immutable package stores to initialise
-    the environment with additional packages that ``cabal`` can choose to use.
+    the environment with additional packages that :term:`cabal` can choose to use.
 
     There are three package databases involved with most builds:
 

doc/config.rst

@@ -6,11 +6,11 @@ Configuration
 Overview
 --------
 
-The global configuration file for ``cabal-install`` is by default
-``$XDG_CONFIG_HOME/cabal/config``. If you do not have this file, ``cabal`` will create
+The global configuration file for :term:`cabal-install:exe:cabal` is by default
+``$XDG_CONFIG_HOME/cabal/config``. If you do not have this file, :term:`cabal` will create
 it for you on the first call to ``cabal update``
 (details see `configuration file discovery`_).
-Alternatively, you can explicitly ask ``cabal`` to create it for you using
+Alternatively, you can explicitly ask :term:`cabal` to create it for you using
 
 .. code-block:: console
 
@@ -40,21 +40,21 @@ executables by default, you would change this line to
     executable-stripping: False
 
 You can also use ``cabal user-config update`` to migrate configuration
-files created by older versions of ``cabal``.
+files created by older versions of :term:`cabal`.
 
 Environment variables
 ---------------------
 
-Various environment variables affect ``cabal-install``.
+Various environment variables affect :term:`cabal-install:exe:cabal`.
 
 ``CABAL_CONFIG``
    The variable to find global configuration file.
 
 ``CABAL_DIR``
 
-   If set, *all* ``cabal-install`` content files will be stored as
+   If set, *all* :term:`cabal-install:exe:cabal` content files will be stored as
    subdirectories of this directory, including the configuration file
-   if ``CABAL_CONFIG`` is unset.  If ``CABAL_DIR`` is unset, Cabal
+   if ``CABAL_CONFIG`` is unset.  If ``CABAL_DIR`` is unset, :term:`cabal`
    will store data files according to the XDG Base Directory
    Specification (see `directories`_).
 
@@ -63,7 +63,7 @@ Various environment variables affect ``cabal-install``.
        For backwards compatibility, if the directory ``~/.cabal`` on
        Unix or ``%APPDATA%\cabal`` on Windows exists, and
        ``$XDG_CONFIG_HOME/cabal/config`` does not exist, and
-       ``CABAL_DIR`` is unset, ``cabal-install`` will behave as if
+       ``CABAL_DIR`` is unset, :term:`cabal-install:exe:cabal` will behave as if
        ``CABAL_DIR`` was set to point at this directory.
 
 ``CABAL_BUILDDIR``
@@ -87,7 +87,7 @@ The configuration file location is determined as follows:
 
 If the configuration file does not exist, and it was not given
 explicitly via ``--config-file`` or ``$CABAL_CONFIG``, then
-``cabal-install`` will generate the default one, with directories
+:term:`cabal-install:exe:cabal` will generate the default one, with directories
 based on ``$CABAL_DIR`` (if set) or according to the XDG Base
 Directory Specification, as listed below.
 
@@ -121,13 +121,13 @@ file:
 * ``~/.local/bin`` for executables installed with ``cabal install``.
 
 You can run ``cabal path`` to see a list of the directories that
-``cabal`` will use with the active configuration.
+:term:`cabal` will use with the active configuration.
 
 Repository specification
 ------------------------
 
 An important part of the configuration is the specification of the
-repository. When ``cabal`` creates a default config file, it configures
+repository. When :term:`cabal` creates a default config file, it configures
 the repository to be the central Hackage server:
 
 ::
@@ -140,7 +140,7 @@ anything; packages downloaded from this repository will be cached under
 ``$XDG_CACHE_HOME/cabal/packages/hackage.haskell.org`` (or whatever name you specify;
 you can change the prefix by changing the value of
 :cfg-field:`remote-repo-cache`). If you want, you can configure multiple
-repositories, and ``cabal`` will combine them and be able to download
+repositories, and :term:`cabal` will combine them and be able to download
 packages from any of them.
 
 Using secure repositories
@@ -166,21 +166,21 @@ The ``<root-key-IDs>`` and ``<key-threshold>`` values are used for
 bootstrapping. As part of the TUF infrastructure the repository will
 contain a file ``root.json`` (for instance,
 http://hackage.haskell.org/root.json) which the client needs to do
-verification. However, how can ``cabal`` verify the ``root.json`` file
+verification. However, how can :term:`cabal` verify the ``root.json`` file
 *itself*? This is known as bootstrapping: if you specify a list of root
-key IDs and a corresponding threshold, ``cabal`` will verify that the
+key IDs and a corresponding threshold, :term:`cabal` will verify that the
 downloaded ``root.json`` file has been signed with at least
 ``<key-threshold>`` keys from your set of ``<root-key-IDs>``.
 
 You can, but are not recommended to, omit these two fields. In that case
-``cabal`` will download the ``root.json`` field and use it without
+:term:`cabal` will download the ``root.json`` field and use it without
 verification. Although this bootstrapping step is then unsafe, all
 subsequent access is secure (provided that the downloaded ``root.json``
 was not tampered with). Of course, adding ``root-keys`` and
 ``key-threshold`` to your repository specification only shifts the
 problem, because now you somehow need to make sure that the key IDs you
 received were the right ones. How that is done is however outside the
-scope of ``cabal`` proper.
+scope of :term:`cabal` proper.
 
 More information about the security infrastructure can be found at
 https://github.com/haskell/hackage-security.
@@ -196,7 +196,7 @@ repository.
     repository my-local-repository
       url: file+noindex:///absolute/path/to/directory
 
-``cabal`` will construct the index automatically from the
+:term:`cabal` will construct the index automatically from the
 ``package-name-version.tar.gz`` files in the directory, and will use optional
 corresponding ``package-name-version.cabal`` files as new revisions.
 
@@ -208,7 +208,7 @@ For example, if ``/absolute/path/to/directory`` looks like
         bar-0.2.0.0.tar.gz
         bar-0.2.0.0.cabal
 
-then ``cabal`` will create an index with two packages:
+then :term:`cabal` will create an index with two packages:
 
 - ``foo-0.1.0.0`` using the source and ``.cabal`` file inside
   ``foo-0.1.0.0.tar.gz``
@@ -221,7 +221,7 @@ then the cache will be stored inside the :cfg-field:`remote-repo-cache` director
 The part of the path will be used to determine the cache key part.
 
 .. note::
-    ``cabal-install`` creates a ``.cache`` file, and will aggressively use
+    :term:`cabal-install:exe:cabal` creates a ``.cache`` file, and will aggressively use
     its contents if it exists. Therefore if you change the contents of
     the directory, remember to wipe the cache too.
 
@@ -256,13 +256,13 @@ thus, looks similar to a ``package-name.cabal``'s ``build-depends`` section.
     certain versions or marking a specific version as deprecated. To achieve this, add a
     local no-index repository to your :ref:`configuration file <config-file-discovery>`,
     where the directory contains your custom
-    ``preferred-versions``. After running ``cabal update``, all ``cabal`` operations will honour the
+    ``preferred-versions``. After running ``cabal update``, all :term:`cabal` operations will honour the
     configuration.
 
 Legacy repositories
 ^^^^^^^^^^^^^^^^^^^
 
-Currently ``cabal`` supports single kind of “legacy” repositories.
+Currently :term:`cabal` supports single kind of “legacy” repositories.
 It is specified using
 
 ::
@@ -303,8 +303,8 @@ can be used to create and manage such repositories.
 Program options
 ---------------
 
-Programs that ``cabal`` knows about can be provided with options that will be
-passed in whenever the program is invoked by ``cabal``. The configuration file
+Programs that :term:`cabal` knows about can be provided with options that will be
+passed in whenever the program is invoked by :term:`cabal`. The configuration file
 can contain a stanza of ``program-default-options`` with ``<prog>-options``
 fields to specify these.
 
@@ -379,11 +379,11 @@ The list of known programs is:
 
 .. warning::
 
-  These options will be used when ``cabal`` invokes the tool as part of the build process or as part of a
+  These options will be used when :term:`cabal` invokes the tool as part of the build process or as part of a
   :pkg-field:`build-tool-depends` declaration, not whenever the tool is invoked by
   third parties.
 
-  In particular this means that for example ``gcc-options`` will be used when ``cabal``
+  In particular this means that for example ``gcc-options`` will be used when :term:`cabal`
   invokes ``gcc``, which is **not** when C sources are compiled by GHC (even though GHC
   might invoke ``gcc`` internally). In order to provide options through GHC for those programs, one has to check the
   GHC User guide's `Section <https://downloads.haskell.org/ghc/latest/docs/users_guide/phases.html#forcing-options-to-a-particular-phase>`_.

doc/external-commands.rst

@@ -1,22 +1,22 @@
 External Commands
 =================
 
-``cabal-install`` provides a system for external commands, akin to the ones used by tools like ``git`` or ``cargo``.
+:term:`cabal-install:exe:cabal` provides a system for external commands, akin to the ones used by tools like ``git`` or ``cargo``.
 
-If you execute ``cabal <cmd>``, ``cabal-install`` will search the path for an executable named ``cabal-<cmd>`` and execute it. The name of the command is passed as the first argument and
+If you execute ``cabal <cmd>``, :term:`cabal-install:exe:cabal` will search the path for an executable named ``cabal-<cmd>`` and execute it. The name of the command is passed as the first argument and
 the remaining arguments are passed afterwards. An error will be thrown in case the custom command is not found. The exit code of cabal when calling an external command is the same as the exit code
 of the command.
 
-The ``$CABAL`` environment variable is set to the path of the ``cabal-install`` executable
+The ``$CABAL`` environment variable is set to the path of the :term:`cabal-install:exe:cabal` executable
 which invoked the subcommand.
 
 It is strongly recommended that you implement your custom commands by calling the
 CLI via the ``$CABAL`` variable rather than linking against the ``Cabal`` library.
 There is no guarantee that the subcommand will link against the same version of the
-``Cabal`` library as ``cabal-install`` so it would lead to unexpected results and
+``Cabal`` library as :term:`cabal-install:exe:cabal` so it would lead to unexpected results and
 incompatibilities.
 
-``cabal-install`` can also display the help message of the external command.
+:term:`cabal-install:exe:cabal` can also display the help message of the external command.
 When ``cabal help <cmd>`` is invoked, then ``cabal-<cmd> <cmd> --help`` will be called so
 your external command can display a help message.