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

[Oleg Grenrus]

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