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

Oleg Grenrus oleg.grenrus at
Wed Mar 17 18:52:42 UTC 2021

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> wrote:
>> I forgot to link a bit of relevant discussion from
>> 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.
>>> 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
>>> <>`__
>>>     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
>>> <>`__.
>>> And there are better examples, which are references for more information,
>>> not essential one, like
>>>      See the proposal `DuplicateRecordFields without ambiguous field access
>>> <>`_
>>>      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
>>> <>`__.
>>>     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
>> _______________________________________________
>> ghc-devs mailing list
>> ghc-devs at

More information about the ghc-devs mailing list