Commit 8dfce868 authored by Herbert Valerio Riedel's avatar Herbert Valerio Riedel 🕺

docs: Add detached refs for common external refs

While at it, I updated a few urls I noticed to be outdated.

This is somewhat related to #3791

[skip ci]
parent 73ad558e
......@@ -27,7 +27,7 @@ extra-source-files:
doc/conf.py doc/config-and-install.rst doc/developing-packages.rst
doc/images/Cabal-dark.png doc/index.rst doc/installing-packages.rst
doc/intro.rst doc/misc.rst doc/nix-local-build-overview.rst
doc/nix-local-build.rst doc/README.md
doc/nix-local-build.rst doc/README.md doc/references.inc
-- Generated with 'misc/gen-extra-source-files.sh'
-- Do NOT edit this section manually; instead, run the script.
......
......@@ -26,6 +26,8 @@ extlinks = {
'ghc-wiki': ('http://ghc.haskell.org/trac/ghc/wiki/%s', ''),
'ghc-ticket': ('http://ghc.haskell.org/trac/ghc/ticket/%s', 'GHC #'),
'hackage-pkg': ('http://hackage.haskell.org/package/%s', ''),
}
# General information about the project.
......
......@@ -712,13 +712,12 @@ with names ending in "``.hs``" or "``.lhs``", or to inputs for various
Haskell preprocessors. The simple build infrastructure understands the
extensions:
- ``.gc``
(`greencard <http://hackage.haskell.org/package/greencard>`__)
- ``.chs`` (`c2hs <http://www.cse.unsw.edu.au/~chak/haskell/c2hs/>`__)
- ``.hsc`` (``hsc2hs``)
- ``.y`` and ``.ly`` (`happy <http://www.haskell.org/happy/>`__)
- ``.x`` (`alex <http://www.haskell.org/alex/>`__)
- ``.cpphs`` (`cpphs <http://projects.haskell.org/cpphs/>`__)
- ``.gc`` (:hackage-pkg:`greencard`)
- ``.chs`` (:hackage-pkg:`c2hs`)
- ``.hsc`` (:hackage-pkg:`hsc2hs`)
- ``.y`` and ``.ly`` (happy_)
- ``.x`` (alex_)
- ``.cpphs`` (cpphs_)
When building, Cabal will automatically run the appropriate preprocessor
and compile the Haskell module it produces. For the ``c2hs`` and
......@@ -884,13 +883,12 @@ describe the package as a whole:
For library packages, this field is used as prologue text by
```setup haddock`` <installing-packages.html#setup-haddock>`__, and
thus may contain the same markup as
`haddock <http://www.haskell.org/haddock/>`__ documentation
thus may contain the same markup as Haddock_ documentation
comments.
``category:`` *freeform*
A classification category for future use by the package catalogue
`Hackage <http://hackage.haskell.org/>`__. These categories have not
Hackage_. These categories have not
yet been specified, but the upper levels of the module hierarchy
make a good start.
``tested-with:`` *compiler list*
......@@ -1070,8 +1068,7 @@ Generating dependency version bounds
""""""""""""""""""""""""""""""""""""
Cabal also has the ability to suggest dependency version bounds that
conform to `Package Versioning
Policy <https://wiki.haskell.org/Package_versioning_policy>`__, which is
conform to `Package Versioning Policy`_, which is
a recommended versioning system for publicly released Cabal packages.
This is done by running the ``gen-bounds`` command:
......@@ -1391,8 +1388,7 @@ system-dependent values for these fields.
Dependencies like ``foo >= 1.2.3 && < 1.3`` turn out to be very
common because it is recommended practise for package versions to
correspond to API versions (see
`PVP <https://wiki.haskell.org/Package_versioning_policy>`__).
correspond to API versions (see PVP_).
Since Cabal 1.6, there is a special wildcard syntax to help with
such ranges
......@@ -1405,7 +1401,7 @@ system-dependent values for these fields.
``foo >= 1.2 && < 1.3``.
Starting with Cabal 2.0, there's a new syntactic sugar to support
`PVP <https://wiki.haskell.org/Package_versioning_policy>`__-style
PVP_-style
major upper bounds conveniently, and is inspired by similiar
syntactic sugar found in other language ecosystems where it's often
called the "Caret" operator:
......@@ -2159,7 +2155,7 @@ Accessing the package version
The aforementioned auto generated ``Paths_``\ *pkgname* module also
exports the constant ``version ::``
`Version <http://hackage.haskell.org/packages/archive/base/latest/doc/html/Data-Version.html>`__
`Version <http://hackage.haskell.org/package/base/docs/Data-Version.html>`__
which is defined as the version of your package as specified in the
``version`` field.
......@@ -2340,7 +2336,7 @@ preprocessor.
Cabal also allows to detect when the source code is being used for
generating documentation. The ``__HADDOCK_VERSION__`` macro is defined
only when compiling via `haddock <http://www.haskell.org/haddock/>`__
only when compiling via Haddock_
instead of a normal Haskell compiler. The value of the
``__HADDOCK_VERSION__`` macro is defined as ``A*1000 + B*10 + C``, where
``A.B.C`` is the Haddock version. This can be useful for working around
......@@ -2422,3 +2418,6 @@ a few options:
packages <installing-packages.html>`__, and you may use the Cabal
library for all or part of the work. One option is to copy the source
of ``Distribution.Simple``, and alter it for your needs. Good luck.
.. include:: references.inc
......@@ -139,8 +139,7 @@ recommended instead to use a *secure* local repository:
key-threshold: <key-threshold>
The layout of these secure local repos matches the layout of remote
repositories exactly; the
`hackage-repo-tool <http://hackage.haskell.org/package/hackage-repo-tool>`__
repositories exactly; the :hackage-pkg:`hackage-repo-tool`
can be used to create and manage such repositories.
Building and installing packages
......@@ -201,7 +200,7 @@ Installing packages from Hackage
--------------------------------
The ``cabal`` tool also can download, configure, build and install a
`Hackage <http://hackage.haskell.org/>`__ package and all of its
Hackage_ package and all of its
dependencies in a single step. To do this, run:
::
......@@ -209,7 +208,7 @@ dependencies in a single step. To do this, run:
cabal install [PACKAGE...]
To browse the list of available packages, visit the
`Hackage <http://hackage.haskell.org/>`__ web site.
Hackage_ web site.
Developing with sandboxes
-------------------------
......@@ -243,9 +242,8 @@ To initialise a fresh sandbox in the current directory, run
It can be useful to make a source package available for installation in
the sandbox - for example, if your package depends on a patched or an
unreleased version of a library. This can be done with the
``cabal sandbox add-source`` command - think of it as "local
`Hackage <http://hackage.haskell.org/>`__". If an add-source dependency
is later modified, it is reinstalled automatically.
``cabal sandbox add-source`` command - think of it as "local Hackage_".
If an add-source dependency is later modified, it is reinstalled automatically.
.. code-block:: bash
......@@ -1146,27 +1144,24 @@ This command takes the following options:
setup haddock
-------------
Build the documentation for the package using
`haddock <http://www.haskell.org/haddock/>`__. By default, only the
documentation for the exposed modules is generated (but see the
``--executables`` and ``--internal`` flags below).
Build the documentation for the package using Haddock_.
By default, only the documentation for the exposed modules is generated
(but see the ``--executables`` and ``--internal`` flags below).
This command takes the following options:
``--hoogle``
Generate a file ``dist/doc/html/``\ *pkgid*\ ``.txt``, which can be
converted by `Hoogle <http://www.haskell.org/hoogle/>`__ into a
database for searching. This is equivalent to running
`haddock <http://www.haskell.org/haddock/>`__ with the ``--hoogle``
flag.
converted by Hoogle_ into a
database for searching. This is equivalent to running Haddock_
with the ``--hoogle`` flag.
``--html-location=``\ *url*
Specify a template for the location of HTML documentation for
prerequisite packages. The substitutions (`see
listing <#paths-in-the-simple-build-system>`__) are applied to the
template to obtain a location for each package, which will be used
by hyperlinks in the generated documentation. For example, the
following command generates links pointing at
`Hackage <http://hackage.haskell.org/>`__ pages:
following command generates links pointing at Hackage_ pages:
setup haddock
--html-location='http://hackage.haskell.org/packages/archive/$pkg/latest/doc/html'
......@@ -1176,28 +1171,26 @@ This command takes the following options:
using the package tool (e.g. ``ghc-pkg``).
``--executables``
Also run `haddock <http://www.haskell.org/haddock/>`__ for the
modules of all the executable programs. By default
`haddock <http://www.haskell.org/haddock/>`__ is run only on the
exported modules.
Also run Haddock_ for the modules of all the executable programs. By default
Haddock_ is run only on the exported modules.
``--internal``
Run `haddock <http://www.haskell.org/haddock/>`__ for the all
Run Haddock_ for the all
modules, including unexposed ones, and make
`haddock <http://www.haskell.org/haddock/>`__ generate documentation
Haddock_ generate documentation
for unexported symbols as well.
``--css=``\ *path*
The argument *path* denotes a CSS file, which is passed to
`haddock <http://www.haskell.org/haddock/>`__ and used to set the
Haddock_ and used to set the
style of the generated documentation. This is only needed to
override the default style that
`haddock <http://www.haskell.org/haddock/>`__ uses.
Haddock_ uses.
``--hyperlink-source``
Generate `haddock <http://www.haskell.org/haddock/>`__ documentation
Generate Haddock_ documentation
integrated with
`HsColour <http://www.cs.york.ac.uk/fp/darcs/hscolour/>`__. First,
`HsColour <http://www.cs.york.ac.uk/fp/darcs/hscolour/>`__ is run to
generate colourised code. Then
`haddock <http://www.haskell.org/haddock/>`__ is run to generate
Haddock_ is run to generate
HTML documentation. Each entity shown in the documentation is linked
to its definition in the colourised code.
``--hscolour-css=``\ *path*
......@@ -1399,3 +1392,6 @@ This command takes the following option:
``--snapshot``
Append today's date (in "YYYYMMDD" format) to the version number for
the generated source package. The original package is unaffected.
.. include:: references.inc
Cabal is the standard package system for
`Haskell <http://www.haskell.org/>`__ software. It helps people to
Haskell_ software. It helps people to
configure, build and install Haskell software and to distribute it
easily to other users and developers.
......@@ -8,7 +8,7 @@ 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
automatically installing dependencies. By default it is configured to
use `Hackage <http://hackage.haskell.org/>`__ which is Haskell's central
use Hackage_ which is Haskell's central
package archive that contains thousands of libraries and applications in
the Cabal package format.
......@@ -76,7 +76,7 @@ It is also possible to install several local packages at once, e.g.
Developers and users can use the tool to install packages from remote
Cabal package archives. By default, the ``cabal`` tool is configured to
use the central Haskell package archive called
`Hackage <http://hackage.haskell.org/>`__ but it is possible to use it
Hackage_ but it is possible to use it
with any other suitable archive.
::
......@@ -193,3 +193,6 @@ possible for tools to install a package and all of its dependencies
automatically. It also makes it possible to translate (in a
mostly-automatically way) into another package format like RPM or deb
which also have automatic dependency resolution.
.. include:: references.inc
......@@ -54,8 +54,7 @@ Unstable command-line
Functions and Types
-------------------
The Cabal library follows the `Package Versioning
Policy <http://www.haskell.org/haskellwiki/Package_versioning_policy>`__.
The Cabal library follows the `Package Versioning Policy`_.
This means that within a stable major release, for example 1.2.x, there
will be no incompatible API changes. But minor versions increments, for
example 1.2.3, indicate compatible API additions.
......@@ -99,3 +98,6 @@ may contain more kinds of files so do not assume every file is a
``.cabal`` file. Incompatible revisions to the format would involve
bumping the name of the index file, i.e., ``00-index.tar.gz``,
``01-index.tar.gz`` etc.
.. include:: references.inc
......@@ -1136,10 +1136,9 @@ The following commands are equivalent to ones that would be passed when
running ``setup haddock``. (TODO: Where does the documentation get put.)
``haddock-hoogle:`` *boolean* (default: False)
Generate a text file which can be converted by
`Hoogle <http://www.haskell.org/hoogle/>`__ into a database for
searching. This is equivalent to running ``haddock`` with the
``--hoogle`` flag.
Generate a text file which can be converted by Hoogle_
into a database for searching. This is equivalent to running ``haddock``
with the ``--hoogle`` flag.
The command line variant of this flag is ``--hoogle`` (for the
``haddock`` command).
......@@ -1336,3 +1335,6 @@ Most users generally won't need these.
The command line variant of this field is
``--cabal-lib-version=1.24.0.1``.
.. include:: references.inc
.. -*- rst -*-
This file contains commonly used link-references
See also "extlinks" in conf.py
.. _`Package Versioning Policy`:
.. _PVP: http://pvp.haskell.org/
.. _Hackage: http://hackage.haskell.org/
.. _Haskell: http://www.haskell.org/
.. _Haddock: http://www.haskell.org/haddock/
.. _Alex: http://www.haskell.org/alex/
.. _Happy: http://www.haskell.org/happy/
.. _Hoogle: http://www.haskell.org/hoogle/
.. _cpphs: http://projects.haskell.org/cpphs/
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment