Sections "Field Syntax Reference" and "Package Description" are out of sync and inconsistent
- Dominant language
- Haskell
- Stars
- 1.7k
- Forks
- 750
- Avg merge
- 4d 3h
- Merged PRs (30d)
- 28
Description
**What is wrong with the docs?**
There are two toplevel sections in the cabal users guide which document the cabal file format. Section 6 (Package description) and section 10 (Field Syntax Reference). Unfortunately, they contradict each other.
For example:
- Field "default-language": Section 6 says that `Haskell98` `Haskell2010` and `GHC2021` are allowed, and that the field was available since version 1.12. Section 10 says that `Haskell98` and `Haskell2010` are allowed, and that the field was available since version 1.10.
- There are a lot of other fields where the two sections disagree on when the field was introduced.
- In section 10 the `license` field is undocumented, so it is missing the crucial information that only SPDX identifiers are accepted in newer versions of the cabal file format.
- The documentation of the `cabal-version` field in section 10 mentions a `>=1.0` default, but version ranges are no longer allowed for newer versions of cabal, and there is no information that this is a special field which should occur only in the very first line.
In general, I have the impression that the documentation in section 6 is much more accurate and current than the documentation in section 10. I think the intention was for section 10 to contain a semi-formal BNF grammar for cabal files, but if this information is incomplete and out-of-sync, then the value of documenting every field twice is a bit dubious.
So what should be done here? If given some guidance on what would be the best approach here I would volunteer some time and could for example try to merge the information of both sections: Go through all the information in sec. 10 and add any information that is missing in sec. 6 to the documentation of the respective fields. But if there are better suggestions on what to do here I would also be thankful :)
Contributor guide
Research direction
Start by comparing sections 6 (Package description) and 10 (Field Syntax Reference) of the Cabal users guide, especially the default-language, license, and cabal-version fields. Identify every contradiction and decide which section is authoritative or whether duplicated information should be consolidated. Done means the two sections no longer disagree and all relevant field constraints and version information are documented consistently.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- haskell
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100