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

[Brandon Allbery]

I'm inclined to agree with this, especially given the argument that it'll
depend on the state of a proposal at a given time.

On Wed, Mar 17, 2021 at 2:36 PM Richard Eisenberg <rae at richarde.dev> 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
>
> _______________________________________________
> ghc-devs mailing list
> ghc-devs at haskell.org
> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
>


-- 
brandon s allbery kf8nh
allbery.b at gmail.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-devs/attachments/20210317/1b361630/attachment.html>