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@haskell.org] On Behalf Of | Howard B. Golden | Sent: 21 August 2014 22:30 | To: ghc-devs@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@haskell.org | http://www.haskell.org/mailman/listinfo/ghc-devs