Is referring to GHC-proposals in GHC user manual bad practice or not?

[Richard Eisenberg]

> On Mar 17, 2021, at 2:52 PM, Oleg Grenrus <oleg.grenrus at iki.fi> wrote:
> 
> 
> Do we agree on this interpretation?

Yes, fully. Thanks for illustrating with examples.

Richard

> 
> - 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.grenrus at 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 at haskell.org
>>>> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
>>> _______________________________________________
>>> ghc-devs mailing list
>>> ghc-devs at haskell.org
>>> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
>>