Break up glasgow_exts.rst
Currently docs/users-guide/glasgow_exts.rst
is nearly 17kLoC. This is problematic for a number of reasons:
- Loading the HTML that it produces is very taxing: Firefox on my laptop requires nearly 5 seconds to completely load the nearly 2 MB of HTML produced in the 8.8.1 documentation. Woe betide you who browse on a mobile device.
- Navigation is a challenge: While the heading structure of the page is fairly logical, the TOC on the right side of the page spans 13 vertical screen-fuls on my laptop, rendering it quite useless.
- Editing is a nightmare: There is an noticeable lag while editing the ReST source in vim and even orienting oneself in the file is dizzying.
- Sphinx struggles to compile it: The file is large enough that we have had to work around performance limitations in Sphinx in the past (#10950 (closed))
For the above reasons I think we should break up this file. I suggest the following split (referring to the section numbers from the 8.8.1 documentation).
-
glasgow_exts.rst
: Language options (Section 9.1)-
glasgow_exts/values.rst
: (syntax and extensions to the value-level language)- Parallel list comprehensions (9.3.13)
- Generalised (SQL-like) list comprehensions (9.3.14)
- Monad comprehensions (9.3.15)
- New monadic failure desugaring mechanism (9.3.16)
- Recursive do-notation (9.3.11)
- Applicative do-notation (9.3.12)
- Arrow notation (9.28)
- Bang patterns and strict Haskell (9.29)
- Assertions (9.30)
- Static pointers (9.31)
-
HasCallStack
(9.38) - Rebindable syntax and the implicit Prelude import (9.3.17)
- Post-fix operators (9.3.18)
- Tuple sections (9.3.19)
- Lambda-case (9.3.20)
- Empty case alternatives (9.3.21)
- Multi-way-if expressions (9.3.22)
- Local fixity declarations (9.3.23)
-
glasgow_exts/literals.rst
:- Negative literals (9.3.3)
- Fractional-looking integer literals (9.3.4)
- Binary integer literals (9.3.5)
- Hexadecimal floating-point literals (9.3.6)
- Numeric underscores (9.3.7)
-
glasgow_exts/syntax.rst
:- Unicode syntax (9.3.1)
- Magic hash (9.3.2)
- Import and export extensions (9.3.24)
- More liberal syntax for function arguments (9.3.25)
- Summary of stolen syntax (9.3.26)
-
glasgow_exts/types.rst
:- Lexically scoped type variables (9.17)
- Bindings and generalisation (9.18)
- Extensions to data types and type synonyms (9.4)
- Extensions to type signatures (9.16)
- Visible type application (9.19)
- Datatype promotion (9.10)
- Kind polymorphism (9.11)
- Levity polymorphism (9.12)
- Equality constraints, Coercible, and the kind
Constraint
(9.14) - Arbitrary-rank polymorphism (9.21)
- Impredicative polymorphism (9.22)
- Roles (9.37)
- Type families (9.9)
-
glasgow_exts/type_errors.rst
: (not so sure about this; fold intotypes.rst
?)- Typed holes (7.23)
- Partial type signatures (9.24)
- Custom compile-time errors (9.25)
- Deferring type errors to runtime (9.26)
-
glasgow_exts/records.rst
: Extensions to the record system (9.5) -
glasgow_exts/patterns.rst
:- Pattern guards (9.3.8)
- View patterns (9.3.9)
- n+k patterns (9.3.10
- Pattern synonyms (9.7)
-
COMPLETE
pragmas (9.32.15)
-
glasgow_exts/typeclasses.rst
:- Implicit parameters (9.20) ?
-
MINIMAL
pragma (9.32.5) -
OVERLAPPING
,OVERLAPPABLE
,OVERLAPS
, andINCOHERENT
pragmas (9.32.17)
-
glasgow_exts/deriving.rst
:- Extensions to the “deriving” mechanism (9.6)
- Class and instances declarations (9.8)
- Quantified constraints (9.15)
-
glasgow_exts/template_haskell.rst
: Template Haskell (9.27) -
glasgow_exts/simplification.rst
: Mechanisms to guide simplification-
INLINE
andNOINLINE
pragmas (9.32.6) -
RULES
pragma (9.32.9) -
SPECIALISE
pragma (9.32.10) -
SPECIALISE instance
pragma (9.32.11) -
UNPACK
pragma (9.32.12) -
NOUNPACK
pragma (9.32.12) - Rewrite rules (9.33)
- Special built-in functions (9.34)
-
-
glasgow_exts/misc_pragmas.rst
: Miscellaneous pragmas-
LANGUAGE
pragma (9.32.1) -
OPTIONS_GHC
pragma (9.32.2) -
WARNING
andDEPRECATED
pragmas (9.32.4) -
LINE
pragma (9.32.7) -
COLUMN
pragma (9.32.8) -
SOURCE
pragma (9.32.14)
-
-
glasgow_exts/generic_prog.rst
:- Generic classes (9.35)
- Generic programming (9.36)
-
Edited by Ben Gamari