Skip to content

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 into types.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, and INCOHERENT 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 and NOINLINE 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 and DEPRECATED 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
To upload designs, you'll need to enable LFS and have an admin enable hashed storage. More information