This issue was moved to a discussion.
You can continue the conversation there. Go to discussion →
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
Comments
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:
Now we need someone to actually do it, and decide about other sections. |
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. |
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... |
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. |
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) |
Comment author: @johnwhitington @Octachron Thanks for pointing out those two sections. I think I can fix that. |
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. |
Comment author: @alainfrisch Commit 491d972: remove section on streams.
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. |
Comment author: @alainfrisch All features introduced in OCaml 1 or 2 except extended let-rec definitions have been more to the core language chapter. |
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 ( |
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?
|
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. |
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. |
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):
|
This issue has been open one year with no activity. Consequently, it is being marked with the "stale" label. What this means is that the issue will be automatically closed in 30 days unless more comments are added or the "stale" label is removed. Comments that provide new information on the issue are especially welcome: is it still reproducible? did it appear in other contexts? how critical is it? etc. |
Still an issue. |
This issue was moved to a discussion.
You can continue the conversation there. Go to discussion →
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
The text was updated successfully, but these errors were encountered: