I'm inclined to agree with this, especially given the argument that it'll depend on the state of a proposal at a given time.
On Wed, Mar 17, 2021 at 2:36 PM Richard Eisenberg <r...@richarde.dev> wrote: > 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 > -- brandon s allbery kf8nh allber...@gmail.com
_______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
