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 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 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-wh... `__ 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-re... `__.

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... `_ 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-si... `__. 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@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

---

ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

_______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

-- brandon s allbery kf8nh allbery.b@gmail.com

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 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-wh...`__ 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-re...`__.

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...`_ 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-si...`__. 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@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

---

ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

I, too, agree with Richard here. In fact, one (small) reason why we originally chose RestructuredText as the proposal syntax is to make it easy to turn the proposal into users guide documentation. Cheers, - Ben On March 17, 2021 2:35:54 PM EDT, 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 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

...

I have a following question: My lexer rules related proposal was recently accepted. The biggest

...

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

On 17.3.2021 19.15, Oleg Grenrus wrote: part 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"

...

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

bits 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-wh...`__

...

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-re...`__.

...

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...`_

...

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-si...`__.

...

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@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

---

ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

_______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

-- Sent from my Android device with K-9 Mail. Please excuse my brevity.