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

[Oleg Grenrus]

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.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
>