Mantis Bug Tracker

View Issue Details Jump to Notes ] Issue History ] Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0006676OCamldocumentationpublic2014-11-25 21:432017-04-17 20:31
Reporterjohnwhitington 
Assigned To 
PrioritynormalSeverityfeatureReproducibilityN/A
StatusacknowledgedResolutionopen 
PlatformOSOS Version
Product Version 
Target VersionlaterFixed in Version 
Summary0006676: Chapter 7 of the manual now has 27 sections
DescriptionI'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?

TagsNo tags attached.
Attached Filestxt file icon remove_stream.txt [^] (1,118 bytes) 2015-06-19 19:58 [Show Content]

- Relationships

-  Notes
(0012582)
frisch (developer)
2014-11-26 09:26

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.
(0014104)
johnwhitington (reporter)
2015-06-19 20:00
edited on: 2015-06-19 20:00

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.

(0014105)
johnwhitington (reporter)
2015-06-19 20:12
edited on: 2015-06-19 20:13

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

(0014156)
octachron (developer)
2015-06-26 13:57

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.
(0014157)
gasche (developer)
2015-06-26 14:02

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)
(0014159)
johnwhitington (reporter)
2015-06-26 14:08

@octachron Thanks for pointing out those two sections. I think I can fix that.
(0014160)
octachron (developer)
2015-06-26 14:14

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.
(0014908)
frisch (developer)
2015-11-30 13:49

Commit 491d972f693d1cb433376ae12e7d786dd6c4c669: 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.
(0014945)
frisch (developer)
2015-12-01 16:09

All features introduced in OCaml 1 or 2 except extended let-rec definitions have been more to the core language chapter.
(0017628)
gasche (developer)
2017-03-12 21:30

In https://github.com/ocaml/ocaml/pull/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; _ }`.
(0017741)
gasche (developer)
2017-04-17 20:31
edited on: 2017-04-17 20:32

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

  https://github.com/ocaml/ocaml/pull/1153 [^]


- Issue History
Date Modified Username Field Change
2014-11-25 21:43 johnwhitington New Issue
2014-11-26 09:26 frisch Note Added: 0012582
2014-12-24 17:31 doligez Status new => acknowledged
2014-12-24 17:31 doligez Target Version => 4.03.0+dev / +beta1
2015-06-19 19:58 johnwhitington File Added: remove_stream.txt
2015-06-19 20:00 johnwhitington Note Added: 0014104
2015-06-19 20:00 johnwhitington Note Edited: 0014104 View Revisions
2015-06-19 20:12 johnwhitington Note Added: 0014105
2015-06-19 20:13 johnwhitington Note Edited: 0014105 View Revisions
2015-06-26 13:57 octachron Note Added: 0014156
2015-06-26 14:02 gasche Note Added: 0014157
2015-06-26 14:08 johnwhitington Note Added: 0014159
2015-06-26 14:14 octachron Note Added: 0014160
2015-11-30 13:49 frisch Note Added: 0014908
2015-11-30 17:00 frisch Target Version 4.03.0+dev / +beta1 => later
2015-12-01 16:09 frisch Note Added: 0014945
2017-02-23 16:35 doligez Category OCaml documentation => Documentation
2017-02-23 16:44 doligez Category Documentation => documentation
2017-03-07 13:27 shinwell Severity minor => feature
2017-03-12 21:30 gasche Note Added: 0017628
2017-04-17 20:31 gasche Note Added: 0017741
2017-04-17 20:32 gasche Note Edited: 0017741 View Revisions


Copyright © 2000 - 2011 MantisBT Group
Powered by Mantis Bugtracker