Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Chapter 7 of the manual now has 27 sections #6676

Open
vicuna opened this issue Nov 25, 2014 · 16 comments
Open

Chapter 7 of the manual now has 27 sections #6676

vicuna opened this issue Nov 25, 2014 · 16 comments

Comments

@vicuna
Copy link

@vicuna vicuna commented Nov 25, 2014

Original bug ID: 6676
Reporter: @johnwhitington
Status: acknowledged (set by @damiendoligez on 2014-12-24T16:31:43Z)
Resolution: open
Priority: normal
Severity: feature
Target version: later
Category: documentation
Monitored by: @gasche @jmeber @hcarty @yakobowski

Bug description

I've noticed, a couple of times recently, programmers missing features of OCaml because they have not read through this, now huge, heterogeneous, chapter. It contains many things which are used even inside the compiler (Range Patterns, say). Or which were introduced many moons ago. Are they really extensions?

What is the rationale which decides what is considered 'Core Language' and 'Language Extensions'?

Why do we need to document a feature "Removed in Objective Caml 3.07" here?

Is this chapter a historical record, or can we trim or reorganise it? Lots of the content is interesting, especially for recently-introduced features (for example, complicated ones to do with the module system).

Is everything in it actually covered elsewhere in the manual? It is intended to be?

File attachments

@vicuna
Copy link
Author

@vicuna vicuna commented Nov 26, 2014

Comment author: @alainfrisch

I've tried to launch this discussion with other core developpers a few months ago. It seems there is a consensus to move some of the most stable/widespread/old features out of this chapter such as:

  • Range patterns
  • Assertion checking
  • Lazy expressions

Now we need someone to actually do it, and decide about other sections.

@vicuna
Copy link
Author

@vicuna vicuna commented Jun 19, 2015

Comment author: @johnwhitington

Patch remove_stream.txt, attached here, is a very small first step. This removes the section "Streams and stream parsers", functionality which was removed from the language 14 years ago.

@vicuna
Copy link
Author

@vicuna vicuna commented Jun 19, 2015

Comment author: @johnwhitington

As a next stage, I suggest dealing with sections 7.1 through to 7.9 inclusive. That is, anything introduced before OCaml 3.12.

How do people feel about increasing the number of top level headings under "Part II: The OCaml language" on the front page from just two to four or five, splitting the "Language extensions" up by topic?

If anyone feels deeply wedded to the "The OCaml language / Language extensions" dichotomy, please speak up, before I break it...

@vicuna
Copy link
Author

@vicuna vicuna commented Jun 26, 2015

Comment author: @Octachron

Concerning the removing of the stream syntax section, I think it could be useful to at least mention the existence of the camlp4 extension in the documentation of the stream module (21.34). Similarly, I am conflicted about the use of this syntax extension in the documentation of the Genlex module (21.12). It makes the example easier to read but it requires to be familiar with the camlp4 stream syntax extension.

@vicuna
Copy link
Author

@vicuna vicuna commented Jun 26, 2015

Comment author: @gasche

Sorry for not giving feedback earlier on these questions. John, I think that this is an instance of "those who do the work decide" indeed. Few people have the motivation to work on this, and we are lucky that you do. Do something that you feel is right, and I will try to support it and get it integrated quickly enough.

(I will start by merging the two other much simpler changes you proposed for the documentation; sorry for the delay)

@vicuna
Copy link
Author

@vicuna vicuna commented Jun 26, 2015

Comment author: @johnwhitington

@Octachron Thanks for pointing out those two sections. I think I can fix that.

@vicuna
Copy link
Author

@vicuna vicuna commented Jun 26, 2015

Comment author: @Octachron

One more detail, after rereading the subsection 7.8 on recursive modules, it sounds more experimental than the other extensions between 7.1 - 7.9. I also vaguely remember reading on the mailing list that the semantic of recursive modules semantic is still somewhat in flux. If it is indeed the case, it might be better to keep this subsection 7.8 inside the extension section.

@vicuna
Copy link
Author

@vicuna vicuna commented Nov 30, 2015

Comment author: @alainfrisch

Commit 491d972: remove section on streams.

I think it could be useful to at least mention the existence of the camlp4 extension in the documentation of the stream module

I think the general direction is rather to mark this module as deprecated, but don't hesitate to suggest some wording if you think this is useful.

@vicuna
Copy link
Author

@vicuna vicuna commented Dec 1, 2015

Comment author: @alainfrisch

All features introduced in OCaml 1 or 2 except extended let-rec definitions have been more to the core language chapter.

@vicuna
Copy link
Author

@vicuna vicuna commented Mar 12, 2017

Comment author: @gasche

In #1100, Octachron moved some of the record syntactic sugar from the Extensions chapter to the core manual, namely the record field punning (f; instead of f = f;, for both exception and pattern, and P.f; instead of P.f = f;) and the record wildcard pattern { f1 = p1; f2 = p2; _ }.

@vicuna
Copy link
Author

@vicuna vicuna commented Apr 17, 2017

Comment author: @gasche

New PR from Octachron moving val!, method! and inherit!. If nobody objects I'm planning on merging it at some point:

#1153

@johnwhitington
Copy link
Contributor

@johnwhitington johnwhitington commented Jan 21, 2021

Here is the current state of things. I have noted which ones contain examples (the "OCaml language" chapter says it does not allow examples).

I propose first to move three longstanding chapters (Recursive definition of values, Overriding in open statements, and Syntax for Bigarray access) into the "OCaml language" chapter. They do not contain examples, and are not tutorials. The Bigarray one is slightly dubious, since it is mostly Stdlib related, not language related, but on balance I want to move it. This gets us down to about 20 chapters...

After that, I propose to retain these tutorials about new features, but copy just the BNF parts into the "OCaml Language" chapter in the right places, with links to the appropriate section in the "Language Extensions" chapter. Thus, one can look in the BNF, find a new feature, and get to its documentation.

I would also like to reorder the contents table for the chapter, maybe by date of last modification?

Examples? Introduced Last modified Notes Action
Recursive definition of values No 1.00 - Move into main?
Recursive modules Yes 3.07 - Marked as experimental
Private types Yes 3.07 3.11
Locally abstract types Yes 3.12 4.03
First-class modules Yes 3.12 4.05
Recovering the type of a module Yes 3.12 -
Substituting inside a signature Yes 3.12 4.06
Type-level module aliases Yes 4.02 -
Overriding in open statements No 4.01 4.06 Move into main?
Syntax for Bigarray access No 3.00 - Related to stdlib, not core language Move into main?
Attributes Yes 4.02 4.03
Extension nodes Yes 4.02 4.04
Extensible variant types Yes 4.02 4.06
Generative functors No 4.02 -
Extension-only syntax No 4.02.2 4.03
Inline records Yes 4.03 -
Documentation comments Yes 4.03 -
Extended indexing operators Yes 4.06 -
Empty variant types Yes 4.07 -
Alerts Yes 4.08 -
Generalized open statements Yes 4.08 -
Binding operators Yes 4.08 -

@xavierleroy
Copy link
Contributor

@xavierleroy xavierleroy commented Jan 22, 2021

I propose first to move three longstanding chapters (Recursive definition of values, Overriding in open statements, and Syntax for Bigarray access)

Recursive definitions of values is a dubious feature with baroque rules and very few legitimate uses. So, I see no reason to bless it as part of "the" language.

Syntax for bigarray accesses could be added, since "the language" already shows syntaxes for array and string accesses. However, the current bigarray accesses chapter documents how the notations are expanded to function calls, while the similar expansion of array and string accesses is only documented in the standard library documentation.

@Octachron
Copy link
Member

@Octachron Octachron commented Jan 22, 2021

Concerning the syntax for bigarrays and overriding opens: I had already proposed to move then in #2201 and #1112 . However, @gasche thought that those features were not principled enough to be moved to the core part of the manual.

@xavierleroy
Copy link
Contributor

@xavierleroy xavierleroy commented Jan 22, 2021

I'm afraid this question requires some global and collective thinking. Discussing it piecewise in issues and pull requests dating back to 2014 is not working.

@yallop
Copy link
Member

@yallop yallop commented Jan 22, 2021

Recursive definition of values

It would be good to rename this section, since it also describes support for recursive definitions that are not values, such as definitions with local let bindings.

Regarding how widely used the feature is, when we wrote about the new recursive definition checker we found that there were a reasonable number of OPAM packages with generalized recursive definitions (i.e. those that Standard ML's syntactic-functions-only check would reject):

At the time of our analysis in July 2020, we found 309 distinct examples of [generalized recursive] definitions in around 74 packages. The definitions variously made use of local bindings and other local constructs (such as local exception definitions), evaluation of sub-terms, record and variant construction and laziness, in both singly-and mutually-recursive bindings.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
5 participants