My vote is that the manual should be self-standing. References to proposals are good, but as supplementary/background reading only. My gold standard always is: if we lost all the source code to GHC and all its compiled versions, but just had the manual and Haskell Reports (but without external references), we could re-create an interface-equivalent implementation. (I say "interface-equivalent" because we do not specify all the details of e.g. optimizations and interface files.) We are very, very far from that gold standard. Yet I still think it's a good standard to aim for when drafting new sections of the manual.
Of course, authors are quite free to copy-and-paste from proposal text to form a new manual chapter. If we agree about this, it would be good to lay this out somewhere, perhaps in the "care and feeding" chapter. Richard > On Mar 17, 2021, at 1:21 PM, Oleg Grenrus <oleg.gren...@iki.fi> wrote: > > I forgot to link a bit of relevant discussion from > https://github.com/ghc-proposals/ghc-proposals/pull/406, > is there a (silent) consensus on the issue? > > - Oleg > > On 17.3.2021 19.15, Oleg Grenrus wrote: >> I have a following question: >> My lexer rules related proposal was recently accepted. The biggest part >> of getting it in is writing documentation for it. While looking at >> Divergence from Haskell 98 and Haskell 2010 section of the user manual, >> in particular Lexical syntax, it already has See "GHC Proposal #229 for >> the precise rules.". >> >> Can I just the same? (I think there was an implicit acceptance of that >> practice in e.g. >> https://gitlab.haskell.org/ghc/ghc/-/merge_requests/1664#note_238759) >> >> However, I think that referring to proposals text for "essential" bits >> of information is a bad practice. >> Because GHC proposals are sometimes amended, one have to look into >> GitHub history to find out what were there for a particular time point >> of a GHC release. Very laborous. >> >> --- >> >> Currently there is 23 references to about a dozen of proposals. An >> example are passages like >> >> In 9.0, the behavior of this extension changed, and now we require >> that a negative literal must not be preceded by a closing token (see >> `GHC Proposal #229 >> <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0229-whitespace-bang-patterns.rst>`__ >> for the definition of a closing token). >> >> or >> >> a future release will be >> turned off by default and then possibly removed. The reasons for >> this and >> the deprecation schedule are described in `GHC proposal #30 >> >> <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0030-remove-star-kind.rst>`__. >> >> And there are better examples, which are references for more information, >> not essential one, like >> >> See the proposal `DuplicateRecordFields without ambiguous field access >> >> <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0366-no-ambiguous-field-access.rst>`_ >> and the documentation on :extension:`DuplicateRecordFields` for >> further details. >> >> (I'd put the internal user manual link first), or >> >> But these automatic eta-expansions may silently change the semantics >> of the user's program, >> and deep skolemisation was removed from the language by >> `GHC Proposal #287 >> <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0287-simplify-subsumption.rst>`__. >> This proposal has many more examples. >> >> --- >> >> So to boil down my question, can I write >> >> Lexical syntax of identifiers and decimal numbers differs slightly >> from the Haskell report. >> See GHC Proposal #403 for the precise rules and differences. >> >> - Oleg >> _______________________________________________ >> ghc-devs mailing list >> ghc-devs@haskell.org >> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs > _______________________________________________ > ghc-devs mailing list > ghc-devs@haskell.org > http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs _______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs