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
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
Marginally less verbose; why not use the language extension *only* in running text? Preferably with a link to the documentation of that language extension. In your example:
| The language extension <ref>UnicodeSyntax</ref> enables Unicode characters to be
| used to stand for certain ASCII character sequences.?
With regards to code examples: Ideally any explicit code example could just be copy-pasted into a .hs-file and loaded into ghci / compiled with ghc without special switches.
Just my two cents ;)
Ph.
________________________________
From: Simon Peyton Jones
p.k.f.,
I like your less verbose suggestion better than my original.
I don't understand your comment about code examples: Are you supporting or opposing the inclusion of the LANGUAGE pragmas in the examples?
Howard
________________________________
From: "p.k.f.holzenspies@utwente.nl"
Dear Howard,
Yes, emphatically so! Any examples should be copy-paste-runnable if reasonably possible without any further switches, so that means the pragmas *should* be included!
Regards,
Philip
________________________________________
From: Howard B. Golden
participants (3)
-
Howard B. Golden -
p.k.f.holzenspies＠utwente.nl -
Simon Peyton Jones