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