Replace link numbers with symbolic names.

This is more maintainable since easier to detect dead or confused links
through inspection.

Author: mboes

documentation.md

@@ -5,13 +5,13 @@ title: Documentation
 
 ### Cloud Haskell Platform
 
-This is the [*Cloud Haskell Platform*][1]. Cloud Haskell is a set of libraries
+This is the [*Cloud Haskell Platform*][cloud-haskell]. Cloud Haskell is a set of libraries
 that bring Erlang-style concurrency and distribution to Haskell programs. This
 project is an implementation of that distributed computing interface, where
 processes communicate with one another through explicit message passing rather
 than shared memory.
 
-Originally described by the joint [Towards Haskell in the Cloud][12] paper,
+Originally described by the joint [Towards Haskell in the Cloud][haskell11-ch] paper,
 Cloud Haskell has be re-written from the ground up and supports a rich and
 growing number of features for
 
@@ -23,23 +23,23 @@ growing number of features for
 * supporting *static* values (required for remote communication)
 
 There is a recent
-[presentation](http://sneezy.cs.nott.ac.uk/fun/2012-02/coutts-2012-02-28.pdf)
+[presentation][fun201202-coutts]
 on Cloud Haskell and this reimplementation, which is worth reading in conjunction
 with the documentation and wiki pages on this website..
 
 Cloud Haskell comprises the following components, some of which are complete,
 others experimental.
 
-* [distributed-process][2]: Base concurrency and distribution support
-* [distributed-process-platform][3]: The Cloud Haskell Platform - APIs
-* [distributed-static][4]: Support for static values
-* [rank1dynamic][5]: Like `Data.Dynamic` and `Data.Typeable` but supporting polymorphic values
-* [network-transport][6]: Generic `Network.Transport` API
-* [network-transport-tcp][7]: TCP realisation of `Network.Transport`
-* [network-transport-inmemory][8]: In-memory realisation of `Network.Transport` (incomplete) 
-* [network-transport-composed][9]: Compose two transports (very preliminary)
-* [distributed-process-simplelocalnet][10]: Simple backend for local networks
-* [distributed-process-azure][11]: Azure backend for Cloud Haskell (proof of concept)
+* [distributed-process][distributed-process]: Base concurrency and distribution support
+* [distributed-process-platform][distributed-process-platform]: The Cloud Haskell Platform - APIs
+* [distributed-static][distributed-static]: Support for static values
+* [rank1dynamic][rank1dynamic]: Like `Data.Dynamic` and `Data.Typeable` but supporting polymorphic values
+* [network-transport][network-transport]: Generic `Network.Transport` API
+* [network-transport-tcp][network-transport-tcp]: TCP realisation of `Network.Transport`
+* [network-transport-inmemory][network-transport-inmemory]: In-memory realisation of `Network.Transport` (incomplete) 
+* [network-transport-composed][network-transport-composed]: Compose two transports (very preliminary)
+* [distributed-process-simplelocalnet][distributed-process-simplelocalnet]: Simple backend for local networks
+* [distributed-process-azure][distributed-process-azure]: Azure backend for Cloud Haskell (proof of concept)
 
 One of Cloud Haskell's goals is to separate the transport layer from the
 *process layer*, so that the transport backend is entirely independent:
@@ -114,10 +114,10 @@ Haskell or C.
 
 ### Network Transport Abstraction Layer
 
-Cloud Haskell's generic [network-transport][6] API is entirely independent of
+Cloud Haskell's generic [network-transport][network-transport] API is entirely independent of
 the concurrency and messaging passing capabilities of the *process layer*.
 Cloud Haskell applications are built using the primitives provided by the
-*process layer* (i.e., [distributed-process][2]), which provides abstractions
+*process layer* (i.e., [distributed-process][distributed-process]), which provides abstractions
 such as nodes and processes. Applications must also depend on a Cloud Haskell
 Backend, which provides functions to allow the initialisation of the transport
 layer using whatever topology might be appropriate to the application.
@@ -160,7 +160,7 @@ of other `Network.Transport` APIs if required, but for the most part this
 is irrelevant and the application will interact with Cloud Haskell through
 the *Process Layer* and *Platform*.
 
-For more details about `Network.Transport` please see the [wiki page][20].
+For more details about `Network.Transport` please see the [wiki page](/wiki/networktransport.html).
 
 ### Concurrency and Distribution
 
@@ -169,7 +169,7 @@ distributed programming are exposed to application developers. This layer
 deals explicitly with 
 
 The core of Cloud Haskell's concurrency and distribution support resides in the
-[distributed-process][2] library. As well as the APIs necessary for starting
+[distributed-process][distributed-process] library. As well as the APIs necessary for starting
 nodes and forking processes on them, we find all the basic primitives required
 to
 
@@ -215,7 +215,7 @@ runProcess  :: LocalNode -> Process () -> IO ()
 {% endhighlight %}
 
 Once we've spawned some processes, they can communicate with one another
-using the messaging primitives provided by [distributed-processes][2],
+using the messaging primitives provided by [distributed-processes][distributed-processes],
 which are well documented in the haddocks.
 
 ### What is Serializable
@@ -272,7 +272,7 @@ need to spawn a process and send a bunch a messages to it, then wait for
 replies however; we can’t send a `ReceivePort` since it is not `Serializable`.
 
 `ReceivePort`s can be merged, so we can listen on several simultaneously. In the
-latest version of [distributed-process][2], we can listen for *regular* messages
+latest version of [distributed-process][distributed-process], we can listen for *regular* messages
 and multiple channels at the same time, using `matchChan` in the list of
 allowed matches passed `receiveWait` and `receiveTimeout`.
 
@@ -313,7 +313,7 @@ and decide whether to oblige or not.
 
 ### Rethinking the Task Layer
 
-[Towards Haskell in the Cloud][12] describes a multi-layered architecture, in
+[Towards Haskell in the Cloud][haskell11-ch] describes a multi-layered architecture, in
 which manipulation of concurrent processes and message passing between them
 is managed in the *process layer*, whilst a higher level API described as the
 *task layer* provides additional features such as
@@ -322,19 +322,19 @@ is managed in the *process layer*, whilst a higher level API described as the
 * data centric processing model
 * a promise (or *future*) abstraction, representing the result of a calculation that may or may not have yet completed
 
-The [distributed-process-platform][18] library implements parts of the
+The [distributed-process-platform][distributed-process-platform] library implements parts of the
 *task layer*, but takes a very different approach to that described
-in the original paper and implemented by the [remote][14] package. In particular,
+in the original paper and implemented by the [remote][remote] package. In particular,
 we diverge from the original design and defer to many of the principles
-defined by Erlang's [Open Telecom Platform][13], taking in some well established
+defined by Erlang's [Open Telecom Platform][OTP], taking in some well established
 Haskell concurrency design patterns along the way.
 
-In fact, [distributed-process-platform][18] does not really consider the
+In fact, [distributed-process-platform][distributed-process-platform] does not really consider the
 *task layer* in great detail. We provide an API comparable to remote's
 `Promise` in Control.Distributed.Process.Platform.Async. This API however,
-is derived from Simon Marlow's [Control.Concurrent.Async][19] package, and is not
+is derived from Simon Marlow's [Control.Concurrent.Async][async] package, and is not
 limited to blocking queries on `Async` handles in the same way. Instead our
-[API][17] handles both blocking and non-blocking queries, polling
+[API][d-p-platform-async] handles both blocking and non-blocking queries, polling
 and working with lists of `Async` handles. We also eschew throwing exceptions
 to indicate asynchronous task failures, instead handling *task* and connectivity
 failures using monitors. Users of the API need only concern themselves with the
@@ -391,7 +391,7 @@ Work is also underway to provide abstractions for managing asynchronous tasks
 at a higher level, focussing on workload distribution and load regulation.
 
 The kinds of task that can be performed by the async implementations in
-[distributed-process-platform][3] are limited only by their return type:
+[distributed-process-platform][distributed-process-platform] are limited only by their return type:
 it **must** be `Serializable` - that much should've been obvious by now.
 The type of asynchronous task definitions comes in two flavours, one for
 local nodes which require no remote-table or static serialisation dictionary,
@@ -430,14 +430,14 @@ domain was more *haskell-ish* than working with bare send and receive primitives
 The `Async` sub-package also provides a type safe interface for receiving data,
 although it is limited to running a computation and waiting for its result.
 
-The [Control.Distributed.Processes.Platform.ManagedProcess][21] API provides a
+The [Control.Distributed.Processes.Platform.ManagedProcess][d-p-platform-ManagedProcess] API provides a
 number of different abstractions that can be used to achieve similar benefits
 in your code. It works by introducing a standard protocol between your process
 and the *world outside*, which governs how to handle request/reply processing,
 exit signals, timeouts, sleeping/hibernation with `threadDelay` and even provides
 hooks that terminating processes can use to clean up residual state.
 
-The [API documentation][21] is quite extensive, so here we will simply point
+The [API documentation][d-p-platform-ManagedProcess] is quite extensive, so here we will simply point
 out the obvious differences. A process implemented with `ManagedProcess`
 can present a type safe API to its callers (and the server side code too!),
 although that's not its primary benefit. For a very simplified example:
@@ -489,8 +489,8 @@ API, which looks a lot like `Async` but manages exit signals in a single thread
 configurable task pools and task supervision strategy part of its API.
 
 More complex examples of the `ManagedProcess` API can be seen in the
-[Managed Processes tutorial][22]. API documentation for HEAD is available
-[here][21].
+[Managed Processes tutorial](tutorials/tutorial3.html). API documentation for HEAD is available
+[here][d-p-platform-ManagedProcess].
 
 ### Supervision Trees
 
@@ -500,25 +500,21 @@ TBC
 
 TBC
 
-[1]: http://haskell-distributed.github.io/documentation.html
-[2]: https://github.com/haskell-distributed/distributed-process
-[3]: https://github.com/haskell-distributed/distributed-process-platform
-[4]: http://hackage.haskell.org/package/distributed-static
-[5]: http://hackage.haskell.org/package/rank1dynamic
-[6]: http://hackage.haskell.org/package/network-transport
-[7]: http://hackage.haskell.org/package/network-transport-tcp
-[8]: https://github.com/haskell-distributed/network-transport-inmemory
-[9]: https://github.com/haskell-distributed/network-transport-composed
-[10]: http://hackage.haskell.org/package/distributed-process-simplelocalnet
-[11]: http://hackage.haskell.org/package/distributed-process-azure
-[12]: http://research.microsoft.com/en-us/um/people/simonpj/papers/parallel/remote.pdf
-[13]: http://en.wikipedia.org/wiki/Open_Telecom_Platform
-[14]: http://hackage.haskell.org/package/remote
-[15]: http://www.erlang.org/doc/design_principles/sup_princ.html
-[16]: http://www.erlang.org/doc/man/supervisor.html
-[17]: http://hackage.haskell.org/package/distributed-process-platform/Control-Distributed-Process-Platform-Async.html
-[18]: https://github.com/haskell-distributed/distributed-process-platform
-[19]: http://hackage.haskell.org/package/async
-[20]: /wiki/networktransport.html
-[21]: http://hackage.haskell.org/package/distributed-process-platform/Control-Distributed-Process-Platform-ManagedProcess.html
-[22]: /tutorials/tutorial3.html
+[cloud-haskell]: http://haskell-distributed.github.io/documentation.html
+[fun201202-coutts]: http://sneezy.cs.nott.ac.uk/fun/2012-02/coutts-2012-02-28.pdf
+[distributed-process]: https://github.com/haskell-distributed/distributed-process
+[distributed-process-platform]: https://github.com/haskell-distributed/distributed-process-platform
+[distributed-static]: http://hackage.haskell.org/package/distributed-static
+[rank1dynamic]: http://hackage.haskell.org/package/rank1dynamic
+[network-transport]: http://hackage.haskell.org/package/network-transport
+[network-transport-tcp]: http://hackage.haskell.org/package/network-transport-tcp
+[network-transport-inmemory]: https://github.com/haskell-distributed/network-transport-inmemory
+[network-transport-composed]: https://github.com/haskell-distributed/network-transport-composed
+[distributed-process-simplelocalnet]: http://hackage.haskell.org/package/distributed-process-simplelocalnet
+[distributed-process-azure]: http://hackage.haskell.org/package/distributed-process-azure
+[haskell11-ch]: http://research.microsoft.com/en-us/um/people/simonpj/papers/parallel/remote.pdf
+[OTP]: http://en.wikipedia.org/wiki/Open_Telecom_Platform
+[remote]: http://hackage.haskell.org/package/remote
+[d-p-platform-async]: http://hackage.haskell.org/package/distributed-process-platform/Control-Distributed-Process-Platform-Async.html
+[async]: http://hackage.haskell.org/package/async
+[d-p-platform-ManagedProcess]: http://hackage.haskell.org/package/distributed-process-platform/Control-Distributed-Process-Platform-ManagedProcess.html