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

[Richard Eisenberg]

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