A stanza for a platform library looks something like

    platform-library test-package
      type:                native-shared

      if os(Windows)
        options: standalone
        mod-def-file: TestPackage.def

      other-modules:       MyPlatformLib.Hello
                           MyPlatformLib.SomeBindings
      build-depends:       base >=4.7 && <4.9
      hs-source-dirs:      src
      c-sources:           csrc/MyPlatformLibWrapper.c
      default-language:    Haskell2010

where native-shared means that we want to build a native shared library
(.so on Linux, .dylib on OSX, .dll on Windows). The parser also
recognizes native-static but this is not currently supported anywhere.
The standalone option means that the we merge all library dependencies
into the dynamic library (i.e., ghc options -shared -static), rather
than make the created dynamic library just record its dependencies (ghc
options -shared -dynamic); it is currently compulsory on Windows and
unsupported anywhere else. The mod-def-file can be used to specify a
module definition file, and is also Windows specific.

There is a bit of refactoring in Build: gbuild is the old buildOrReplExe
and now deals with both executables and platform libraries.

`--dynlibdir` indicates the directory in which dynamic libraries
are installed. By default this setting is equal to:

`$libdir/$abi`

The static libraries will still end up in:

`$libdir/$libsubdir`

With `$libsubdir/$abi` as the default directory for dynamic
libraries, dynamic libraries will by default end up in a
single shared directory (per package database). This has the
potential to reduce start-up times for dynamically linked
executable as only one RPATH per package database will be
needed.

This commit uses the functionality defined in

https://phabricator.haskell.org/D2611

to tell GHC's > 8.0.1 package database that dynamic libraries
are copied to the directories mentioned in the

`dynamic-library-dirs`

field.

[ci skip]

Is now rendered as object description, and can have attached meta.

[ci skip]

And also how reference page is build

[ci skip]

Reference index shows fields and flags for project.cabal and fields for
pkgname.cabal

[ci skip]

[ci skip]

[ci skip]

It features simple `pkg-section` directive for marking sections for
which subsequent `pkg-field` fields are defined. Needed to disambiguate
fields such as `type` or `main-is`.

Converted most of `developing-packages.rst` to use new directives

Future work:

* Add directives for describing project.local, make it reference
  relevant cabal arguments

* Add more meta, like since or deprecated which can be rendered in link
  titles and index.

* Add "quick reference" indices for cabal args, package.cabal and
 project.local fields. Reference these from sidebar.

* Using "since" and "deprectated field it is possible to create "what's
  new" index

[ci skip]

Also makes 'cabal' a default highlighter

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

This is somewhat related to #3791

[skip ci]

This is the result of using `pandoc` with default settings
to convert the existing `.markdown` files to `.rst` files.