Add languages extension groups to grammar

[philderbeast]

Follow up on #9580. Shows the grammar of language extensions that before was showing as optcommalist TODO. Move these and default-language to its own section named "Language Extensions" and renames the "Field Syntax Reference" to "Cabal Package Syntax". In the table of contents put these in a new topmost SYNTAX REFERENCE section.

I first tried all languages extensions but the MathJax HTML renderer couldn't handle it; all of the extension rendered but the braces were drawn with interrupted lines. I upgraded to MathJax 3 and went back to using the SVG renderer. I used a different color for the math (same blue color we use for the titles in the docs). To help render wide equations, I allow the docs to render full width.

Template Β: This PR does not modify cabal behaviour (documentation, tests, refactoring, etc.)

Include the following checklist in your PR:

• Patches conform to the coding conventions.

To test:

$ make doc/buildinfo-fields-reference.rst --always-make

Please review the rendered docs, the sections in "SYNTAX REFERENCE".

[phadej]

The extension syntax is not restricted to known extensions, listing all the extensions is IMO not appropriate, the syntax description is the wrong place. (Same can be said about default-languages as well, but there are only few, so it's not as bad).

[philderbeast]

@phadej I took on what you said about default-extensions and default-languages and moved these to their own section in the docs (at the bottom of the table of contents).

[philderbeast]

We have a "cabal package" syntax reference but we don't have a "cabal project" syntax reference.

[phadej]

I repeat myself: this is wrong. The grammar accapts any tokens. The extensions specified may be anything, something which particular Cabal version doesn;t know about. The list of extensions is not part of .cabal file specification.

Listing all known extensions in the grammar specification is a bad idea.

[philderbeast]

How about something like this with its "unknown-extension"?

instance Described Extension where
    describe _ = REUnion
        [ reEnableExtension
        , reDisableExtension
        , reUnknownExtension
        ]

reEnableExtension :: GrammarRegex a
reEnableExtension = RENamed "enable-known-extension" reKnownExtension

reDisableExtension :: GrammarRegex a
reDisableExtension = REUnion ["No" <> reEnableExtension]

reUnknownExtension :: GrammarRegex a
reUnknownExtension = RENamed "unknown-extension" RETodo

[phadej]

No. Grammar doesn't care about extension names. They don't belong there.

The KnownExtension is an optimization: a constructor tag (machine integer) is better than a String (or Text). Perfectly, Cabal won't even have those exposed at all (for example it would allow smoother GHC-updates, as adjusting KnownExtension currently is a breaking change, but it would be better if it wasnt).

If people want extension list, add a link to the GHC manual.

EDIT: AFAIK the only place in Cabal which cares about extension names is cabal check feature which is a "linter" for .cabal files.

[geekosaur]

I agree with @phadej: extensions are in ghc's wheelhouse, cabal should not know about them (we have occasional discussions about why cabal knows about them at all instead of using ghc --supported-languages, although I don't think it's in a ticket). They certainly don't belong in the grammar.

[philderbeast]

Regarding "extensions shouldn't be in the grammar"; the intention with this change is to improve our documentation and to do that without altering the grammar. If the minor encroachment on the grammar bothers you, I could reduce it further.

As a reader of the docs, I find the red TODO rather glaring and off-putting.

[Mikolaj]

Yes, I think it makes sense to both correct/complete the documentation and minimize it, in particular, so that we don't have to update it as new extensions are added (until we manage to get rid of the need to add them).

[phadej]

to do that without altering the grammar.

Describe functionality is used to test real (Parsec) parsers. The TODOs are TODOs, but if specified the grammars should be correct. See UnitTests.Distribution.Described

o improve our documentation

The default-extensions documentation is https://cabal.readthedocs.io/en/stable/cabal-package.html#pkg-field-default-extensions, not in grammar. The picture you link actually has a link Documentation of default-extensions, which says

A list of Haskell extensions used by every module. These determine corresponding compiler options enabled for all files. Extension names are the constructors of the Extension type. For example, CPP specifies that Haskell source files are to be preprocessed with a C preprocessor.

(with unfortunately broken link) I.e. If you want to improve the documentation, do it in the right place. Correcting the link to https://hackage.haskell.org/package/Cabal-syntax/docs/Language-Haskell-Extension.html#t:KnownExtension should be sufficient. It's not Cabal's job to classify the extensions (GHC manual does, and having link there would be nice too, i.e. to https://downloads.haskell.org/ghc/latest/docs/users_guide/exts.html)