Docs for language flags
simonpj at microsoft.com
Thu Aug 28 08:54:42 EDT 2008
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
| -----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
| <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.
More information about the Cvs-ghc