Cabal User Guide §1.2.9.1 has not kept pace with Cabal 1.8.0.2

[mpilgrem]

Cabal 1.8.0.2 (published December 2009) introduced:

• Allow executables to depend on the lib within the same package

and, nowadays, most packages where that is applicable take it up.

@geekosaur has noticed, in the Cabal and Hackage Matrix room, that the example in §1.2.9.1 of the latest Cabal User Guide has not kept pace with that.

I'll raise a pull request to fix that. I plan to do that in two steps:

1. take the documentation of the Cabal package description format specification history back from its current cabal-version: 1.12 to cabal-version: ==1.8; and
2. put through any other changes that ensure that the development is reflected fully in the current guide.

[ulysses4ever]

I agree that the example should be modernized as discussed.

I don't think it's a good idea to put things like cabal-version: 1.12 or 1.8 in today's Cabal manual because people (esp. novices) may run into all sorts of troubles with ancient formats not supporting features that are common nowadays (like common stanzas, for instance!). Also, 1.8 isn't valid, I think: before 1.12 you ought to say >=1.8, etc.

[mpilgrem]

@ulysses4ever, in a sense your comment makes my point: your observation about cabal-version: >= 1.8 is supported by referring to the current stable documentation of the changes to the specification introduced with cabal-version: 1.12 at https://cabal.readthedocs.io/en/stable/file-format-changelog.html#cabal-version-1-12.

Similarly, a question asked by @geekosaur in the Matrix room would have been answered, in part, by reference to the changes to the specification introduced with cabal-version: ==1.8 - if only the history went back that far. (The current 'to do' under cabal-version: 1.16 in the history suggests to me that the reason the history 'stops short' may be because the necessary research has not yet been performed.)

EDIT: I hope you will see from the associated pull request (now raised) that the changes that I propose to the documentation of the specification history are relatively conservative.