adapt the manual to discourage labels-omitted applications

manual/src/cmds/comp.etex

@@ -358,6 +358,41 @@ command line, and possibly the "-custom" option.
 
 This section describes and explains in detail some warnings:
 
+\subsection{ss:warn6}{Warning 6: Label omitted in function application}
+
+OCaml supports "labels-omitted" full applications: if the function has
+a known arity, all the arguments are unlabeled, and their number
+matches the number of non-optional parameters, then labels are ignored
+and non-optional parameters are matched in their definition
+order. Optional arguments are defaulted.
+
+\begin{verbatim}
+let f ~x ~y = x + y
+let test = f 2 3
+
+> let test = f 2 3
+>            ^
+> Warning 6 [labels-omitted]: labels x, y were omitted in the application of this function.
+\end{verbatim}
+
+This support for "labels-omitted" application was introduced when
+labels were added to OCaml, to ease the progressive introduction of
+labels in a codebase. However, it has the downside of weakening the
+labeling discipline: if you use labels to prevent callers from
+mistakenly reordering two parameters of the same type, labels-omitted
+make this mistake possible again.
+
+Warning 6 warns when labels-omitted applications are used, to
+discourage their use. When labels were introduced, this warning was
+not enabled by default, so users would use labels-omitted
+applications, often without noticing.
+
+Over time, it has become idiomatic to enable this warning to avoid
+argument-order mistakes. The warning is now on by default, since OCaml
+4.13. Labels-omitted applications are not recommended anymore, but
+users wishing to preserve this transitory style can disable the
+warning explicitly.
+
 \subsection{ss:warn9}{Warning 9: missing fields in a record pattern}
 
   When pattern matching on records, it can be useful to match only few

manual/src/refman/expr.etex

@@ -293,24 +293,18 @@ let fullname ?title first second =
 let name = fullname "Jane" "Fisher";;
 \end{caml_example}
 
-As a special case, if the function has a known arity, all the
-arguments are unlabeled, and their number matches the number of
-non-optional parameters, then labels are ignored and non-optional
-parameters are matched in their definition order. Optional arguments
-are defaulted.
-
-\begin{caml_example}{toplevel}
-let f ~a ?b c = 
-  match b with Some n -> a + n + c | None -> a + c
-
-let r = f 2 3;;
-\end{caml_example}
-
 In all cases but exact match of order and labels, without optional
 parameters, the function type should be known at the application
 point.  This can be ensured by adding a type constraint.  Principality
 of the derivation can be checked in the "-principal" mode.
 
+As a special case, OCaml supports "labels-omitted" full applications:
+if the function has a known arity, all the arguments are unlabeled,
+and their number matches the number of non-optional parameters, then
+labels are ignored and non-optional parameters are matched in their
+definition order. Optional arguments are defaulted. This omission of
+labels is discouraged and results in a warning, see \ref{ss:warn6}.
+
 \subsubsection*{sss:expr-function-definition}{Function definition}
 
 Two syntactic forms are provided to define functions. The first form

manual/src/tutorials/lablexamples.etex

@@ -69,35 +69,6 @@ let hline ~x:x1 ~x:x2 ~y = (x1, x2, y);;
 hline ~x:3 ~y:2 ~x:5;;
 \end{caml_example}
 
-As an exception to the above parameter matching rules, if an
-application is total (omitting all optional arguments), labels may be
-omitted.
-In practice, many applications are total, so that labels can often be
-omitted.
-\begin{caml_example}{toplevel}
-f 3 2;;
-ListLabels.map succ [1;2;3];;
-\end{caml_example}
-But beware that functions like "ListLabels.fold_left" whose result
-type is a type variable will never be considered as totally applied.
-\begin{caml_example}{toplevel}[error]
-ListLabels.fold_left ( + ) 0 [1;2;3];;
-\end{caml_example}
-
-When a function is passed as an argument to a higher-order function,
-labels must match in both types. Neither adding nor removing labels
-are allowed.
-\begin{caml_example}{toplevel}
-let h g = g ~x:3 ~y:2;;
-h f;;
-h ( + ) [@@expect error];;
-\end{caml_example}
-Note that when you don't need an argument, you can still use a wildcard
-pattern, but you must prefix it with the label.
-\begin{caml_example}{toplevel}
-h (fun ~x:_ ~y -> y+1);;
-\end{caml_example}
-
 \subsection{ss:optional-arguments}{Optional arguments}
 
 An interesting feature of labeled arguments is that they can be made