`stack haddock`: How to correctly use `--prologue`?

[ad-si]

Stack version

stack --version
Version 3.5.1, Git revision 86415540dffcb1990e0b503c894dcb913378f5dc aarch64 hpack-0.38.0

Method of installation

• Via GHCup

Question

If I'm executing stack like this:

stack haddock \
--haddock-arguments \
  '--title=Documentation \
  --theme=/app/theme \
  --odir=/app/docs \
  --prologue=/app/prologue.md'
package-a \
package-b

I get following errors:

…
package-a: multiple -p/--prologue options
…
package-b: multiple -p/--prologue options
…

How do I use it correctly?

[mpilgrem]

@ad-si, thanks for reporting. The problem seems to be this:

Stack builds with Cabal (the library) and will send Cabal a command like this:

[Cabal]
--builddir=.stack-work\dist\f24b2e15 
haddock 
--html 
--hoogle 
--html-location=../$pkg-$version/ 
--haddock-option=--hyperlinked-source 
--haddock-option=--quickjump 
--haddock-option=--prologue=my-prologue  <<<< passing on the desired prologue file

For its part, Cabal then invokes Haddock with a command something like this (extracts only):

haddock.exe 
--prologue=.stack-work\\dist\\f24b2e15\\doc\\html\\testHaddock\\had1135.txt <<<< Cabal's own prologue
--dump-interface=.stack-work\\dist\\f24b2e15\\doc\\html\\testHaddock\\testHaddock.haddock
--package-name=testHaddock
--package-version=0.1.0.0
--since-qual=external
...
--html
--hoogle
--title=testHaddock-0.1.0.0
...
src\\Lib.hs
--hyperlinked-source
--quickjump
--prologue=my-prologue <<<< passing on the desired prologue file

Cabal's own prologue seems to be the contents of the Cabal file's description field.

As Cabal has already snaffled the use of --prologue, it seems that you can't then specify your own.

The starting point for doing what you want to do is a new feature request for Cabal (the library). As Stack builds with the version of Cabal that ships with the specified version of GHC, if that feature is implemented by future Cabal, it won't come to Stack until that future Cabal ships with future GHC.