To check that I understand this - Bad: "See the proposal for the definition of a closing token" (important definition) - Acceptable: "The reasons for this ..." (not essential information for replicating the functionality, though maybe one sentence summary would be good?) - Fine: "...the deprecation schedule are described ..." (if code is lost, the schedule will probably change as well) - Fine: "This proposal has many more examples." (manual has some examples already) - Bad: "Lexical syntax of identifiers and decimal numbers differs slightly from the Haskell report. See GHC Proposal #403 for the precise rules and differences." (doesn't specify the changes, vague, needs external reference).
Do we agree on this interpretation? - Oleg On 17.3.2021 20.35, Richard Eisenberg 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
