Is referring to GHC-proposals in GHC user manual bad practice or not?
oleg.grenrus at iki.fi
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"
- Acceptable: "The reasons for this ..." (not essential information for
replicating the functionality, though maybe one sentence summary would
- 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
- 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
Do we agree on this interpretation?
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.
>> 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
>> 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).
>>> 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 haskell.org
>> ghc-devs mailing list
>> ghc-devs at haskell.org
More information about the ghc-devs