Suggestion for GHC System User's Guide documentation change

p.k.f.holzenspies at utwente.nl p.k.f.holzenspies at utwente.nl
Fri Aug 22 12:38:57 UTC 2014


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 <simonpj at microsoft.com>
Sent: 22 August 2014 09:37
To: Howard B. Golden; ghc-devs at haskell.org
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: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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.haskell.org/pipermail/ghc-devs/attachments/20140822/d8f72183/attachment-0001.html>


More information about the ghc-devs mailing list