Suggestion for GHC System User's Guide documentation change

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

Suggestion for GHC System User's Guide documentation change

Howard B. Golden
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

Reply | Threaded
Open this post in threaded view
|

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

Reply | Threaded
Open this post in threaded view
|

Suggestion for GHC System User's Guide documentation change

p.k.f.holzenspies@utwente.nl
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>

Reply | Threaded
Open this post in threaded view
|

Suggestion for GHC System User's Guide documentation change

Howard B. Golden
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 at utwente.nl" <p.k.f.holzenspies at utwente.nl>
To: simonpj at microsoft.com; howard_b_golden at yahoo.com; ghc-devs at haskell.org
Sent: Friday, August 22, 2014 5:38 AM
Subject: RE: Suggestion for GHC System User's Guide documentation change



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.


Reply | Threaded
Open this post in threaded view
|

Suggestion for GHC System User's Guide documentation change

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 <howard_b_golden at yahoo.com>
Sent: 22 August 2014 18:47
To: Holzenspies, P.K.F. (EWI); simonpj at microsoft.com; ghc-devs at haskell.org
Subject: Re: Suggestion for GHC System User's Guide documentation change

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 at utwente.nl" <p.k.f.holzenspies at utwente.nl>
To: simonpj at microsoft.com; howard_b_golden at yahoo.com; ghc-devs at haskell.org
Sent: Friday, August 22, 2014 5:38 AM
Subject: RE: Suggestion for GHC System User's Guide documentation change



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.