<div dir="ltr">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.</div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Wed, Mar 17, 2021 at 2:36 PM Richard Eisenberg <<a href="mailto:rae@richarde.dev">rae@richarde.dev</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">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.<br>
<br>
Of course, authors are quite free to copy-and-paste from proposal text to form a new manual chapter.<br>
<br>
If we agree about this, it would be good to lay this out somewhere, perhaps in the "care and feeding" chapter.<br>
<br>
Richard<br>
<br>
> On Mar 17, 2021, at 1:21 PM, Oleg Grenrus <<a href="mailto:oleg.grenrus@iki.fi" target="_blank">oleg.grenrus@iki.fi</a>> wrote:<br>
> <br>
> I forgot to link a bit of relevant discussion from<br>
> <a href="https://github.com/ghc-proposals/ghc-proposals/pull/406" rel="noreferrer" target="_blank">https://github.com/ghc-proposals/ghc-proposals/pull/406</a>,<br>
> is there a (silent) consensus on the issue?<br>
> <br>
> - Oleg<br>
> <br>
> On 17.3.2021 19.15, Oleg Grenrus wrote:<br>
>> I have a following question:<br>
>> My lexer rules related proposal was recently accepted. The biggest part<br>
>> of getting it in is writing documentation for it. While looking at<br>
>> Divergence from Haskell 98 and Haskell 2010 section of the user manual,<br>
>> in particular Lexical syntax, it already has See "GHC Proposal #229 for<br>
>> the precise rules.".<br>
>> <br>
>> Can I just the same? (I think there was an implicit acceptance of that<br>
>> practice in e.g.<br>
>> <a href="https://gitlab.haskell.org/ghc/ghc/-/merge_requests/1664#note_238759" rel="noreferrer" target="_blank">https://gitlab.haskell.org/ghc/ghc/-/merge_requests/1664#note_238759</a>)<br>
>> <br>
>> However, I think that referring to proposals text for "essential" bits<br>
>> of information is a bad practice.<br>
>> Because GHC proposals are sometimes amended, one have to look into<br>
>> GitHub history to find out what were there for a particular time point<br>
>> of a GHC release. Very laborous.<br>
>> <br>
>> ---<br>
>> <br>
>> Currently there is 23 references to about a dozen of proposals. An<br>
>> example are passages like<br>
>> <br>
>>     In 9.0, the behavior of this extension changed, and now we require<br>
>> that a negative literal must not be preceded by a closing token (see<br>
>>     `GHC Proposal #229<br>
>> <<a href="https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0229-whitespace-bang-patterns.rst" rel="noreferrer" target="_blank">https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0229-whitespace-bang-patterns.rst</a>>`__<br>
>>     for the definition of a closing token).<br>
>> <br>
>> or<br>
>> <br>
>>      a future release will be<br>
>>      turned off by default and then possibly removed. The reasons for<br>
>> this and<br>
>>      the deprecation schedule are described in `GHC proposal #30<br>
>>     <br>
>> <<a href="https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0030-remove-star-kind.rst" rel="noreferrer" target="_blank">https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0030-remove-star-kind.rst</a>>`__.<br>
>> <br>
>> And there are better examples, which are references for more information,<br>
>> not essential one, like<br>
>> <br>
>>      See the proposal `DuplicateRecordFields without ambiguous field access<br>
>>     <br>
>> <<a href="https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0366-no-ambiguous-field-access.rst" rel="noreferrer" target="_blank">https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0366-no-ambiguous-field-access.rst</a>>`_<br>
>>      and the documentation on :extension:`DuplicateRecordFields` for<br>
>> further details.<br>
>> <br>
>> (I'd put the internal user manual link first), or<br>
>> <br>
>>     But these automatic eta-expansions may silently change the semantics<br>
>> of the user's program,<br>
>>     and deep skolemisation was removed from the language by<br>
>>     `GHC Proposal #287<br>
>> <<a href="https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0287-simplify-subsumption.rst" rel="noreferrer" target="_blank">https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0287-simplify-subsumption.rst</a>>`__.<br>
>>     This proposal has many more examples.<br>
>> <br>
>> ---<br>
>> <br>
>> So to boil down my question, can I write<br>
>> <br>
>>     Lexical syntax of identifiers and decimal numbers differs slightly<br>
>> from the Haskell report.<br>
>>     See GHC Proposal #403 for the precise rules and differences.<br>
>> <br>
>> - Oleg<br>
>> _______________________________________________<br>
>> ghc-devs mailing list<br>
>> <a href="mailto:ghc-devs@haskell.org" target="_blank">ghc-devs@haskell.org</a><br>
>> <a href="http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs" rel="noreferrer" target="_blank">http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs</a><br>
> _______________________________________________<br>
> ghc-devs mailing list<br>
> <a href="mailto:ghc-devs@haskell.org" target="_blank">ghc-devs@haskell.org</a><br>
> <a href="http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs" rel="noreferrer" target="_blank">http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs</a><br>
<br>
_______________________________________________<br>
ghc-devs mailing list<br>
<a href="mailto:ghc-devs@haskell.org" target="_blank">ghc-devs@haskell.org</a><br>
<a href="http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs" rel="noreferrer" target="_blank">http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs</a><br>
</blockquote></div><br clear="all"><div><br></div>-- <br><div dir="ltr" class="gmail_signature"><div dir="ltr"><div><div dir="ltr"><div>brandon s allbery kf8nh</div><div><a href="mailto:allbery.b@gmail.com" target="_blank">allbery.b@gmail.com</a></div></div></div></div></div>