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

Improvements to OCaml manual #1545

Merged
merged 4 commits into from Jan 25, 2018

Conversation

Projects
None yet
7 participants
@jfehrle
Copy link
Contributor

jfehrle commented Dec 24, 2017

See https://caml.inria.fr/mantis/view.php?id=7698.

This will take some discussion, perhaps a lot.

@jfehrle jfehrle force-pushed the jfehrle:improve_doc branch from fa97b7f to 24eeba8 Dec 24, 2017

They will be covered in more details later; for now, we concentrate on lists.
Predefined data structures include tuples, arrays, and lists. There are also
general mechanisms for defining your own data structures. These are records
and classes, which will be covered in more detail later; for now, we concentrate on lists.

This comment has been minimized.

@OvermindDL1

OvermindDL1 Dec 27, 2017

/me is not really a fan of even acknowledging classes exist this early...

This comment has been minimized.

@Octachron

Octachron Dec 27, 2017

Contributor

Introducing classes with the same level of importance as records and eclipsing variants is indeed a bad idea. People familiar with C++ or Java often misjudge the importance of classes in OCaml and this change may accentuate this problem. Contrarily echoing the title of the records and variants sections seems like a good idea. Mentioning that specialized data types like classes and polymorphic variants (and GADTs, extensible variants, and first-class modules) are also available might be a good compromise.

This comment has been minimized.

@jfehrle

jfehrle Dec 28, 2017

Author Contributor

I'll take out the reference to classes and leave records as an example.

While I can frequently identify when something is confusing or missing, it's of course challenging for me as a novice to come up with specific changes to the wording and accurate details.

This comment has been minimized.

@Octachron

Octachron Dec 28, 2017

Contributor

I'll take out the reference to classes and leave records as an example.

I think citing variants at the same level of record would be nice, the two complements each other a lot and are fundamental parts of the type system.

While I can frequently identify when something is confusing or missing, it's of course challenging for me as a novice to come up with specific changes to the wording and accurate details.

Sorry if my tone was too dry, I really appreciate your contribution and it will make for a nice improvemen … after a bit of editing.

@Octachron
Copy link
Contributor

Octachron left a comment

Thanks a lot for the contribution! I have however a lot of small comments and request for modifications.

@@ -4,7 +4,7 @@

This part of the manual is a tutorial introduction to the
OCaml language. A good familiarity with programming in a conventional
languages (say, Pascal or C) is assumed, but no prior exposure to
languages (say, C++ or Java) is assumed, but no prior exposure to

This comment has been minimized.

@Octachron

Octachron Dec 27, 2017

Contributor

I find this change detrimental: C++ or Java are too close from each other, readers might assume wrongly that a good familiarity with this family of language is required. If you are displeased with the relative obscurity of Pascal, one option might be to replace it with Javascript, Python, or any beginner language. Similarly, I see little point for replacing C with C++.

This comment has been minimized.

@jfehrle

jfehrle Dec 28, 2017

Author Contributor

I'll go with "C or Javascript".

They will be covered in more details later; for now, we concentrate on lists.
Predefined data structures include tuples, arrays, and lists. There are also
general mechanisms for defining your own data structures. These are records
and classes, which will be covered in more detail later; for now, we concentrate on lists.

This comment has been minimized.

@Octachron

Octachron Dec 27, 2017

Contributor

Introducing classes with the same level of importance as records and eclipsing variants is indeed a bad idea. People familiar with C++ or Java often misjudge the importance of classes in OCaml and this change may accentuate this problem. Contrarily echoing the title of the records and variants sections seems like a good idea. Mentioning that specialized data types like classes and polymorphic variants (and GADTs, extensible variants, and first-class modules) are also available might be a good compromise.

function defined above takes 2 arguments. Its type is therefore given as
"'a -> 'a list -> 'a list".
TODO: a sentence or two explaining why this notation was chosen and
why it's preferred (eg to be more similar to mathematical logic)

This comment has been minimized.

@Octachron

Octachron Dec 27, 2017

Contributor

Explaining briefly the type of insert sounds like a good idea. However, this paragraph seems a bit clumsy and makes it sound like the notation used is totally arbitrary and have no link with currying. I would rather have a short explanation on the fact that insert takes two arguments here; and another paragraph in the "Function as values" section describing currying and why the notation 'a -> 'b -> 'c is natural.

This comment has been minimized.

@jfehrle

jfehrle Dec 28, 2017

Author Contributor

The problem is that I don't know what should be said about the notation. I'm aware of currying but I couldn't explain why it is used and useful in OCaml. (Reading the wikipedia page on Currying doesn't cover that.)
I will drop the change unless one of you wants to suggest exact wording.

This comment has been minimized.

@Octachron

Octachron Dec 28, 2017

Contributor

A short description of the types may be enough here, more or less like the one used for sort may be enough here:

The type inferred for insert, 'a -> 'a list -> 'a list, means that insert takes two argument, an element of any type "'a" and a list of element of the same type "'a" and returns a list of the same type.

The explanation of partial application may be left to a later section and PR.

@@ -373,8 +383,24 @@ g r;;
\pdfsection{Exceptions}

OCaml provides exceptions for signalling and handling exceptional
conditions. Exceptions can also be used as a general-purpose non-local
control structure. Exceptions are declared with the "exception"
conditions.

This comment has been minimized.

@Octachron

Octachron Dec 27, 2017

Contributor

This change is far too opinionated, adding some words of caution might be fine, but not removing this sentence.

This comment has been minimized.

@jfehrle

jfehrle Dec 28, 2017

Author Contributor

I believe the clear consensus among Java developers is that exceptions should be used for truly exceptional conditions and not as a non-local go to or an alternate way of returning a value. AFAIK this is not at all a controversial opinion. But perhaps this doesn't carry over to OCaml, or the consensus among OCaml developers is different.

I could say something like this (or just drop the change): "Exceptions can also be used as a general-purpose non-local control structure, although this should not be overused since it can make the code harder to understand."

This comment has been minimized.

@Octachron

Octachron Dec 28, 2017

Contributor

the consensus among OCaml developers is different.

I don't think that there is a clear consensus on this subject to be honest.

"Exceptions can also be used as a general-purpose non-local control structure, although this should not be overused since it can make the code harder to understand."

This sounds good.

purpose control structure, which some would vigorously contest. My intention was to
remove a controversial statement. But certainly this can be left unchanged.

Can you explain how OCaml exceptions are more lightweight than in Java?

This comment has been minimized.

@Octachron

Octachron Dec 27, 2017

Contributor

May I suggest you to keep the discussion in the mantis ticket or in the github comments rather than in the source code itself?

This comment has been minimized.

@jfehrle

jfehrle Dec 28, 2017

Author Contributor

Sure. It was expedient. Discussion in Mantis is more awkward than in github, and I made about 4 pages of comments there. @dra suggested "some of the smaller changes would be easier to discuss if you are able/willing to contribute a pull request"

This comment has been minimized.

@Octachron

Octachron Dec 28, 2017

Contributor

Sorry, I have not yet had the time to answer your question on the Mantis ticket. It is true that discussion on Mantis is a bit awkward on splintered discussion, but hiding questions in commits is a bit limited too.

> the use of the word "messages" is largely accurate, I believe.

I'm sure "sending messages" is the commonly used term by some. But I think it's not
the term that would be used by Java/C++ developers. They would think of referencing

This comment has been minimized.

@Octachron

Octachron Dec 27, 2017

Contributor

Another point is that the manual is not aimed specifically to Java/C++ developper, it might be interesting to write an "OCaml for Java developpers" book but I do not think it is the primary objective of the manual. May I also repeat my statement that the manual source is not the place for a discussion?

This comment has been minimized.

@jfehrle

jfehrle Dec 28, 2017

Author Contributor

I don't advocate turning this into an "OCaml for <language> developers". But the "sending messages" seems quite confusing for someone used to conventional languages. (To me it suggests creating a buffer, writing data into it, somehow "sending", ...)

I take the statement in the first paragraph of Chapter 1 as a metric for evaluating the contents of Part I of the manual ("This part of the language is a tutorial introduction to the OCaml language. A good familiarity with programming in a conventional language (say, Pascal or C) is assumed, but no prior exposure to functional languages is required.") This particular wording seems not to meet that standard--in my opinion.

Surely there is a clearer way to express this idea. If we can quickly agree on something better, let's go with it. If not, let's drop the suggestion and move on to things we can agree on.

This comment has been minimized.

@Octachron

Octachron Dec 28, 2017

Contributor

But the "sending messages" seems quite confusing for someone used to conventional languages

I think that the message metaphore was one of the original explanation for OO (it is used in smalltalk for instance). But since the word is used only once in chapter, you are probably right that it should be paraphrased.

This comment has been minimized.

@xavierleroy

xavierleroy Dec 29, 2017

Contributor

Yes, "sending messages" is Smalltalk terminology, but Smalltalk is the birthplace of OOP. Time for some Alan Kay quotes:

Actually I made up the term "object-oriented", and I can tell you I did not have C++ in mind.

I'm sorry that I long ago coined the term "objects" for this topic because it gets many people to focus on the lesser idea. The big idea is "messaging"

This comment has been minimized.

@jfehrle

jfehrle Dec 29, 2017

Author Contributor

Yes, "sending messages" is Smalltalk terminology, but Smalltalk is the birthplace of OOP.
Time for some Alan Kay quotes:

Good quotes, but they recognize that common thinking/usage is not what Kay would prefer. Innovators put out their best ideas and the world may adapt them (or distort them or ignore them).

How about this? (And if not, I won't make any change here.)

A method or an initializer can send messages to self (that is,
the current object).  (Or, in the terms used in mainstream
languages such as Java and C++, a method or an initializer can call
methods on the current object.)

This comment has been minimized.

@Octachron

Octachron Jan 2, 2018

Contributor

I fear that this sounds more like an armistice statement rather than a simple explanation.
I think going to the simpler version,

A method or an initializer can invoke methods on self (that is, the current object).

would be fine. There is definitively merit to try to spread potentially better terminology, but I think that the internal coherency of the chapter is more important here: methods are introduced in the first section with

We now invoke some methods to p:

Thus, reusing invoke may help readers.

The "with" part is actually a regular pattern-matching on the
exception value. Thus, several exceptions can be caught by one
The "with" part does pattern matching on the
exception value with the same syntax and behavior as "match". Thus, several exceptions can be caught by one

This comment has been minimized.

@Octachron

Octachron Dec 27, 2017

Contributor

The original sentence seems clearer to me, why did you think it was unclear?

This comment has been minimized.

@jfehrle

jfehrle Dec 28, 2017

Author Contributor

My original comment in Mantis:

“The with part is actually a regular pattern-matching on the exception value.” “regular” makes me think of regular expressions. I think you mean it does the usual/normal pattern matching. Maybe
say “The with part does pattern matching on the exception value.”?

This comment has been minimized.

@Octachron

Octachron Dec 28, 2017

Contributor

or The "with" part is actually an usual pattern-matching on the exception value.
But your sentence seems fine too.

introduced on a global level. However, you can give explicitly
a data structure, keeping its polymorphism. Doing this requires
user-provided type annotation, since polymorphism is only introduced
automatically for global (top-level?) definitions.”

This comment has been minimized.

@Octachron

Octachron Dec 27, 2017

Contributor

global (top-level?) definitions."

First, there is a wandering " here. I would let global but the whole paragraph feels misplaced. I need to think about it.

This comment has been minimized.

@jfehrle

jfehrle Dec 28, 2017

Author Contributor

let global

You mean keep "global" or remove "(top-level)"?

This comment has been minimized.

@Octachron

Octachron Dec 28, 2017

Contributor

I think leaving global is alright here.

as arrays. Arrays are either given in extension between "[|" and "|]"
brackets, or allocated and initialized with the "Array.make"
as arrays. Arrays are either created by listing semicolon-separated element
values between "[|" and "|]" brackets, or allocated and initialized with the "Array.make"

This comment has been minimized.

@Octachron

Octachron Dec 27, 2017

Contributor

This is nice!

@@ -27,6 +27,8 @@ by ";;" in response to the "#" prompt, and the system compiles them
on the fly, executes them, and prints the outcome of evaluation.
Phrases are either simple expressions, or "let" definitions of
identifiers (either values or functions).
The ";;" is not necessary and generally not used in source files created
for use with the OCaml compiler.

This comment has been minimized.

@Octachron

Octachron Dec 27, 2017

Contributor

I think this sentence would fit much better in the "Standalone Ocaml programs" section.

This comment has been minimized.

@jfehrle

jfehrle Dec 28, 2017

Author Contributor

I'll move it. It seemed important to me to include so early because I've been looking at a lot of OCaml code in files. (Tangentially, many of the examples are far longer than you would ever type in to the top-level. In practice you would create files for them.)

The standalone OCaml program example at the end of page 24 uses ";;", which I think is not needed and so maybe should be removed.

This comment has been minimized.

@Octachron

Octachron Dec 28, 2017

Contributor

It seemed important to me to include so early because I've been looking at a lot of OCaml code in files

I agree that this an important point to keep in mind, at the same time this part of the manual is really focused on the interactive toplevel. Maybe a good option would be to add a forward reference or a footnote to the standalone program section for readers more interested in files.

The standalone OCaml program example at the end of page 24 uses ";;", which I think is not needed and so maybe should be removed.

This is an excellent idea!

This comment has been minimized.

@jfehrle

jfehrle Dec 29, 2017

Author Contributor

I can remove two of the ";;". The one after "exit" is needed (gives a compile error without it). (Still figuring out OCaml syntax.)

let rec fib n =
  if n < 2 then 1 else fib (n-1) + fib (n-2)
let main () =
  let arg = int_of_string Sys.argv.(1) in
  print_int (fib arg);
  print_newline ();
  exit 0;;
main ()

This comment has been minimized.

@Octachron

Octachron Dec 29, 2017

Contributor

A common OCaml idiom is to replace ;; main () with let () = main ().
An interpretation of the syntactical rule for ;; is that ;; is used to start (effectful) toplevel expressions.

@jfehrle jfehrle force-pushed the jfehrle:improve_doc branch 2 times, most recently from 002d84b to ff82ed4 Jan 6, 2018

@jfehrle jfehrle force-pushed the jfehrle:improve_doc branch 2 times, most recently from 9c90434 to 5d1e9fc Jan 21, 2018

@jfehrle

This comment has been minimized.

Copy link
Contributor Author

jfehrle commented Jan 21, 2018

I updated 'Changes', which should make the required Travis job pass. @Octachron, any further review comments?

@jfehrle jfehrle force-pushed the jfehrle:improve_doc branch from dc6464b to 266f73b Jan 21, 2018

@@ -564,10 +564,6 @@ expr_n ')'@ evaluates to the n-ary variant value whose constructor is
@constr@ and whose arguments are the values of @expr_1, \ldots,
expr_n@.

The expression @constr '('expr_1, \ldots, expr_n')'@ evaluates to the
variant value whose constructor is @constr@, and whose arguments are
the values of @expr_1 \ldots expr_n@.

This comment has been minimized.

@Octachron

Octachron Jan 21, 2018

Contributor

This change is an accident, isn'it?

This comment has been minimized.

@jfehrle

jfehrle Jan 21, 2018

Author Contributor

My bad. Fixed. Thanks for reviewing.

@Octachron

This comment has been minimized.

Copy link
Contributor

Octachron commented Jan 21, 2018

Overall, this looks fine; I will do a last review sometimes today.

@jfehrle jfehrle force-pushed the jfehrle:improve_doc branch from 266f73b to 87aa17e Jan 21, 2018

@Octachron
Copy link
Contributor

Octachron left a comment

I like the current changes, except for few minor nitpicking comments.

mechanisms for defining your own data structures are also provided.
They will be covered in more details later; for now, we concentrate on lists.
Predefined data structures include tuples, arrays, and lists. There are also
general mechanisms for defining your own data structures, such as records, which

This comment has been minimized.

@Octachron

Octachron Jan 21, 2018

Contributor

I would replace such as records by such as records and variants.

Functors are ``functions'' from modules to modules. Functors
let you create parameterized modules and then provide other modules as parameter(s)
to get a specific implementation. For instance, a "Set" module implementing sets
as sorted lists could be parameterized to work with any module that provides a type

This comment has been minimized.

@Octachron

Octachron Jan 21, 2018

Contributor

I would add a bit more context here: that provides a typethat provides a type of elements

This comment has been minimized.

@jfehrle

jfehrle Jan 21, 2018

Author Contributor

Made this "that provides an element type", more idiomatic.

let you create parameterized modules and then provide other modules as parameter(s)
to get a specific implementation. For instance, a "Set" module implementing sets
as sorted lists could be parameterized to work with any module that provides a type
and a comparison method "compare" (such as "OrderedString"):

This comment has been minimized.

@Octachron

Octachron Jan 21, 2018

Contributor

I would use comparison function rather than method to avoid a potential confusion with object methods.

@@ -2,15 +2,20 @@
\label{c:objectexamples}
\pdfchapterfold{-15}{Tutorial: Objects in OCaml}
%HEVEA\cutname{objectexamples.html}
{\it (Chapter written by J�r�me Vouillon, Didier R�my and Jacques Garrigue)}
{\it (Chapter written by J�r�me Vouillon, Didier R�my and Jacques Garrigue)}

This comment has been minimized.

@Octachron

Octachron Jan 21, 2018

Contributor

Am I a bit worried with this line, but this could be a problem with Github web interface. Could you check that this line does not exists in your local commit?

This comment has been minimized.

@jfehrle

jfehrle Jan 21, 2018

Author Contributor

It doesn't appear as a change when I diff the commit. It may be that Github is expecting UTF-8 encoding for the accented characters (and would have multibyte representation) but that are probably in ISO 8851-1 (single byte).

image

Other changes applied as you suggested.

@jfehrle jfehrle force-pushed the jfehrle:improve_doc branch from 87aa17e to 02cd0a2 Jan 21, 2018

@@ -4,7 +4,7 @@

This part of the manual is a tutorial introduction to the
OCaml language. A good familiarity with programming in a conventional
languages (say, Pascal or C) is assumed, but no prior exposure to
languages (say, C or Javascript) is assumed, but no prior exposure to
functional languages is required. The present chapter introduces the

This comment has been minimized.

@xavierleroy

xavierleroy Jan 22, 2018

Contributor

It pains me to see Javascript mentioned. When we give examples of "conventional languages", can we choose some that don't completely suck? Java might do.

This comment has been minimized.

@jfehrle

jfehrle Jan 22, 2018

Author Contributor

I originally mentioned Java, but the reviewer @Octachron thought that was too similar to C. I'll change it back to Java.

This comment has been minimized.

@Octachron

Octachron Jan 22, 2018

Contributor

I think I may have overeacted on your proposed couple (C++, Java), I am perfectly fine with (C, Java), even if the pair feels a bit close phylogenetically.

This comment has been minimized.

@xavierleroy

xavierleroy Jan 22, 2018

Contributor

Apologies for the back-and-forth. Java is a good middle ground here.

exit 0;;
main ();;
exit 0
let () = main ()
\end{verbatim}

This comment has been minimized.

@xavierleroy

xavierleroy Jan 22, 2018

Contributor

The let () = ... trick is idiomatic but not intuitive at all. I see newcomers shaking their heads here.

This comment has been minimized.

@jfehrle

jfehrle Jan 22, 2018

Author Contributor

Upon further reflection, I reverted the changes to the example and modified one sentence:

The ";;" used
in the interactive examples is not required in
source files created for use with the OCaml compiler, but can be helpful
to unambiguously mark the end of a top-level expression even when
there are syntax errors.

This comment has been minimized.

@xavierleroy

xavierleroy Jan 22, 2018

Contributor

That's reasonable. The alternative would be to explain the let () = or let _ = trick, but that can wait for another round of editing.

@@ -219,7 +224,7 @@ in sections \ref{ss:reference-to-self} and \ref{ss:parameterized-classes}.
\pdfsection{Reference to self}
\label{ss:reference-to-self}

A method or an initializer can send messages to self (that is,
A method or an initializer can invoke methods on self (that is,
the current object). For that, self must be explicitly bound, here to

This comment has been minimized.

@xavierleroy

xavierleroy Jan 22, 2018

Contributor

Not sure about this use of "on" in "invoke methods on self".

This comment has been minimized.

@jfehrle

jfehrle Jan 22, 2018

Author Contributor

"methods on self" is commonly used, at least in the Java world.
How about "methods of self"?

This comment has been minimized.

@xavierleroy

xavierleroy Jan 22, 2018

Contributor

As you wish. I just wanted to make sure that "on" was not a typo for "of". But if "on" feels idiomatic to you, fine.

@shindere

This comment has been minimized.

Copy link
Contributor

shindere commented Jan 22, 2018

@xavierleroy

This comment has been minimized.

Copy link
Contributor

xavierleroy commented Jan 22, 2018

Python is a lot more respectable than JavaScript, but to me it still hails from the "scripting languages" family more than from the "conventional languages" family. But, yes, it is the most "conventional" of the "scripting" languages, if this distinction makes any sense...

@jfehrle jfehrle force-pushed the jfehrle:improve_doc branch 2 times, most recently from 3ff5435 to 7db8c00 Jan 22, 2018

@dra27 dra27 added the suspended label Jan 22, 2018

@dra27
Copy link
Contributor

dra27 left a comment

I've only skimmed the technical discussions so far, so this is principally a review of the final language. It all looks like a nice improvement - main gripe for requesting changes is that there's still an editor encoding artefact present on some accented characters.

They will be covered in more details later; for now, we concentrate on lists.
Predefined data structures include tuples, arrays, and lists. There are also
general mechanisms for defining your own data structures, such as records and
variants, which

This comment has been minimized.

@dra27

dra27 Jan 22, 2018

Contributor

Line-break shouldn't be here

This comment has been minimized.

@jfehrle

jfehrle Jan 22, 2018

Author Contributor

Is it really necessary to fill and justify the rest of the paragraph (the next 5 lines) in the tex source when it has no effect on the appearance of the output? Seems to me it just makes more tedium for the editor and generates extraneous diffs in github. What is your thinking on this?

This comment has been minimized.

@dra27

dra27 Jan 23, 2018

Contributor

I'm not sure what the standard for the manual is (@Octachron?), but this would certainly be yes for the main code base (e.g. for a re-worded documentation comment). While I completely agree that minimising diffs is important, so are coding standards and there are several places where I think the new lines also exceed the 80 char limit.

You're also assuming that the manual is only read after being TeX'd, but maybe I'm strange...

This comment has been minimized.

@jfehrle

jfehrle Jan 23, 2018

Author Contributor

How about if we go for whatever @Octachron suggests?

(Adhering strictly to an 80 character limit is, BTW, an additional manual step for me--tedious to inspect and correct. There should be a tool to take care of this. But let's not dive into this debate.)

This comment has been minimized.

@Octachron

Octachron Jan 23, 2018

Contributor

For now, I don't think that there is a strongly enforced character-limit, even if the manual tend to follow a soft-limit of 70-72 characters.

However, I agree that this line-break disrupts the reading flow, and the changes required for respecting the character limit are very moderate:

variants, which will be covered in more detail later; for now, we concentrate
on lists. Lists are either given in extension as a bracketed list of

Note that for inspecting the 80 character limit, you can use the check-typo tools in the tools: ./tools/check-typo manual/manual/tutorials show that there is three new lines that goes beyond the character limit (the other lines were already here before), but this this can be fixed later.

This comment has been minimized.

@jfehrle

jfehrle Jan 23, 2018

Author Contributor

I made all my changes less than 80 characters wide. Hope we're good now.

@@ -110,11 +111,16 @@ sort [3.14; 2.718];;
The "sort" function above does not modify its input list: it builds
and returns a new list containing the same elements as the input list,
in ascending order. There is actually no way in OCaml to modify
in-place a list once it is built: we say that lists are {\em immutable}
a list in place once it is built: we say that lists are {\em immutable}

This comment has been minimized.

@dra27

dra27 Jan 22, 2018

Contributor

This should still be in-place with a hyphen, though the ordering is of course better.

This comment has been minimized.

@jfehrle

jfehrle Jan 22, 2018

Author Contributor

"in place" is the common English usage, not "in-place", right? I moved the word and made this improvement.

This comment has been minimized.

@dra27

dra27 Jan 23, 2018

Contributor

It's not common English, though - it's a technical term. cf. https://en.wikipedia.org/wiki/In-place_algorithm

This comment has been minimized.

@jfehrle

jfehrle Jan 23, 2018

Author Contributor

OK

"arg1_type -> arg2_type -> ... -> return_type". For example,
the type inferred for insert, "'a -> 'a list -> 'a list", means that insert
takes two arguments, an element of any type "'a" and a list of elements of
the same type "'a" and returns a list of the same type.

This comment has been minimized.

@dra27

dra27 Jan 22, 2018

Contributor

@Octachron - does the style of the manual does require some kind of formatting when referring to the insert function, too?

(text looks great, though!)

This comment has been minimized.

@Octachron

Octachron Jan 22, 2018

Contributor

I missed this point: Using "insert" when refering to the function named insert would be better (but not strictly required).

type annotations, this is not allowed, as polymorphism is only
introduced on a global level. However, you can give explicitly
a data structure, keeping its polymorphism. Doing this requires
user-provided type annotation, since polymorphism is only introduced

This comment has been minimized.

@dra27

dra27 Jan 22, 2018

Contributor

Either "Doing this requires a user-provided type annotation" or "Doing this requires user-provided type annotations" (or the third possibility "Doing this requires user-providing type annotating", however I'm neutral on the first two options, but dislike this one!)

@@ -409,11 +416,12 @@ name_of_binary_digit 0;;
name_of_binary_digit (-1);;
\end{caml_example}

The "with" part is actually a regular pattern-matching on the
exception value. Thus, several exceptions can be caught by one
The "with" part does pattern matching on the

This comment has been minimized.

@dra27

dra27 Jan 22, 2018

Contributor

I would personally say performs rather than does

@@ -2,15 +2,20 @@
\label{c:objectexamples}
\pdfchapterfold{-15}{Tutorial: Objects in OCaml}
%HEVEA\cutname{objectexamples.html}
{\it (Chapter written by J�r�me Vouillon, Didier R�my and Jacques Garrigue)}
{\it (Chapter written by J�r�me Vouillon, Didier R�my and Jacques Garrigue)}

This comment has been minimized.

@dra27

dra27 Jan 22, 2018

Contributor

Editor encoding artefact?

This comment has been minimized.

@jfehrle

jfehrle Jan 22, 2018

Author Contributor

My local repository doesn't show any difference here, @Octachron thought it might be a github diff-code glitch because of the character encoding (ISO 8859-1 single byte vs UTF-8).

This comment has been minimized.

@Octachron

Octachron Jan 22, 2018

Contributor

A safer solution might be to use (Chapter written by J\'er\^ome Vouillon, Didier R\'emy and Jacques Garrigue) and then we could discuss later to change the encoding of the manual to utf-8.

This comment has been minimized.

@jfehrle

jfehrle Jan 22, 2018

Author Contributor

I applied @Octachron 's suggestion.

This comment has been minimized.

@dra27

dra27 Jan 23, 2018

Contributor

Note quite correctly, though - the letters themselves are missing after the accents. J\'er\^ome and R\'emy

This comment has been minimized.

@jfehrle

jfehrle Jan 23, 2018

Author Contributor

Doh. Fixed.

OCaml.

Note that the relationship between object, class and type in OCaml is different than
in Java and C++, so you shouldn't assume that similar keywords mean the same thing.

This comment has been minimized.

@dra27

dra27 Jan 22, 2018

Contributor

"is different than differs from in Java and C++, so you one shouldn't assume that similar keywords mean the same thing have the same meaning."? (I realise the last part is not your text originally!)

This comment has been minimized.

@jfehrle

jfehrle Jan 22, 2018

Author Contributor

These seem rather subjective--no single right/best way to word this.

As I see it: "... in OCaml is different than in Java and C++' has simple parallel construction with the 2 uses of "in <languages>". The bold part in your suggested "Note that the relationship between object, class and type in OCaml differs from in Java and C++" is itself awkward; "differs from that in" is more specific but feels pedantic.

"you" vs. "one": the document uses "you" and "your" in many places. Less formal and friendlier, seems OK to me.

"have the same meaning" vs "mean the same thing". The latter is a more active construction, the former is sort of a passive voice.

Note that the relationship between object, class and type in OCaml is different than
in Java and C++, so you shouldn't assume that similar keywords mean the same thing.
Object-oriented features are used much less frequently in OCaml than
in mainstream object-oriented languages such as Java and C++. OCaml has other

This comment has been minimized.

@dra27

dra27 Jan 22, 2018

Contributor

The repetition of "such as Java and C++" is unnecessary here, IMO.

The word "other" is tautologous - "OCaml has alternatives"

This comment has been minimized.

@jfehrle

jfehrle Jan 22, 2018

Author Contributor

I made it:

Note that the relationship between object, class and type in OCaml is different than
in mainstream object-oriented languages such as Java and C++, so you shouldn't assume
that similar keywords mean the same thing.
Object-oriented features are used much less frequently in OCaml than
in those languages.  OCaml has other
alternatives that are often more appropriate, such as modules and functors.  Many
OCaml programs do not use objects at all.

From the dictionary: an alternative is "one of two or more available possibilities." Using obect-oriented features is an alternative in OCaml. "other alternatives" emphasizes excluding using object-oriented features. But if you feel strongly I will drop "other".

This comment has been minimized.

@dra27

dra27 Jan 23, 2018

Contributor

Feel strongly is perhaps strong (!), but it mentions one thing (the object system) and then refers to the alternatives. To refer to the "other alternatives", there should be a reference to at least one alternative between the reference to the object system and the "other alternatives". 🙂

I like your point of wanting emphasis, though - perhaps it could be made by saying "several/many alternatives"?

This comment has been minimized.

@jfehrle

jfehrle Jan 23, 2018

Author Contributor

Ah, I suspect we're not going to agree here so I will remove "other". In the bigger picture it doesn't matter.

To refer to the "other alternatives", there should be a reference to at least one alternative between the reference to the object system and the "other alternatives".

An alternative is "one of two or more available possibilities." Using object-oriented features is implicitly an alternative in OCaml since they they "are used much less frequently in OCaml".

This comment has been minimized.

@Octachron

Octachron Jan 23, 2018

Contributor

Stepping in as a non-native speaker, alternative has also a strong underlying connotation of another choice; and in other alternatives one may wonder if other is an emphatic redundancy or refers to yet another other possibility. I would prefer either several alternatives or other possibilities and avoid the potential ambiguity (and nuance) of the double negation in other alternatives.

in Java and C++, so you shouldn't assume that similar keywords mean the same thing.
Object-oriented features are used much less frequently in OCaml than
in mainstream object-oriented languages such as Java and C++. OCaml has other
alternatives that are often more appropriate, such as modules and functors. Many

This comment has been minimized.

@dra27

dra27 Jan 22, 2018

Contributor

Nit: "which", rather than "that"

This comment has been minimized.

@jfehrle

jfehrle Jan 22, 2018

Author Contributor

Though "which" may be more correct, I think "that" is the more common usage. I would have to look up the rule for when to use "which". The language evolves...

This comment has been minimized.

@dra27

dra27 Jan 23, 2018

Contributor

Depends on your ivory tower (and definition of "evolution") 😉

Object-oriented features are used much less frequently in OCaml than
in mainstream object-oriented languages such as Java and C++. OCaml has other
alternatives that are often more appropriate, such as modules and functors. Many
OCaml programs do not use objects at all.

This comment has been minimized.

@dra27

dra27 Jan 22, 2018

Contributor

Perhaps "Indeed, many OCaml programs do not use the object system at all."?

This comment has been minimized.

@jfehrle

jfehrle Jan 22, 2018

Author Contributor

I added "indeed" but kept "objects".

@dra27 dra27 removed the suspended label Jan 22, 2018

@jfehrle jfehrle force-pushed the jfehrle:improve_doc branch 3 times, most recently from e1ab2a6 to 0ef05ad Jan 22, 2018

@dra27

dra27 approved these changes Jan 24, 2018

@dra27

This comment has been minimized.

Copy link
Contributor

dra27 commented Jan 24, 2018

LGTM, thank you!

@Octachron

This comment has been minimized.

Copy link
Contributor

Octachron commented Jan 24, 2018

@jfehrle , would you mind updating the list of reviewers? I will merge after this last details.

@jfehrle jfehrle force-pushed the jfehrle:improve_doc branch from 0ef05ad to a324021 Jan 24, 2018

@jfehrle

This comment has been minimized.

Copy link
Contributor Author

jfehrle commented Jan 24, 2018

I added David to the list of reviewers. Thanks, guys.

@jfehrle jfehrle force-pushed the jfehrle:improve_doc branch from a324021 to 52454d3 Jan 25, 2018

Merge pull request #1 from Octachron/pr/1545
manual: last minute  fixes

@Octachron Octachron merged commit 261c714 into ocaml:trunk Jan 25, 2018

2 checks passed

continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
@Octachron

This comment has been minimized.

Copy link
Contributor

Octachron commented Jan 25, 2018

Merged. Thank you for you contribution, and your patience during the review process!

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.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.