Docs: difficult to discover "common" and "import"

[david-christiansen]

Having had a hazy idea that cabal-install had the ability to define common sets of dependencies for components, I went hunting for a description of how to do it. Searching for terms like "cabal include subsections", "cabal shared dependencies" and the like did not help me, and there was nothing I could find on the Cabal quickstart page with C-f in my browser. I even read the Cabal changelog since version 2.0, and found no mention of the feature.

I asked on the internal chat at work, and someone eventually pointed me to the right spot.

It seems unfortunate that this feature was so difficult to discover, because it's very useful.

Because it's most hugely a win for build-depends, I would suggest that there be a pointer to it in the build-depends docs, and also to have cabal init generate a file that has it as an example.

[tom-audm]

Related #5705

[23Skidoo]

/cc @phadej

[m-renaud]

It seems like a new section between 3.1.4. Modules imported from other packages and 3.1.5. Building the package would be a natural place.

Either that or simply expanding section 3.1.4 to include an "Also, you can factor out shared build-depends (and other fields like ghc-options) into a common stanza which you can import in your library and executable sections like so: <code-snippet>. For more information see the Common stanzas section."

[david-christiansen]

The two sentences that you write in your second stanza would have saved me a good chunk of confusion today, @m-renaud.

[m-renaud]

I'll put together a PR today when I get a chance :)

[david-christiansen]

This is great! Thanks!