Suggestion for GHC System User's Guide documentation change

Howard B. Golden howard_b_golden at yahoo.com
Thu Aug 21 21:29:38 UTC 2014


I suggest changing the User's Guide extensions documentation to consistently use the LANGUAGE pragma form to specify extensions and code examples, rather than a combination of LANGUAGE pragmas and -XExtension flags. I find the combination of the two confusing. Also, the reader copying code examples which require a specific LANGUAGE to compile will be assisted by including the LANGUAGE pragma in the code examples.


For example, in section 7.3, I would change:
--------------------------------------------

7.3. Syntactic extensions
7.3.1. Unicode syntax

The language extension -XUnicodeSyntax enables Unicode characters to be used to stand for certain ASCII character sequences.
--------------------------------------------


To:
--------------------------------------------
7.3. Syntactic extensions
7.3.1. Unicode syntax

The language extension {-# LANGUAGE UnicodeSyntax #-} enables Unicode characters to be used to stand for certain ASCII character sequences.
--------------------------------------------



Similarly, I would include the required LANGUAGE pragma(s) in _all_ code examples. For example, in section 7.3.7, I would change:
--------------------------------------------

type Typ

data TypView = Unit
             | Arrow Typ Typ

view :: Typ -> TypView

-- additional operations for constructing Typ's ...
--------------------------------------------


To:
--------------------------------------------


{-# LANGUAGE ViewPatterns #-}
type Typ

data TypView = Unit
             | Arrow Typ Typ

view :: Typ -> TypView

-- additional operations for constructing Typ's ...
--------------------------------------------

I realize that LANGUAGE pragmas must be in file headers. While it is possible that users may be confused if they try to put pragmas in the body of a source file, I believe this will be outweighed by the benefit of making the examples clearer about the extensions necessary to use them.

If this change is accepted, I volunteer to make the necessary documentation patches to implement it.


Howard B. Golden
Northridge, CA USA


More information about the ghc-devs mailing list