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:[EMAIL PROTECTED] | Sent: 28 August 2008 12:28 | To: Simon Peyton-Jones; Ian Lynagh; Simon Marlow | Cc: [email protected] | 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 | _______________________________________________ Cvs-ghc mailing list [email protected] http://www.haskell.org/mailman/listinfo/cvs-ghc
