Docs for language flags

[Simon Peyton-Jones]

Thanks.  That's helpful. I've committed a patch that summarises syntactic changes as a subsection of the "Syntactic extensions" section of the manual.  Maybe it should be x-referenced from elsewhere, but it seems to fit there

Simion

| -----Original Message-----
| From: Claus Reinke [mailto:claus.reinke at talk21.com]
| Sent: 28 August 2008 12:28
| To: Simon Peyton-Jones; Ian Lynagh; Simon Marlow
| Cc: cvs-ghc at haskell.org
| Subject: Re: Docs for language flags
|
| | This is the first time I've looked at (b), so I don't mind it going,
| | but the syntax info deserves its own section, to be easy to find
| | without blowing up the flag reference section.
|
| >Interesting.  Any suggestions about where would be "easy to find"?
| >Or what the section would look like.  Would you like to draft it?
| >Then I'd go through for accuracy.
|
| I think the reason I never looked at 8.1 is that, even for what
| it says it does, there are more direct sources: if I want an overview,
| I go to 5.17.12, if I want the details, I go to 8.n (n>1). So I never
| had a reason to look up 8.1, so I never knew it offered syntax diffs
| as well (something I have looked for on occasion).
|
| So, one could retarget 8.1 to be a summary of "New and stolen syntax"
| (the new syntax elements are explained at the beginning of each 8.n,
| but in so much detail that the stolen syntax aspect would be lost there).
|
| That title might have led me to look into the section, although I'd
| probably have searched for the information in some 13.1a, so I'm
| completely undecided which of the two would make the best location.
|
| But then, I wouldn't want this kind of information to be written into
| those sections by hand anyway: stolen syntax/new syntax ought to be
| part of the centralised flag description, and automatically extracted
| from there, perhaps even into both 8.1 and 13.1a (if they have the
| same generated uptodate text, duplication isn't much of a problem).
|
| Something like:
|
| 13.1a Haskell 98 vs. Glasgow Haskell: New and stolen syntax
|
|     Section 13.1 describes issues in how close working with GHC
|     can come to working with Haskell 98. There is, however, the
|     not entirely separate issue of how GHC's language extensions
|     interact with Haskell 98 programs when you want to go beyond
|     Haskell 98. There is new syntax, only available when a language
|     extension is enabled, but there are also a few cases where enabling
|     a language extension re-interprets existing syntax, which can lead
|     to awkward misinterpretations.
|
|     If you encounter an unknown piece of syntax, this section will
|     help you to identify which language extension it belongs to. If you
|     run into trouble with Haskell 98 code after switching on a language
|     extension, this section will try to tell you why that happens and how
|     to work around it. After browsing this section, you should be able
|     to spot potentially troublesome syntax, and to write your Haskell 98
|     code in a way that will continue to work if language extensions are
|     enabled.
|
|     <flag-specific parts, extracted from central file, showing new and
|     stolen syntax, suggested syntax rewrites to avoid misinterpretations;
|     links to sections explaining details>
|
|     All GHC language extensions are documented in detail in section 8.
|     The Flag Reference, section 5.17.12 gives an overview of language
|     options enabling or disabling these extensions.
|
| Claus
|