Suggestion for GHC System User's Guide documentation change

[Simon Peyton Jones]

I'd be ok with this. It's a bit more verbose, but if it's less confusing for our users, then go for it.

Thanks for offering to make a patch!

SImon

| -----Original Message-----
| From: ghc-devs [mailto:ghc-devs-bounces at haskell.org] On Behalf Of
| Howard B. Golden
| Sent: 21 August 2014 22:30
| To: ghc-devs at haskell.org
| Subject: Suggestion for GHC System User's Guide documentation change
| 
| 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
| _______________________________________________
| ghc-devs mailing list
| ghc-devs at haskell.org
| http://www.haskell.org/mailman/listinfo/ghc-devs