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 · 11 comments

Comments

Projects
None yet
1 participant
@vicuna
Copy link

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

This comment has been minimized.

Copy link
Author

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

This comment has been minimized.

Copy link
Author

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

This comment has been minimized.

Copy link
Author

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

This comment has been minimized.

Copy link
Author

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

This comment has been minimized.

Copy link
Author

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

This comment has been minimized.

Copy link
Author

commented Jun 26, 2015

Comment author: @johnwhitington

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

@vicuna

This comment has been minimized.

Copy link
Author

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

This comment has been minimized.

Copy link
Author

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

This comment has been minimized.

Copy link
Author

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

This comment has been minimized.

Copy link
Author

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

This comment has been minimized.

Copy link
Author

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.