Mantis Bug Tracker

View Issue Details Jump to Notes ] Issue History ] Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0005612OCamldocumentationpublic2012-05-10 10:132015-12-11 19:24
Assigned Todoligez 
PlatformOSOS Version
Product Version 
Target Version4.01.0+devFixed in Version4.01.0+dev 
Summary0005612: Rationalize spacing and parenteses use in the tutorial part of the manual
DescriptionA beginners_list discussion revealed that some beginners are confused by the spacing style used in the introduction, that plays a dubious ambiguity between OCaml parenthesing rules and the more familiar f(x) notation. Terms like fib(n-2) or square(cos pi) are a potential recipe for disaster once the beginner uses currified functions.

In my experience, such parenthesing and escaping mistakes are actually the number one problem among early OCaml beginners. This section of the manual should be updated to avoid that style.
Attached Files

- Relationships

-  Notes
doligez (administrator)
2013-08-19 14:47

Do I understand correctly that you are suggesting we add a space to turn "f(x)" into "f (x)" ? Will that be enough to help the beginners ? If so, I'm all in favor of making the change.

There is also one instance of "f(g(x))", which should obviously replaced by "f (g x)".
johnwhitington (reporter)
2013-08-20 23:39

Can't we go the whole way and just use "f x" and "f (x + 1)" and "f (g x)" (i.e. miss out all unnecessary parentheses in function applications)?

Beginners, especially those from another language, often think of (x) as a 1-tuple, which contributes to their conviction that f (x, y, z) is a three-argument function rather than a function with a single argument which is a tuple. I think this harms their understanding when they move on to currying.

(Students I teach for Standard ML also universally think unit is the 0-tuple the first time they see it, but that's mostly harmless).
gasche (developer)
2013-08-20 23:46

The notation I want to avoid is foo(bar), in particular f(x) (the case where both `foo` and `bar` are variables) which is exactly the math notation -- it's best to show as early as possible as OCaml uses a different notation. So we must never have parentheses just after the function expression, and adding a space is one way to avoid having that.

I'd say Damien's proposal to just add spaces is "sufficient". John's suggestion to always use the minimal number of parentheses is not strictly necessary but would be, I think, a good guideline to follow (for expressions built up of function applications at least).
doligez (administrator)
2013-09-02 11:24

I'm sorry I wasn't clear. What I wanted to propose is exactly John's suggestion, but there are very few actual occurrences of f(x) in the manual, most of these are f(expr) where expr is not a single variable.

My question was whether we also want to add a space in f(expr), and the answer is yes.

I'll do the changes when I'm done with the RC.
doligez (administrator)
2013-09-02 13:47

Done. I've also added spaces when infix operators are used as prefix (as in (( + ) 1) l).

I have not changed the spacing for constructors because unlike functions they have arity and I think it's good to show that they are not quite like functions. For similar reasons, I haven't touched functor applications (where parentheses are mandatory).

Fixed in rev 14053.

- Issue History
Date Modified Username Field Change
2012-05-10 10:13 gasche New Issue
2012-05-10 10:13 gasche Status new => assigned
2012-05-10 10:13 gasche Assigned To => gasche
2012-09-06 16:44 doligez Target Version => 4.00.1+dev
2012-09-21 14:20 doligez Target Version 4.00.1+dev => 4.01.0+dev
2013-07-28 09:07 gasche Tag Attached: junior_job
2013-08-19 14:47 doligez Note Added: 0010195
2013-08-19 14:47 doligez Target Version 4.01.0+dev => 4.01.1+dev
2013-08-19 14:47 doligez Target Version 4.01.1+dev => 4.01.0+dev
2013-08-20 23:39 johnwhitington Note Added: 0010213
2013-08-20 23:46 gasche Note Added: 0010214
2013-09-02 11:24 doligez Note Added: 0010295
2013-09-02 13:19 doligez Assigned To gasche => doligez
2013-09-02 13:47 doligez Note Added: 0010296
2013-09-02 13:47 doligez Status assigned => resolved
2013-09-02 13:47 doligez Resolution open => fixed
2013-09-02 13:47 doligez Fixed in Version => 4.01.0+dev
2015-12-11 19:24 xleroy Status resolved => closed
2017-02-23 16:35 doligez Category OCaml documentation => Documentation
2017-02-23 16:44 doligez Category Documentation => documentation

Copyright © 2000 - 2011 MantisBT Group
Powered by Mantis Bugtracker