PR#7363: start documentation headers at {1

43 files changed, 273 insertions, 272 deletions

diff --git a/manual/tools/caml_tex2.ml b/manual/tools/caml_tex2.ml
index c0d4380f9c..976bacd4e3 100644
--- a/manual/tools/caml_tex2.ml
+++ b/manual/tools/caml_tex2.ml
@@ -87,13 +87,13 @@ module Output = struct
     | Ok -> Printf.fprintf ppf "an ok"
     | Warning n -> Printf.fprintf ppf "a warning %d" n
 
-  (** {2 Related latex environment } *)
+  (** {1 Related latex environment } *)
   let env = function
     | Error -> error
     | Warning _ -> warning
     | Ok -> ok_output
 
-  (** {2 Exceptions } *)
+  (** {1 Exceptions } *)
   exception Parsing_error of kind * string
 
   type source = { file:string; lines:int * int; phrase:string; output:string }
@@ -141,7 +141,7 @@ module Output = struct
            and [@@expect warning n] (with n a warning number).\n" s
 
 
-  (** {2 Output analysis} *)
+  (** {1 Output analysis} *)
   let catch_error s =
     if string_match ~!{|Error:|} s 0 then Some Error else None
 
@@ -156,7 +156,7 @@ module Output = struct
     | None, Some e -> e
     | None, None -> Ok
 
-  (** {2 Parsing caml_example options } *)
+  (** {1 Parsing caml_example options } *)
 
   (** Parse [warning=n] options for caml_example options *)
   let parse_warning s =
diff --git a/ocamldoc/odoc_class.ml b/ocamldoc/odoc_class.ml
index 2d811ecc22..b25d89c513 100644
--- a/ocamldoc/odoc_class.ml
+++ b/ocamldoc/odoc_class.ml
@@ -94,7 +94,7 @@ and t_class_type = {
   }
 
 
-(** {2 Functions} *)
+(** {1 Functions} *)
 
 (** Returns the text associated to the given parameter label
    in the given class, or None. *)
diff --git a/ocamldoc/odoc_info.mli b/ocamldoc/odoc_info.mli
index a60cfcdd69..2a2d80ea1c 100644
--- a/ocamldoc/odoc_info.mli
+++ b/ocamldoc/odoc_info.mli
@@ -135,7 +135,7 @@ module Name :
 (** Representation and manipulation of method / function / class / module parameters.*)
 module Parameter :
   sig
-    (** {3 Types} *)
+    (** {2 Types} *)
 
     (** Representation of a simple parameter name *)
     type simple_name = Odoc_parameter.simple_name =
@@ -154,7 +154,7 @@ module Parameter :
     (** A parameter is just a param_info.*)
     type parameter = param_info
 
-    (** {3 Functions} *)
+    (** {2 Functions} *)
 
     (** Access to the name as a string. For tuples, parentheses and commas are added. *)
     val complete_name : parameter -> string
@@ -343,7 +343,7 @@ module Value :
 (** Representation and manipulation of classes and class types.*)
 module Class :
   sig
-    (** {3 Types} *)
+    (** {2 Types} *)
 
     (** To keep the order of elements in a class. *)
     type class_element = Odoc_class.class_element =
@@ -429,7 +429,7 @@ module Class :
           mutable clt_loc : location ;
         }
 
-    (** {3 Functions} *)
+    (** {2 Functions} *)
 
     (** Access to the elements of a class. *)
     val class_elements : ?trans:bool -> t_class -> class_element list
@@ -465,7 +465,7 @@ module Class :
 (** Representation and manipulation of modules and module types. *)
 module Module :
   sig
-    (** {3 Types} *)
+    (** {2 Types} *)
 
     (** To keep the order of elements in a module. *)
     type module_element = Odoc_module.module_element =
@@ -570,7 +570,7 @@ module Module :
           mutable mt_loc : location ;
         }
 
-    (** {3 Functions for modules} *)
+    (** {2 Functions for modules} *)
 
     (** Access to the elements of a module. *)
     val module_elements : ?trans:bool -> t_module -> module_element list
@@ -620,7 +620,7 @@ module Module :
     (** The list of module comments. *)
     val module_comments : ?trans:bool-> t_module -> text list
 
-    (** {3 Functions for module types} *)
+    (** {2 Functions for module types} *)
 
     (** Access to the elements of a module type. *)
     val module_type_elements : ?trans:bool-> t_module_type -> module_element list
@@ -669,7 +669,7 @@ module Module :
   end
 
 
-(** {3 Getting strings from values} *)
+(** {2 Getting strings from values} *)
 
 (** This function is used to reset the names of type variables.
    It must be called when printing the whole type of a function,
@@ -749,7 +749,7 @@ val string_of_attribute : Value.t_attribute -> string
 (** @return a string to describe the given method. *)
 val string_of_method : Value.t_method -> string
 
-(** {3 Miscellaneous functions} *)
+(** {2 Miscelaneous functions} *)
 
 (** Return the first sentence (until the first dot followed by a blank
    or the first blank line) of a text.
@@ -1036,7 +1036,7 @@ module Dep :
     val deps_of_types : ?kernel: bool -> Type.t_type list -> (Type.t_type * (Name.t list)) list
   end
 
-(** {2 Some global variables} *)
+(** {1 Some global variables} *)
 
 module Global :
   sig
diff --git a/ocamldoc/odoc_module.ml b/ocamldoc/odoc_module.ml
index 90b5723ffb..790a812d54 100644
--- a/ocamldoc/odoc_module.ml
+++ b/ocamldoc/odoc_module.ml
@@ -107,7 +107,7 @@ and t_module_type = {
   }
 
 
-(** {2 Functions} *)
+(** {1 Functions} *)
 
 (** Returns the list of values from a list of module_element. *)
 let values l =
@@ -543,7 +543,7 @@ let module_type_simple_values ?(trans=true) mt =
     (fun v -> not (Odoc_value.is_function v))
     (values (module_type_elements ~trans mt))
 
-(** {2 Functions for modules and module types} *)
+(** {1 Functions for modules and module types} *)
 
 (** The list of classes defined in this module and all its modules, functors, ....
   @param trans indicates if, for aliased modules, we must perform a transitive search.*)
diff --git a/ocamldoc/odoc_texi.ml b/ocamldoc/odoc_texi.ml
index 899dbafb80..f722fc595a 100644
--- a/ocamldoc/odoc_texi.ml
+++ b/ocamldoc/odoc_texi.ml
@@ -29,7 +29,7 @@ let info_section = ref "OCaml"
 
 let info_entry = ref []
 
-(** {2 Some small helper functions} *)
+(** {1 Some small helper functions} *)
 
 let puts_nl chan s =
   output_string chan s ;
@@ -240,12 +240,13 @@ end
 
 
 
-(** {2 Generation of Texinfo code} *)
+(** {1 Generation of Texinfo code} *)
 
 (** This class generates Texinfo code from text structures *)
 class text =
   object(self)
 
+
   (** Associations between a title number and texinfo code. *)
     val titles = [
       0, "@chapter " ;
@@ -283,7 +284,7 @@ class text =
         (List.map self#texi_of_text_element t)
 
 
-    (** {3 Conversion methods}
+    (** {2 Conversion methods}
        [texi_of_????] converts a [text_element] to a Texinfo string. *)
 
     (** Return the Texinfo code for the [text_element] in parameter. *)
@@ -401,7 +402,7 @@ class texi =
     inherit text
     inherit Odoc_to_text.to_text as to_text
 
-    (** {3 Small helper stuff.} *)
+    (** {2 Small helper stuff.} *)
 
     val maxdepth = 4
 
@@ -455,7 +456,7 @@ class texi =
             | Raw s -> Raw (Str.global_replace re rep s)
             | txt -> txt) t
 
-    (** {3 [text] values generation}
+    (** {2 [text] values generation}
        Generates [text] values out of description parts.
        Redefines some of methods of {! Odoc_to_text.to_text}. *)
 
@@ -567,7 +568,7 @@ class texi =
     method texi_of_info i =
       self#texi_of_text (self#text_of_info i)
 
-    (** {3 Conversion of [module_elements] into Texinfo strings}
+    (** {2 Conversion of [module_elements] into Texinfo strings}
        The following functions convert [module_elements] and their
        description to [text] values then to Texinfo strings using the
        functions above. *)
@@ -909,7 +910,7 @@ class texi =
           self#texi_of_text (Newline :: t @ [Newline])
       )
 
-    (** {3 Generating methods }
+    (** {2 Generating methods }
        These methods write Texinfo code to an [out_channel] *)
 
     (** Generate the Texinfo code for the given list of inherited classes.*)
diff --git a/otherlibs/bigarray/bigarray.mli b/otherlibs/bigarray/bigarray.mli
index 39d5bbb030..cadd04a610 100644
--- a/otherlibs/bigarray/bigarray.mli
+++ b/otherlibs/bigarray/bigarray.mli
@@ -32,7 +32,7 @@
      and {!Pervasives.input_value}).
 *)
 
-(** {6 Element kinds} *)
+(** {1 Element kinds} *)
 
 (** Big arrays can contain elements of the following kinds:
 - IEEE single precision (32 bits) floating-point numbers
@@ -179,7 +179,7 @@ val kind_size_in_bytes : ('a, 'b) kind -> int
 
    @since 4.03.0 *)
 
-(** {6 Array layouts} *)
+(** {1 Array layouts} *)
 
 type c_layout = CamlinternalBigarray.c_layout = C_layout_typ (**)
 (** See {!Bigarray.fortran_layout}.*)
@@ -224,7 +224,7 @@ val c_layout : c_layout layout
 val fortran_layout : fortran_layout layout
 
 
-(** {6 Generic arrays (of arbitrarily many dimensions)} *)
+(** {1 Generic arrays (of arbitrarily many dimensions)} *)
 
 module Genarray :
   sig
@@ -447,7 +447,7 @@ Note that Bigarray.Genarray.map_file raises Sys_error while\n\
 Unix.map_file raises Unix_error."]
   end
 
-(** {6 Zero-dimensional arrays} *)
+(** {1 Zero-dimensional arrays} *)
 
 (** Zero-dimensional arrays. The [Array0] structure provides operations
    similar to those of {!Bigarray.Genarray}, but specialized to the case
@@ -504,7 +504,7 @@ module Array0 : sig
 end
 
 
-(** {6 One-dimensional arrays} *)
+(** {1 One-dimensional arrays} *)
 
 (** One-dimensional arrays. The [Array1] structure provides operations
    similar to those of
@@ -611,7 +611,7 @@ Unix.map_file raises Unix_error."]
 end
 
 
-(** {6 Two-dimensional arrays} *)
+(** {1 Two-dimensional arrays} *)
 
 (** Two-dimensional arrays. The [Array2] structure provides operations
    similar to those of {!Bigarray.Genarray}, but specialized to the
@@ -734,7 +734,7 @@ Unix.map_file raises Unix_error."]
 
 end
 
-(** {6 Three-dimensional arrays} *)
+(** {1 Three-dimensional arrays} *)
 
 (** Three-dimensional arrays. The [Array3] structure provides operations
    similar to those of {!Bigarray.Genarray}, but specialized to the case
@@ -882,7 +882,7 @@ Unix.map_file raises Unix_error."]
 
 end
 
-(** {6 Coercions between generic big arrays and fixed-dimension big arrays} *)
+(** {1 Coercions between generic big arrays and fixed-dimension big arrays} *)
 
 external genarray_of_array0 :
   ('a, 'b, 'c) Array0.t -> ('a, 'b, 'c) Genarray.t = "%identity"
@@ -926,7 +926,7 @@ val array3_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Array3.t
    does not have exactly three dimensions. *)
 
 
-(** {6 Re-shaping big arrays} *)
+(** {1 Re-shaping big arrays} *)
 
 val reshape : ('a, 'b, 'c) Genarray.t -> int array -> ('a, 'b, 'c) Genarray.t
 (** [reshape b [|d1;...;dN|]] converts the big array [b] to a
diff --git a/otherlibs/dynlink/dynlink.mli b/otherlibs/dynlink/dynlink.mli
index 39b3ea62d7..fabbe6d310 100644
--- a/otherlibs/dynlink/dynlink.mli
+++ b/otherlibs/dynlink/dynlink.mli
@@ -19,7 +19,7 @@ val is_native: bool
 (** [true] if the program is native,
     [false] if the program is bytecode. *)
 
-(** {6 Dynamic loading of compiled files} *)
+(** {1 Dynamic loading of compiled files} *)
 
 val loadfile : string -> unit
 (** In bytecode: load the given bytecode object file ([.cmo] file) or
@@ -42,7 +42,7 @@ val adapt_filename : string -> string
 (** In bytecode, the identity function. In native code, replace the last
     extension with [.cmxs]. *)
 
-(** {6 Access control} *)
+(** {1 Access control} *)
 
 val allow_only: string list -> unit
 (** [allow_only units] restricts the compilation units that
@@ -81,7 +81,7 @@ val allow_unsafe_modules : bool -> unit
     not allowed. In native code, this function does nothing; object files
     with external functions are always allowed to be dynamically linked. *)
 
-(** {6 Deprecated, low-level API for access control} *)
+(** {1 Deprecated, low-level API for access control} *)
 
 (** @deprecated  The functions [add_interfaces], [add_available_units]
     and [clear_available_units] should not be used in new programs,
@@ -109,13 +109,13 @@ val clear_available_units : unit -> unit
 (** Empty the list of compilation units accessible to dynamically-linked
     programs. *)
 
-(** {6 Deprecated, initialization} *)
+(** {1 Deprecated, initialization} *)
 
 val init : unit -> unit
 (** @deprecated Initialize the [Dynlink] library. This function is called
     automatically when needed. *)
 
-(** {6 Error reporting} *)
+(** {1 Error reporting} *)
 
 type linking_error =
     Undefined_global of string
@@ -143,6 +143,6 @@ val error_message : error -> string
 
 (**/**)
 
-(** {6 Internal functions} *)
+(** {1 Internal functions} *)
 
 val digest_interface : string -> string list -> Digest.t
diff --git a/otherlibs/graph/graphics.mli b/otherlibs/graph/graphics.mli
index e364f6e099..2373241cba 100644
--- a/otherlibs/graph/graphics.mli
+++ b/otherlibs/graph/graphics.mli
@@ -19,7 +19,7 @@ exception Graphic_failure of string
 (** Raised by the functions below when they encounter an error. *)
 
 
-(** {6 Initializations} *)
+(** {1 Initializations} *)
 
 val open_graph : string -> unit
 (** Show the graphics window or switch the screen to graphic mode.
@@ -53,7 +53,7 @@ external size_y : unit -> int = "caml_gr_size_y"
    16-bit integers, hence wrong clipping may occur with coordinates
    below [-32768] or above [32676]. *)
 
-(** {6 Colors} *)
+(** {1 Colors} *)
 
 type color = int
 (** A color is specified by its R, G, B components. Each component
@@ -93,7 +93,7 @@ val cyan : color
 val magenta : color
 
 
-(** {6 Point and line drawing} *)
+(** {1 Point and line drawing} *)
 
 external plot : int -> int -> unit = "caml_gr_plot"
 (** Plot the given point with the current drawing color. *)
@@ -184,7 +184,7 @@ val set_line_width : int -> unit
    used when [set_line_width 1] is specified.
    Raise [Invalid_argument] if the argument is negative. *)
 
-(** {6 Text drawing} *)
+(** {1 Text drawing} *)
 
 external draw_char : char -> unit = "caml_gr_draw_char"
 (** See {!Graphics.draw_string}.*)
@@ -209,7 +209,7 @@ external text_size : string -> int * int = "caml_gr_text_size"
    the current font and size. *)
 
 
-(** {6 Filling} *)
+(** {1 Filling} *)
 
 val fill_rect : int -> int -> int -> int -> unit
 (** [fill_rect x y w h] fills the rectangle with lower left corner
@@ -233,7 +233,7 @@ val fill_circle : int -> int -> int -> unit
    parameters are the same as for {!Graphics.draw_circle}. *)
 
 
-(** {6 Images} *)
+(** {1 Images} *)
 
 type image
 (** The abstract type for images, in internal representation.
@@ -277,7 +277,7 @@ external blit_image : image -> int -> int -> unit = "caml_gr_blit_image"
    [img] are left unchanged. *)
 
 
-(** {6 Mouse and keyboard events} *)
+(** {1 Mouse and keyboard events} *)
 
 type status =
   { mouse_x : int;              (** X coordinate of the mouse *)
@@ -316,7 +316,7 @@ val loop_at_exit : event list -> (status -> unit) -> unit
     @since 4.01
 *)
 
-(** {6 Mouse and keyboard polling} *)
+(** {1 Mouse and keyboard polling} *)
 
 val mouse_pos : unit -> int * int
 (** Return the position of the mouse cursor, relative to the
@@ -336,13 +336,13 @@ val key_pressed : unit -> bool
    would not block. *)
 
 
-(** {6 Sound} *)
+(** {1 Sound} *)
 
 external sound : int -> int -> unit = "caml_gr_sound"
 (** [sound freq dur] plays a sound at frequency [freq] (in hertz)
    for a duration [dur] (in milliseconds). *)
 
-(** {6 Double buffering} *)
+(** {1 Double buffering} *)
 
 val auto_synchronize : bool -> unit
 (** By default, drawing takes place both on the window displayed
diff --git a/otherlibs/str/str.mli b/otherlibs/str/str.mli
index 256289c806..636e5812af 100644
--- a/otherlibs/str/str.mli
+++ b/otherlibs/str/str.mli
@@ -16,7 +16,7 @@
 (** Regular expressions and high-level string processing *)
 
 
-(** {6 Regular expressions} *)
+(** {1 Regular expressions} *)
 
 
 type regexp
@@ -84,7 +84,7 @@ val regexp_string_case_fold : string -> regexp
    but the regexp matches in a case-insensitive way. *)
 
 
-(** {6 String matching and searching} *)
+(** {1 String matching and searching} *)
 
 
 val string_match : regexp -> string -> int -> bool
@@ -188,7 +188,7 @@ val group_end : int -> int
    the regular expression. *)
 
 
-(** {6 Replacement} *)
+(** {1 Replacement} *)
 
 
 val global_replace : regexp -> string -> string -> string
@@ -224,7 +224,7 @@ val replace_matched : string -> string -> string
    searching function. *)
 
 
-(** {6 Splitting} *)
+(** {1 Splitting} *)
 
 
 val split : regexp -> string -> string list
@@ -270,7 +270,7 @@ val bounded_full_split : regexp -> string -> int -> split_result list
    the latter are tagged [Text]. *)
 
 
-(** {6 Extracting substrings} *)
+(** {1 Extracting substrings} *)
 
 
 val string_before : string -> int -> string
diff --git a/otherlibs/systhreads/thread.mli b/otherlibs/systhreads/thread.mli
index 9b8a126796..2eb38599a1 100644
--- a/otherlibs/systhreads/thread.mli
+++ b/otherlibs/systhreads/thread.mli
@@ -18,7 +18,7 @@
 type t
 (** The type of thread handles. *)
 
-(** {6 Thread creation and termination} *)
+(** {1 Thread creation and termination} *)
 
 val create : ('a -> 'b) -> 'a -> t
 (** [Thread.create funct arg] creates a new thread of control,
@@ -47,7 +47,7 @@ val exit : unit -> unit
 val kill : t -> unit
 (** Terminate prematurely the thread whose handle is given. *)
 
-(** {6 Suspending threads} *)
+(** {1 Suspending threads} *)
 
 val delay: float -> unit
 (** [delay d] suspends the execution of the calling thread for
@@ -102,7 +102,7 @@ val yield : unit -> unit
    telling the scheduler that now is a good time to
    switch to other threads. *)
 
-(** {6 Management of signals} *)
+(** {1 Management of signals} *)
 
 (** Signal handling follows the POSIX thread model: signals generated
   by a thread are delivered to that thread; signals generated externally
diff --git a/otherlibs/systhreads/threadUnix.mli b/otherlibs/systhreads/threadUnix.mli
index 9e8d927ee5..1fe1bcc8d1 100644
--- a/otherlibs/systhreads/threadUnix.mli
+++ b/otherlibs/systhreads/threadUnix.mli
@@ -21,7 +21,7 @@
    (block the calling thread, if required, but do not block all threads
    in the process).  *)
 
-(** {6 Process handling} *)
+(** {1 Process handling} *)
 
 val execv : string -> string array -> unit
 val execve : string -> string array -> string array -> unit
@@ -30,13 +30,13 @@ val wait : unit -> int * Unix.process_status
 val waitpid : Unix.wait_flag list -> int -> int * Unix.process_status
 val system : string -> Unix.process_status
 
-(** {6 Basic input/output} *)
+(** {1 Basic input/output} *)
 
 val read : Unix.file_descr -> bytes -> int -> int -> int
 val write : Unix.file_descr -> bytes -> int -> int -> int
 val write_substring : Unix.file_descr -> string -> int -> int -> int
 
-(** {6 Input/output with timeout} *)
+(** {1 Input/output with timeout} *)
 
 val timed_read :
       Unix.file_descr ->
@@ -55,25 +55,25 @@ val timed_write_substring :
       Unix.file_descr -> string -> int -> int -> float -> int
 (** See {!ThreadUnix.timed_write}. *)
 
-(** {6 Polling} *)
+(** {1 Polling} *)
 
 val select :
   Unix.file_descr list -> Unix.file_descr list ->
   Unix.file_descr list -> float ->
         Unix.file_descr list * Unix.file_descr list * Unix.file_descr list
 
-(** {6 Pipes and redirections} *)
+(** {1 Pipes and redirections} *)
 
 val pipe : ?cloexec:bool -> unit -> Unix.file_descr * Unix.file_descr
 val open_process_in: string -> in_channel
 val open_process_out: string -> out_channel
 val open_process: string -> in_channel * out_channel
 
-(** {6 Time} *)
+(** {1 Time} *)
 
 val sleep : int -> unit
 
-(** {6 Sockets} *)
+(** {1 Sockets} *)
 
 val socket :
   ?cloexec:bool -> Unix.socket_domain -> Unix.socket_type -> int ->
diff --git a/otherlibs/threads/thread.mli b/otherlibs/threads/thread.mli
index bf0c38047d..bd9b19e722 100644
--- a/otherlibs/threads/thread.mli
+++ b/otherlibs/threads/thread.mli
@@ -19,7 +19,7 @@ type t
 (** The type of thread handles. *)
 
 
-(** {6 Thread creation and termination} *)
+(** {1 Thread creation and termination} *)
 
 val create : ('a -> 'b) -> 'a -> t
 (** [Thread.create funct arg] creates a new thread of control,
@@ -49,7 +49,7 @@ val kill : t -> unit
 (** Terminate prematurely the thread whose handle is given.
    This functionality is available only with bytecode-level threads. *)
 
-(** {6 Suspending threads} *)
+(** {1 Suspending threads} *)
 
 val delay : float -> unit
 (** [delay d] suspends the execution of the calling thread for
@@ -112,7 +112,7 @@ val yield : unit -> unit
 
 (**/**)
 
-(** {6 Synchronization primitives}
+(** {1 Synchronization primitives}
 
    The following primitives provide the basis for implementing
    synchronization functions between threads. Their direct use is
diff --git a/otherlibs/threads/threadUnix.mli b/otherlibs/threads/threadUnix.mli
index 2b03ac9bce..bd37f710fd 100644
--- a/otherlibs/threads/threadUnix.mli
+++ b/otherlibs/threads/threadUnix.mli
@@ -21,7 +21,7 @@
    (block the calling thread, if required, but do not block all threads
    in the process).  *)
 
-(** {6 Process handling} *)
+(** {1 Process handling} *)
 
 val execv : string -> string array -> unit
 val execve : string -> string array -> string array -> unit
@@ -30,7 +30,7 @@ val wait : unit -> int * Unix.process_status
 val waitpid : Unix.wait_flag list -> int -> int * Unix.process_status
 val system : string -> Unix.process_status
 
-(** {6 Basic input/output} *)
+(** {1 Basic input/output} *)
 
 val read : Unix.file_descr -> bytes -> int -> int -> int
 val write : Unix.file_descr -> bytes -> int -> int -> int
@@ -38,7 +38,7 @@ val single_write : Unix.file_descr -> bytes -> int -> int -> int
 val write_substring : Unix.file_descr -> string -> int -> int -> int
 val single_write_substring : Unix.file_descr -> string -> int -> int -> int
 
-(** {6 Input/output with timeout} *)
+(** {1 Input/output with timeout} *)
 
 val timed_read : Unix.file_descr -> bytes -> int -> int -> float -> int
 (** See {!ThreadUnix.timed_write}. *)
@@ -53,14 +53,14 @@ val timed_write_substring :
       Unix.file_descr -> string -> int -> int -> float -> int
 (** See {!ThreadUnix.timed_write}. *)
 
-(** {6 Polling} *)
+(** {1 Polling} *)
 
 val select :
   Unix.file_descr list -> Unix.file_descr list -> Unix.file_descr list ->
     float ->
     Unix.file_descr list * Unix.file_descr list * Unix.file_descr list
 
-(** {6 Pipes and redirections} *)
+(** {1 Pipes and redirections} *)
 
 val pipe : ?cloexec:bool -> unit -> Unix.file_descr * Unix.file_descr
 val open_process_in : string -> in_channel
@@ -69,11 +69,11 @@ val open_process : string -> in_channel * out_channel
 val open_process_full :
   string -> string array -> in_channel * out_channel * in_channel
 
-(** {6 Time} *)
+(** {1 Time} *)
 
 val sleep : int -> unit
 
-(** {6 Sockets} *)
+(** {1 Sockets} *)
 
 val socket :
   ?cloexec:bool -> Unix.socket_domain -> Unix.socket_type -> int ->
diff --git a/otherlibs/unix/unix.mli b/otherlibs/unix/unix.mli
index 32ea7f13a6..bf968126a5 100644
--- a/otherlibs/unix/unix.mli
+++ b/otherlibs/unix/unix.mli
@@ -20,7 +20,7 @@
     exception whenever the underlying system call signals an error. *)
 
 
-(** {6 Error report} *)
+(** {1 Error report} *)
 
 
 type error =
@@ -116,7 +116,7 @@ val handle_unix_error : ('a -> 'b) -> 'a -> 'b
    describing the error and exits with code 2. *)
 
 
-(** {6 Access to the process environment} *)
+(** {1 Access to the process environment} *)
 
 
 val environment : unit -> string array
@@ -162,7 +162,7 @@ val putenv : string -> string -> unit
    and [value] its new associated value. *)
 
 
-(** {6 Process handling} *)
+(** {1 Process handling} *)
 
 
 type process_status =
@@ -253,7 +253,7 @@ val nice : int -> int
    On Windows: not implemented. *)
 
 
-(** {6 Basic file input/output} *)
+(** {1 Basic file input/output} *)
 
 
 type file_descr
@@ -334,7 +334,7 @@ val single_write_substring : file_descr -> string -> int -> int -> int
     a byte sequence.
     @since 4.02.0 *)
 
-(** {6 Interfacing with the standard input/output library} *)
+(** {1 Interfacing with the standard input/output library} *)
 
 
 
@@ -380,7 +380,7 @@ val descr_of_out_channel : out_channel -> file_descr
 (** Return the descriptor corresponding to an output channel. *)
 
 
-(** {6 Seeking and truncating} *)
+(** {1 Seeking and truncating} *)
 
 
 type seek_command =
@@ -406,7 +406,7 @@ val ftruncate : file_descr -> int -> unit
   On Windows: not implemented. *)
 
 
-(** {6 File status} *)
+(** {1 File status} *)
 
 
 type file_kind =
@@ -449,7 +449,7 @@ val isatty : file_descr -> bool
 (** Return [true] if the given file descriptor refers to a terminal or
    console window, [false] otherwise. *)
 
-(** {6 File operations on large files} *)
+(** {1 File operations on large files} *)
 
 module LargeFile :
   sig
@@ -543,7 +543,7 @@ val map_file :
   validation fails.
   @since 4.06.0 *)
 
-(** {6 Operations on file names} *)
+(** {1 Operations on file names} *)
 
 
 val unlink : string -> unit
@@ -569,7 +569,7 @@ val link : string -> string -> unit
    named [source]. *)
 
 
-(** {6 File permissions and ownership} *)
+(** {1 File permissions and ownership} *)
 
 
 type access_permission =
@@ -608,7 +608,7 @@ val access : string -> access_permission list -> unit
    tests for read permission instead. *)
 
 
-(** {6 Operations on file descriptors} *)
+(** {1 Operations on file descriptors} *)
 
 
 val dup : ?cloexec:bool -> file_descr -> file_descr
@@ -687,7 +687,7 @@ val clear_close_on_exec : file_descr -> unit
    See {!Unix.set_close_on_exec}.*)
 
 
-(** {6 Directories} *)
+(** {1 Directories} *)
 
 
 val mkdir : string -> file_perm -> unit
@@ -724,7 +724,7 @@ val closedir : dir_handle -> unit
 
 
 
-(** {6 Pipes and redirections} *)
+(** {1 Pipes and redirections} *)
 
 
 val pipe : ?cloexec:bool -> unit -> file_descr * file_descr
@@ -739,7 +739,7 @@ val mkfifo : string -> file_perm -> unit
    On Windows: not implemented. *)
 
 
-(** {6 High-level process and redirection management} *)
+(** {1 High-level process and redirection management} *)
 
 
 val create_process :
@@ -816,7 +816,7 @@ val close_process_full :
    and return its termination status. *)
 
 
-(** {6 Symbolic links} *)
+(** {1 Symbolic links} *)
 
 
 val symlink : ?to_dir:bool -> string -> string -> unit
@@ -862,7 +862,7 @@ val readlink : string -> string
 (** Read the contents of a symbolic link. *)
 
 
-(** {6 Polling} *)
+(** {1 Polling} *)
 
 
 val select :
@@ -880,7 +880,7 @@ val select :
    component). *)
 
 
-(** {6 Locking} *)
+(** {1 Locking} *)
 
 type lock_command =
     F_ULOCK       (** Unlock a region *)
@@ -925,7 +925,7 @@ val lockf : file_descr -> lock_command -> int -> unit
 *)
 
 
-(** {6 Signals}
+(** {1 Signals}
    Note: installation of signal handlers is performed via
    the functions {!Sys.signal} and {!Sys.set_signal}.
 *)
@@ -970,7 +970,7 @@ val pause : unit -> unit
   On Windows: not implemented (no inter-process signals on Windows). *)
 
 
-(** {6 Time functions} *)
+(** {1 Time functions} *)
 
 
 type process_times =
@@ -1086,7 +1086,7 @@ val setitimer :
    On Windows: not implemented. *)
 
 
-(** {6 User id, group id} *)
+(** {1 User id, group id} *)
 
 
 val getuid : unit -> int
@@ -1177,7 +1177,7 @@ val getgrgid : int -> group_entry
    On Windows, always raise [Not_found]. *)
 
 
-(** {6 Internet addresses} *)
+(** {1 Internet addresses} *)
 
 
 type inet_addr
@@ -1211,7 +1211,7 @@ val inet6_addr_loopback : inet_addr
 (** A special IPv6 address representing the host machine ([::1]). *)
 
 
-(** {6 Sockets} *)
+(** {1 Sockets} *)
 
 
 type socket_domain =
@@ -1329,7 +1329,7 @@ val sendto_substring :
     @since 4.02.0 *)
 
 
-(** {6 Socket options} *)
+(** {1 Socket options} *)
 
 
 type socket_bool_option =
@@ -1409,7 +1409,7 @@ val getsockopt_error : file_descr -> error option
     and clear it. *)
 
 
-(** {6 High-level network connection functions} *)
+(** {1 High-level network connection functions} *)
 
 
 val open_connection : sockaddr -> in_channel * out_channel
@@ -1435,7 +1435,7 @@ val establish_server : (in_channel -> out_channel -> unit) -> sockaddr -> unit
    On Windows, it is not implemented.  Use threads. *)
 
 
-(** {6 Host and protocol databases} *)
+(** {1 Host and protocol databases} *)
 
 
 type host_entry =
@@ -1550,7 +1550,7 @@ val getnameinfo : sockaddr -> getnameinfo_option list -> name_info
     @raise Not_found if an error occurs. *)
 
 
-(** {6 Terminal interface} *)
+(** {1 Terminal interface} *)
 
 
 (** The following functions implement the POSIX standard terminal
diff --git a/otherlibs/unix/unixLabels.mli b/otherlibs/unix/unixLabels.mli
index b12b3133ce..08b388b3bd 100644
--- a/otherlibs/unix/unixLabels.mli
+++ b/otherlibs/unix/unixLabels.mli
@@ -18,7 +18,7 @@
    add [module Unix = UnixLabels] in your implementation.
 *)
 
-(** {6 Error report} *)
+(** {1 Error report} *)
 
 
 type error = Unix.error =
@@ -114,7 +114,7 @@ val handle_unix_error : ('a -> 'b) -> 'a -> 'b
    describing the error and exits with code 2. *)
 
 
-(** {6 Access to the process environment} *)
+(** {1 Access to the process environment} *)
 
 
 val environment : unit -> string array
@@ -147,7 +147,7 @@ val putenv : string -> string -> unit
    and [value] its new associated value. *)
 
 
-(** {6 Process handling} *)
+(** {1 Process handling} *)
 
 
 type process_status = Unix.process_status =
@@ -227,7 +227,7 @@ val nice : int -> int
    lower priorities.) Return the new nice value. *)
 
 
-(** {6 Basic file input/output} *)
+(** {1 Basic file input/output} *)
 
 
 type file_descr = Unix.file_descr
@@ -307,7 +307,7 @@ val single_write_substring :
     a byte sequence.
     @since 4.02.0 *)
 
-(** {6 Interfacing with the standard input/output library} *)
+(** {1 Interfacing with the standard input/output library} *)
 
 
 
@@ -328,7 +328,7 @@ val descr_of_out_channel : out_channel -> file_descr
 (** Return the descriptor corresponding to an output channel. *)
 
 
-(** {6 Seeking and truncating} *)
+(** {1 Seeking and truncating} *)
 
 
 type seek_command = Unix.seek_command =
@@ -350,7 +350,7 @@ val ftruncate : file_descr -> len:int -> unit
    to the given size. *)
 
 
-(** {6 File status} *)
+(** {1 File status} *)
 
 
 type file_kind = Unix.file_kind =
@@ -393,7 +393,7 @@ val isatty : file_descr -> bool
 (** Return [true] if the given file descriptor refers to a terminal or
    console window, [false] otherwise. *)
 
-(** {6 File operations on large files} *)
+(** {1 File operations on large files} *)
 
 module LargeFile :
   sig
@@ -430,7 +430,7 @@ module LargeFile :
   whose sizes are greater than [max_int]. *)
 
 
-(** {6 Mapping files into memory} *)
+(** {1 Mapping files into memory} *)
 
 val map_file :
   file_descr -> ?pos:int64 -> kind:('a, 'b) CamlinternalBigarray.kind ->
@@ -483,7 +483,7 @@ val map_file :
   validation fails.
   @since 4.06.0 *)
 
-(** {6 Operations on file names} *)
+(** {1 Operations on file names} *)
 
 
 val unlink : string -> unit
@@ -497,7 +497,7 @@ val link : src:string -> dst:string -> unit
    named [source]. *)
 
 
-(** {6 File permissions and ownership} *)
+(** {1 File permissions and ownership} *)
 
 
 type access_permission = Unix.access_permission =
@@ -529,7 +529,7 @@ val access : string -> perm:access_permission list -> unit
    file. Raise [Unix_error] otherwise. *)
 
 
-(** {6 Operations on file descriptors} *)
+(** {1 Operations on file descriptors} *)
 
 
 val dup : ?cloexec:bool -> file_descr -> file_descr
@@ -563,7 +563,7 @@ val clear_close_on_exec : file_descr -> unit
    See {!UnixLabels.set_close_on_exec}.*)
 
 
-(** {6 Directories} *)
+(** {1 Directories} *)
 
 
 val mkdir : string -> perm:file_perm -> unit
@@ -599,7 +599,7 @@ val closedir : dir_handle -> unit
 
 
 
-(** {6 Pipes and redirections} *)
+(** {1 Pipes and redirections} *)
 
 
 val pipe : ?cloexec:bool -> unit -> file_descr * file_descr
@@ -611,7 +611,7 @@ val mkfifo : string -> perm:file_perm -> unit
 (** Create a named pipe with the given permissions. *)
 
 
-(** {6 High-level process and redirection management} *)
+(** {1 High-level process and redirection management} *)
 
 
 val create_process :
@@ -688,7 +688,7 @@ val close_process_full :
    and return its termination status. *)
 
 
-(** {6 Symbolic links} *)
+(** {1 Symbolic links} *)
 
 
 val symlink : ?to_dir:bool -> src:string -> dst:string -> unit
@@ -706,7 +706,7 @@ val readlink : string -> string
 (** Read the contents of a link. *)
 
 
-(** {6 Polling} *)
+(** {1 Polling} *)
 
 
 val select :
@@ -723,7 +723,7 @@ val select :
    and over which an exceptional condition is pending (third
    component). *)
 
-(** {6 Locking} *)
+(** {1 Locking} *)
 
 
 type lock_command = Unix.lock_command =
@@ -762,7 +762,7 @@ val lockf : file_descr -> mode:lock_command -> len:int -> unit
    It returns immediately if successful, or fails otherwise. *)
 
 
-(** {6 Signals}
+(** {1 Signals}
    Note: installation of signal handlers is performed via
    the functions {!Sys.signal} and {!Sys.set_signal}.
 *)
@@ -798,7 +798,7 @@ val pause : unit -> unit
 (** Wait until a non-ignored, non-blocked signal is delivered. *)
 
 
-(** {6 Time functions} *)
+(** {1 Time functions} *)
 
 
 type process_times = Unix.process_times =
@@ -897,7 +897,7 @@ val setitimer :
    after its next expiration. *)
 
 
-(** {6 User id, group id} *)
+(** {1 User id, group id} *)
 
 
 val getuid : unit -> int
@@ -971,7 +971,7 @@ val getgrgid : int -> group_entry
    [Not_found]. *)
 
 
-(** {6 Internet addresses} *)
+(** {1 Internet addresses} *)
 
 
 type inet_addr = Unix.inet_addr
@@ -1005,7 +1005,7 @@ val inet6_addr_loopback : inet_addr
 (** A special IPv6 address representing the host machine ([::1]). *)
 
 
-(** {6 Sockets} *)
+(** {1 Sockets} *)
 
 
 type socket_domain = Unix.socket_domain =
@@ -1122,7 +1122,7 @@ val sendto_substring :
 
 
 
-(** {6 Socket options} *)
+(** {1 Socket options} *)
 
 
 type socket_bool_option =
@@ -1200,7 +1200,7 @@ val getsockopt_error : file_descr -> error option
 (** Return the error condition associated with the given socket,
     and clear it. *)
 
-(** {6 High-level network connection functions} *)
+(** {1 High-level network connection functions} *)
 
 
 val open_connection : sockaddr -> in_channel * out_channel
@@ -1223,7 +1223,7 @@ val establish_server :
    never returns normally. *)
 
 
-(** {6 Host and protocol databases} *)
+(** {1 Host and protocol databases} *)
 
 
 type host_entry = Unix.host_entry =
@@ -1338,7 +1338,7 @@ val getnameinfo : sockaddr -> getnameinfo_option list -> name_info
     Raise [Not_found] if an error occurs. *)
 
 
-(** {6 Terminal interface} *)
+(** {1 Terminal interface} *)
 
 
 (** The following functions implement the POSIX standard terminal
diff --git a/parsing/ast_helper.mli b/parsing/ast_helper.mli
index ce9ef0ce4b..efc1dfcad5 100644
--- a/parsing/ast_helper.mli
+++ b/parsing/ast_helper.mli
@@ -24,7 +24,7 @@ type str = string loc
 type loc = Location.t
 type attrs = attribute list
 
-(** {2 Default locations} *)
+(** {1 Default locations} *)
 
 val default_loc: loc ref
     (** Default value for all optional location arguments. *)
@@ -33,7 +33,7 @@ val with_default_loc: loc -> (unit -> 'a) -> 'a
     (** Set the [default_loc] within the scope of the execution
         of the provided function. *)
 
-(** {2 Constants} *)
+(** {1 Constants} *)
 
 module Const : sig
   val char : char -> constant
@@ -46,7 +46,7 @@ module Const : sig
   val float : ?suffix:char -> string -> constant
 end
 
-(** {2 Core language} *)
+(** {1 Core language} *)
 
 (** Type expressions *)
 module Typ :
@@ -216,7 +216,7 @@ module Te:
       str -> lid -> extension_constructor
   end
 
-(** {2 Module language} *)
+(** {1 Module language} *)
 
 (** Module type expressions *)
 module Mty:
@@ -339,7 +339,7 @@ module Vb:
   end
 
 
-(** {2 Class language} *)
+(** {1 Class language} *)
 
 (** Class type expressions *)
 module Cty:
diff --git a/parsing/ast_iterator.mli b/parsing/ast_iterator.mli
index 28df9af137..bd8e081687 100755
--- a/parsing/ast_iterator.mli
+++ b/parsing/ast_iterator.mli
@@ -19,7 +19,7 @@
 
 open Parsetree
 
-(** {2 A generic Parsetree iterator} *)
+(** {1 A generic Parsetree iterator} *)
 
 type iterator = {
   attribute: iterator -> attribute -> unit;
diff --git a/parsing/ast_mapper.mli b/parsing/ast_mapper.mli
index 8889d2f3b2..85b59e9c37 100644
--- a/parsing/ast_mapper.mli
+++ b/parsing/ast_mapper.mli
@@ -50,7 +50,7 @@ let () =
 
 open Parsetree
 
-(** {2 A generic Parsetree mapper} *)
+(** {1 A generic Parsetree mapper} *)
 
 type mapper = {
   attribute: mapper -> attribute -> attribute;
@@ -106,7 +106,7 @@ type mapper = {
 val default_mapper: mapper
 (** A default mapper, which implements a "deep identity" mapping. *)
 
-(** {2 Apply mappers to compilation units} *)
+(** {1 Apply mappers to compilation units} *)
 
 val tool_name: unit -> string
 (** Can be used within a ppx preprocessor to know which tool is
@@ -131,7 +131,7 @@ val run_main: (string list -> mapper) -> unit
     function implements proper error reporting for uncaught
     exceptions. *)
 
-(** {2 Registration API} *)
+(** {1 Registration API} *)
 
 val register_function: (string -> (string list -> mapper) -> unit) ref
 
@@ -153,7 +153,7 @@ val register: string -> (string list -> mapper) -> unit
     the ppx driver.  *)
 
 
-(** {2 Convenience functions to write mappers} *)
+(** {1 Convenience functions to write mappers} *)
 
 val map_opt: ('a -> 'b) -> 'a option -> 'b option
 
@@ -167,7 +167,7 @@ val attribute_of_warning: Location.t -> string -> attribute
     inserted in a generated Parsetree.  The compiler will be
     responsible for reporting the warning. *)
 
-(** {2 Helper functions to call external mappers} *)
+(** {1 Helper functions to call external mappers} *)
 
 val add_ppx_context_str:
     tool_name:string -> Parsetree.structure -> Parsetree.structure
@@ -190,7 +190,7 @@ val drop_ppx_context_sig:
     restore:bool -> Parsetree.signature -> Parsetree.signature
 (** Same as [drop_ppx_context_str], but for signatures. *)
 
-(** {2 Cookies} *)
+(** {1 Cookies} *)
 
 (** Cookies are used to pass information from a ppx processor to
     a further invocation of itself, when called from the OCaml
diff --git a/parsing/docstrings.mli b/parsing/docstrings.mli
index 500ecbf083..892a80e278 100644
--- a/parsing/docstrings.mli
+++ b/parsing/docstrings.mli
@@ -21,7 +21,7 @@ val init : unit -> unit
 (** Emit warnings for unattached and ambiguous docstrings *)
 val warn_bad_docstrings : unit -> unit
 
-(** {3 Docstrings} *)
+(** {2 Docstrings} *)
 
 (** Documentation comments *)
 type docstring
@@ -38,7 +38,7 @@ val docstring_body : docstring -> string
 (** Get the location of a docstring *)
 val docstring_loc : docstring -> Location.t
 
-(** {3 Set functions}
+(** {2 Set functions}
 
    These functions are used by the lexer to associate docstrings to
    the locations of tokens. *)
@@ -58,7 +58,7 @@ val set_pre_extra_docstrings : Lexing.position -> docstring list -> unit
 (** Docstrings immediately preceding the token which follows this one *)
 val set_post_extra_docstrings : Lexing.position -> docstring list -> unit
 
-(** {3 Items}
+(** {2 Items}
 
     The {!docs} type represents documentation attached to an item. *)
 
@@ -93,7 +93,7 @@ val mark_symbol_docs : unit -> unit
     two positions (for ambiguity warnings) *)
 val mark_rhs_docs : int -> int -> unit
 
-(** {3 Fields and constructors}
+(** {2 Fields and constructors}
 
     The {!info} type represents documentation attached to a field or
     constructor. *)
@@ -114,7 +114,7 @@ val symbol_info : unit -> info
 (** Fetch the field info following the symbol at a given position. *)
 val rhs_info : int -> info
 
-(** {3 Unattached comments}
+(** {2 Unattached comments}
 
     The {!text} type represents documentation which is not attached to
     anything. *)
@@ -137,7 +137,7 @@ val symbol_text_lazy : unit -> text Lazy.t
 val rhs_text : int -> text
 val rhs_text_lazy : int -> text Lazy.t
 
-(** {3 Extra text}
+(** {2 Extra text}
 
     There may be additional text attached to the delimiters of a block
     (e.g. [struct] and [end]). This is fetched by the following
diff --git a/parsing/parsetree.mli b/parsing/parsetree.mli
index 13fd8de611..852a526b10 100644
--- a/parsing/parsetree.mli
+++ b/parsing/parsetree.mli
@@ -37,7 +37,7 @@ type constant =
      Suffixes are rejected by the typechecker.
   *)
 
-(** {2 Extension points} *)
+(** {1 Extension points} *)
 
 type attribute = string loc * payload
        (* [@id ARG]
@@ -62,7 +62,7 @@ and payload =
   | PTyp of core_type  (* : T *)
   | PPat of pattern * expression option  (* ? P  or  ? P when E *)
 
-(** {2 Core language} *)
+(** {1 Core language} *)
 
 (* Type expressions *)
 
@@ -481,7 +481,7 @@ and extension_constructor_kind =
          | C = D
        *)
 
-(** {2 Class language} *)
+(** {1 Class language} *)
 
 (* Type expressions for the class language *)
 
@@ -647,7 +647,7 @@ and class_field_kind =
 
 and class_declaration = class_expr class_infos
 
-(** {2 Module language} *)
+(** {1 Module language} *)
 
 (* Type expressions for the module language *)
 
@@ -858,7 +858,7 @@ and module_binding =
     }
 (* X = ME *)
 
-(** {2 Toplevel} *)
+(** {1 Toplevel} *)
 
 (* Toplevel phrases *)
 
diff --git a/stdlib/array.mli b/stdlib/array.mli
index f2cdea34fe..bfad5317ca 100644
--- a/stdlib/array.mli
+++ b/stdlib/array.mli
@@ -134,7 +134,7 @@ val of_list : 'a list -> 'a array
    of [l]. *)
 
 
-(** {6 Iterators} *)
+(** {1 Iterators} *)
 
 
 val iter : ('a -> unit) -> 'a array -> unit
@@ -168,7 +168,7 @@ val fold_right : ('b -> 'a -> 'a) -> 'b array -> 'a -> 'a
    where [n] is the length of the array [a]. *)
 
 
-(** {6 Iterators on two arrays} *)
+(** {1 Iterators on two arrays} *)
 
 
 val iter2 : ('a -> 'b -> unit) -> 'a array -> 'b array -> unit
@@ -185,7 +185,7 @@ val map2 : ('a -> 'b -> 'c) -> 'a array -> 'b array -> 'c array
    @since 4.03.0 *)
 
 
-(** {6 Array scanning} *)
+(** {1 Array scanning} *)
 
 
 val for_all : ('a -> bool) -> 'a array -> bool
@@ -211,7 +211,7 @@ val memq : 'a -> 'a array -> bool
    @since 4.03.0 *)
 
 
-(** {6 Sorting} *)
+(** {1 Sorting} *)
 
 
 val sort : ('a -> 'a -> int) -> 'a array -> unit
@@ -257,7 +257,7 @@ val fast_sort : ('a -> 'a -> int) -> 'a array -> unit
 
 
 (**/**)
-(** {6 Undocumented functions} *)
+(** {1 Undocumented functions} *)
 
 (* The following is for system use only. Do not call directly. *)
 
diff --git a/stdlib/arrayLabels.mli b/stdlib/arrayLabels.mli
index 7abab477d0..0b9fe0c9bc 100644
--- a/stdlib/arrayLabels.mli
+++ b/stdlib/arrayLabels.mli
@@ -211,7 +211,7 @@ val make_float: int -> float array
     {!Array.create_float}. *)
 
 
-(** {6 Sorting} *)
+(** {1 Sorting} *)
 
 
 val sort : cmp:('a -> 'a -> int) -> 'a array -> unit
@@ -258,7 +258,7 @@ val fast_sort : cmp:('a -> 'a -> int) -> 'a array -> unit
 
 (**/**)
 
-(** {6 Undocumented functions} *)
+(** {1 Undocumented functions} *)
 
 (* The following is for system use only. Do not call directly. *)
 
diff --git a/stdlib/bytes.mli b/stdlib/bytes.mli
index dc53078768..8c6b585f9a 100644
--- a/stdlib/bytes.mli
+++ b/stdlib/bytes.mli
@@ -261,7 +261,7 @@ val rcontains_from : bytes -> int -> char -> bool
 
 val uppercase : bytes -> bytes
   [@@ocaml.deprecated "Use Bytes.uppercase_ascii instead."]
-(** Return a copy of the argument, with all lowercase letters
+(* Return a copy of the argument, with all lowercase letters
    translated to uppercase, including accented letters of the ISO
    Latin-1 (8859-1) character set.
    @deprecated Functions operating on Latin-1 character set are deprecated. *)
@@ -318,7 +318,7 @@ val equal: t -> t -> bool
 (** The equality function for byte sequences.
     @since 4.03.0 *)
 
-(** {4 Unsafe conversions (for advanced users)}
+(** {3 Unsafe conversions (for advanced users)}
 
     This section describes unsafe, low-level conversion functions
     between [bytes] and [string]. They do not copy the internal data;
diff --git a/stdlib/camlinternalOO.mli b/stdlib/camlinternalOO.mli
index 7c7e0013ba..b6ffc70d7f 100644
--- a/stdlib/camlinternalOO.mli
+++ b/stdlib/camlinternalOO.mli
@@ -17,7 +17,7 @@
     All functions in this module are for system use only, not for the
     casual user. *)
 
-(** {6 Classes} *)
+(** {1 Classes} *)
 
 type tag
 type label
@@ -57,7 +57,7 @@ val dummy_class :
     string * int * int ->
     (t * (table -> Obj.t -> t) * (Obj.t -> t) * Obj.t)
 
-(** {6 Objects} *)
+(** {1 Objects} *)
 
 val copy : (< .. > as 'a) -> 'a
 val create_object : table -> obj
@@ -71,12 +71,12 @@ external sendself : obj -> label -> t = "%sendself"
 external get_public_method : obj -> tag -> closure
     = "caml_get_public_method" [@@noalloc]
 
-(** {6 Table cache} *)
+(** {1 Table cache} *)
 
 type tables
 val lookup_tables : tables -> closure array -> tables
 
-(** {6 Builtins to reduce code size} *)
+(** {1 Builtins to reduce code size} *)
 
 (*
 val get_const : t -> closure
@@ -132,7 +132,7 @@ type impl =
   | SendMeth
   | Closure of closure
 
-(** {6 Parameters} *)
+(** {1 Parameters} *)
 
 (* currently disabled *)
 type params =
@@ -144,7 +144,7 @@ type params =
 
 val params : params
 
-(** {6 Statistics} *)
+(** {1 Statistics} *)
 
 type stats =
   { classes : int;
diff --git a/stdlib/format.mli b/stdlib/format.mli
index ec14ddefda..3f9c7f299a 100644
--- a/stdlib/format.mli
+++ b/stdlib/format.mli
@@ -41,7 +41,7 @@
 
 *)
 
-(** {6 Introduction}
+(** {1 Introduction}
    For a gentle introduction to the basics of pretty-printing using
    [Format], read
    {{:http://caml.inria.fr/resources/doc/guides/format.en.html}
@@ -111,7 +111,7 @@ type formatter
 (** Abstract data corresponding to a pretty-printer (also called a
     formatter) and all its machinery. See also {!section:formatter}. *)
 
-(** {6:boxes Pretty-printing boxes} *)
+(** {1:boxes Pretty-printing boxes} *)
 
 (** The pretty-printing engine uses the concepts of pretty-printing box and
   break hint to drive indentation and line splitting behavior of the
@@ -211,7 +211,7 @@ val open_hovbox : int -> unit
   current indentation.
 *)
 
-(** {6 Formatting functions} *)
+(** {1 Formatting functions} *)
 
 val pp_print_string : formatter -> string -> unit
 val print_string : string -> unit
@@ -239,7 +239,7 @@ val pp_print_bool : formatter -> bool -> unit
 val print_bool : bool -> unit
 (** Print a boolean in the current pretty-printing box. *)
 
-(** {6:breaks Break hints} *)
+(** {1:breaks Break hints} *)
 
 (** A 'break hint' tells the pretty-printer to output some space or split the
   line whichever way is more appropriate to the current pretty-printing box
@@ -307,7 +307,7 @@ val print_if_newline : unit -> unit
   command.
 *)
 
-(** {6 Pretty-printing termination} *)
+(** {1 Pretty-printing termination} *)
 
 val pp_print_flush : formatter -> unit -> unit
 val print_flush : unit -> unit
@@ -349,7 +349,7 @@ val print_newline : unit -> unit
   box.
 *)
 
-(** {6 Margin} *)
+(** {1 Margin} *)
 
 val pp_set_margin : formatter -> int -> unit
 val set_margin : int -> unit
@@ -369,7 +369,7 @@ val pp_get_margin : formatter -> unit -> int
 val get_margin : unit -> int
 (** Returns the position of the right margin. *)
 
-(** {6 Maximum indentation limit} *)
+(** {1 Maximum indentation limit} *)
 
 val pp_set_max_indent : formatter -> int -> unit
 val set_max_indent : int -> unit
@@ -390,7 +390,7 @@ val pp_get_max_indent : formatter -> unit -> int
 val get_max_indent : unit -> int
 (** Return the maximum indentation limit (in characters). *)
 
-(** {6 Maximum formatting depth} *)
+(** {1 Maximum formatting depth} *)
 
 (** The maximum formatting depth is the maximum number of pretty-printing
   boxes simultaneously open.
@@ -422,7 +422,7 @@ val over_max_boxes : unit -> bool
   been opened.
 *)
 
-(** {6 Tabulation boxes} *)
+(** {1 Tabulation boxes} *)
 
 (**
 
@@ -488,7 +488,7 @@ val print_tbreak : int -> int -> unit
   the current indentation.
 *)
 
-(** {6 Ellipsis} *)
+(** {1 Ellipsis} *)
 
 val pp_set_ellipsis_text : formatter -> string -> unit
 val set_ellipsis_text : string -> unit
@@ -500,7 +500,7 @@ val pp_get_ellipsis_text : formatter -> unit -> string
 val get_ellipsis_text : unit -> string
 (** Return the text of the ellipsis. *)
 
-(** {6:tags Semantic tags} *)
+(** {1:tags Semantic tags} *)
 
 type tag = string
 
@@ -614,7 +614,7 @@ val pp_get_mark_tags : formatter -> unit -> bool
 val get_mark_tags : unit -> bool
 (** Return the current status of tag-marking operations. *)
 
-(** {6 Redirecting the standard formatter output} *)
+(** {1 Redirecting the standard formatter output} *)
 val pp_set_formatter_out_channel :
   formatter -> Pervasives.out_channel -> unit
 val set_formatter_out_channel : Pervasives.out_channel -> unit
@@ -650,7 +650,7 @@ val get_formatter_output_functions :
   unit -> (string -> int -> int -> unit) * (unit -> unit)
 (** Return the current output functions of the standard pretty-printer. *)
 
-(** {6:meaning Redefining formatter output} *)
+(** {1:meaning Redefining formatter output} *)
 
 (** The [Format] module is versatile enough to let you completely redefine
   the meaning of pretty-printing output: you may provide your own functions
@@ -658,7 +658,7 @@ val get_formatter_output_functions :
   all the characters that have to be printed!
 *)
 
-(** {7 Redefining output functions} *)
+(** {2 Redefining output functions} *)
 
 type formatter_out_functions = {
   out_string : string -> int -> int -> unit;
@@ -719,7 +719,7 @@ val get_formatter_out_functions : unit -> formatter_out_functions
   @since 4.01.0
 *)
 
-(** {6:tagsmeaning Redefining semantic tag operations} *)
+(** {1:tagsmeaning Redefining semantic tag operations} *)
 
 type formatter_tag_functions = {
   mark_open_tag : tag -> string;
@@ -761,7 +761,7 @@ val get_formatter_tag_functions : unit -> formatter_tag_functions
 (** Return the current semantic tag operation functions of the standard
   pretty-printer. *)
 
-(** {6:formatter Defining formatters}
+(** {1:formatter Defining formatters}
 
   Defining new formatters permits unrelated output of material in
   parallel on several output devices.
@@ -842,7 +842,7 @@ val formatter_of_out_functions :
   @since 4.06.0
 *)
 
-(** {7:symbolic Symbolic pretty-printing} *)
+(** {2:symbolic Symbolic pretty-printing} *)
 
 (**
   Symbolic pretty-printing is pretty-printing using a symbolic formatter,
@@ -927,7 +927,7 @@ val formatter_of_symbolic_output_buffer : symbolic_output_buffer -> formatter
   @since 4.06.0
 *)
 
-(** {6 Convenience formatting functions.} *)
+(** {1 Convenience formatting functions.} *)
 
 val pp_print_list:
   ?pp_sep:(formatter -> unit -> unit) ->
@@ -947,7 +947,7 @@ val pp_print_text : formatter -> string -> unit
   @since 4.02.0
 *)
 
-(** {6:fpp Formatted pretty-printing} *)
+(** {1:fpp Formatted pretty-printing} *)
 
 (**
   Module [Format] provides a complete set of [printf] like functions for
@@ -1101,7 +1101,7 @@ val kasprintf : (string -> 'a) -> ('b, formatter, unit, 'a) format4 -> 'b
   @since 4.03
 *)
 
-(** {6 Deprecated} *)
+(** {1 Deprecated} *)
 
 val bprintf : Buffer.t -> ('a, formatter, unit) format -> 'a
   [@@ocaml.deprecated]
diff --git a/stdlib/hashtbl.mli b/stdlib/hashtbl.mli
index d3c0ef3e35..6449c055d8 100644
--- a/stdlib/hashtbl.mli
+++ b/stdlib/hashtbl.mli
@@ -19,7 +19,7 @@
 *)
 
 
-(** {6 Generic interface} *)
+(** {1 Generic interface} *)
 
 
 type ('a, 'b) t
@@ -216,7 +216,7 @@ val stats : ('a, 'b) t -> statistics
    buckets by size.
    @since 4.00.0 *)
 
-(** {6 Functorial interface} *)
+(** {1 Functorial interface} *)
 
 (** The functorial interface allows the use of specific comparison
     and hash functions, either for performance/security concerns,
@@ -371,7 +371,7 @@ module MakeSeeded (H : SeededHashedType) : SeededS with type key = H.t
     @since 4.00.0 *)
 
 
-(** {6 The polymorphic hash functions} *)
+(** {1 The polymorphic hash functions} *)
 
 
 val hash : 'a -> int
diff --git a/stdlib/int32.mli b/stdlib/int32.mli
index 745cc35828..199d86f29b 100644
--- a/stdlib/int32.mli
+++ b/stdlib/int32.mli
@@ -182,7 +182,7 @@ val equal: t -> t -> bool
 
 (**/**)
 
-(** {6 Deprecated functions} *)
+(** {1 Deprecated functions} *)
 
 external format : string -> int32 -> string = "caml_int32_format"
 (** Do not use this deprecated function.  Instead,
diff --git a/stdlib/int64.mli b/stdlib/int64.mli
index 97a407072c..96f48a6040 100644
--- a/stdlib/int64.mli
+++ b/stdlib/int64.mli
@@ -203,7 +203,7 @@ val equal: t -> t -> bool
 
 (**/**)
 
-(** {6 Deprecated functions} *)
+(** {1 Deprecated functions} *)
 
 external format : string -> int64 -> string = "caml_int64_format"
 (** Do not use this deprecated function.  Instead,
diff --git a/stdlib/lexing.mli b/stdlib/lexing.mli
index 31f15ce8f0..397d20cbb1 100644
--- a/stdlib/lexing.mli
+++ b/stdlib/lexing.mli
@@ -15,7 +15,7 @@
 
 (** The run-time library for lexers generated by [ocamllex]. *)
 
-(** {6 Positions} *)
+(** {1 Positions} *)
 
 type position = {
   pos_fname : string;
@@ -43,7 +43,7 @@ val dummy_pos : position
  *)
 
 
-(** {6 Lexer buffers} *)
+(** {1 Lexer buffers} *)
 
 
 type lexbuf =
@@ -95,7 +95,7 @@ val from_function : (bytes -> int -> int) -> lexbuf
    provided. A return value of 0 means end of input. *)
 
 
-(** {6 Functions for lexer semantic actions} *)
+(** {1 Functions for lexer semantic actions} *)
 
 
 (** The following functions can be called from the semantic actions
@@ -140,7 +140,7 @@ val new_line : lexbuf -> unit
     @since 3.11.0
 *)
 
-(** {6 Miscellaneous functions} *)
+(** {1 Miscellaneous functions} *)
 
 val flush_input : lexbuf -> unit
 (** Discard the contents of the buffer and reset the current
@@ -149,7 +149,7 @@ val flush_input : lexbuf -> unit
 
 (**/**)
 
-(** {6  } *)
+(** {1  } *)
 
 (** The following definitions are used by the generated scanners only.
    They are not intended to be used directly by user programs. *)
diff --git a/stdlib/list.mli b/stdlib/list.mli
index ab8e793577..cdcd23cdf6 100644
--- a/stdlib/list.mli
+++ b/stdlib/list.mli
@@ -99,7 +99,7 @@ val flatten : 'a list list -> 'a list
 (** An alias for [concat]. *)
 
 
-(** {6 Iterators} *)
+(** {1 Iterators} *)
 
 
 val iter : ('a -> unit) -> 'a list -> unit
@@ -140,7 +140,7 @@ val fold_right : ('a -> 'b -> 'b) -> 'a list -> 'b -> 'b
    [f a1 (f a2 (... (f an b) ...))].  Not tail-recursive. *)
 
 
-(** {6 Iterators on two lists} *)
+(** {1 Iterators on two lists} *)
 
 
 val iter2 : ('a -> 'b -> unit) -> 'a list -> 'b list -> unit
@@ -173,7 +173,7 @@ val fold_right2 : ('a -> 'b -> 'c -> 'c) -> 'a list -> 'b list -> 'c -> 'c
    to have different lengths.  Not tail-recursive. *)
 
 
-(** {6 List scanning} *)
+(** {1 List scanning} *)
 
 
 val for_all : ('a -> bool) -> 'a list -> bool
@@ -205,7 +205,7 @@ val memq : 'a -> 'a list -> bool
    equality to compare list elements. *)
 
 
-(** {6 List searching} *)
+(** {1 List searching} *)
 
 
 val find : ('a -> bool) -> 'a list -> 'a
@@ -236,7 +236,7 @@ val partition : ('a -> bool) -> 'a list -> 'a list * 'a list
    The order of the elements in the input list is preserved. *)
 
 
-(** {6 Association lists} *)
+(** {1 Association lists} *)
 
 
 val assoc : 'a -> ('a * 'b) list -> 'b
@@ -283,7 +283,7 @@ val remove_assq : 'a -> ('a * 'b) list -> ('a * 'b) list
    of structural equality to compare keys.  Not tail-recursive. *)
 
 
-(** {6 Lists of pairs} *)
+(** {1 Lists of pairs} *)
 
 
 val split : ('a * 'b) list -> 'a list * 'b list
@@ -300,7 +300,7 @@ val combine : 'a list -> 'b list -> ('a * 'b) list
    have different lengths.  Not tail-recursive. *)
 
 
-(** {6 Sorting} *)
+(** {1 Sorting} *)
 
 
 val sort : ('a -> 'a -> int) -> 'a list -> 'a list
diff --git a/stdlib/listLabels.mli b/stdlib/listLabels.mli
index 82c301fdbb..d5d9cd400e 100644
--- a/stdlib/listLabels.mli
+++ b/stdlib/listLabels.mli
@@ -101,7 +101,7 @@ val flatten : 'a list list -> 'a list
    (length of the argument + length of the longest sub-list). *)
 
 
-(** {6 Iterators} *)
+(** {1 Iterators} *)
 
 
 val iter : f:('a -> unit) -> 'a list -> unit
@@ -142,7 +142,7 @@ val fold_right : f:('a -> 'b -> 'b) -> 'a list -> init:'b -> 'b
    [f a1 (f a2 (... (f an b) ...))].  Not tail-recursive. *)
 
 
-(** {6 Iterators on two lists} *)
+(** {1 Iterators on two lists} *)
 
 
 val iter2 : f:('a -> 'b -> unit) -> 'a list -> 'b list -> unit
@@ -177,7 +177,7 @@ val fold_right2 :
    to have different lengths.  Not tail-recursive. *)
 
 
-(** {6 List scanning} *)
+(** {1 List scanning} *)
 
 
 val for_all : f:('a -> bool) -> 'a list -> bool
@@ -209,7 +209,7 @@ val memq : 'a -> set:'a list -> bool
    equality to compare list elements. *)
 
 
-(** {6 List searching} *)
+(** {1 List searching} *)
 
 
 val find : f:('a -> bool) -> 'a list -> 'a
@@ -241,7 +241,7 @@ val partition : f:('a -> bool) -> 'a list -> 'a list * 'a list
    The order of the elements in the input list is preserved. *)
 
 
-(** {6 Association lists} *)
+(** {1 Association lists} *)
 
 
 val assoc : 'a -> ('a * 'b) list -> 'b
@@ -289,7 +289,7 @@ val remove_assq : 'a -> ('a * 'b) list -> ('a * 'b) list
    of structural equality to compare keys.  Not tail-recursive. *)
 
 
-(** {6 Lists of pairs} *)
+(** {1 Lists of pairs} *)
 
 
 val split : ('a * 'b) list -> 'a list * 'b list
@@ -306,7 +306,7 @@ val combine : 'a list -> 'b list -> ('a * 'b) list
    have different lengths.  Not tail-recursive. *)
 
 
-(** {6 Sorting} *)
+(** {1 Sorting} *)
 
 
 val sort : cmp:('a -> 'a -> int) -> 'a list -> 'a list
diff --git a/stdlib/nativeint.mli b/stdlib/nativeint.mli
index dc69017594..a047ced5a6 100644
--- a/stdlib/nativeint.mli
+++ b/stdlib/nativeint.mli
@@ -193,7 +193,7 @@ val equal: t -> t -> bool
 
 (**/**)
 
-(** {6 Deprecated functions} *)
+(** {1 Deprecated functions} *)
 
 external format : string -> nativeint -> string = "caml_nativeint_format"
 (** [Nativeint.format fmt n] return the string representation of the
diff --git a/stdlib/parsing.mli b/stdlib/parsing.mli
index baeae9ab5f..73b9504d4f 100644
--- a/stdlib/parsing.mli
+++ b/stdlib/parsing.mli
@@ -71,7 +71,7 @@ val set_trace: bool -> bool
 
 (**/**)
 
-(** {6  } *)
+(** {1  } *)
 
 (** The following definitions are used by the generated parsers only.
    They are not intended to be used directly by user programs. *)
diff --git a/stdlib/pervasives.mli b/stdlib/pervasives.mli
index b9e52401a7..af0cffee40 100644
--- a/stdlib/pervasives.mli
+++ b/stdlib/pervasives.mli
@@ -25,7 +25,7 @@
 *)
 
 
-(** {6 Exceptions} *)
+(** {1 Exceptions} *)
 
 external raise : exn -> 'a = "%raise"
 (** Raise the given exception value *)
@@ -46,7 +46,7 @@ exception Exit
     provided for use in your programs. *)
 
 
-(** {6 Comparisons} *)
+(** {1 Comparisons} *)
 
 external ( = ) : 'a -> 'a -> bool = "%equal"
 (** [e1 = e2] tests for structural equality of [e1] and [e2].
@@ -129,7 +129,7 @@ external ( != ) : 'a -> 'a -> bool = "%noteq"
     Left-associative operator at precedence level 4/11. *)
 
 
-(** {6 Boolean operations} *)
+(** {1 Boolean operations} *)
 
 external not : bool -> bool = "%boolnot"
 (** The boolean negation. *)
@@ -157,7 +157,7 @@ external ( or ) : bool -> bool -> bool = "%sequor"
 (** @deprecated {!Pervasives.( || )} should be used instead.
     Right-associative operator at precedence level 2/11. *)
 
-(** {6 Debugging} *)
+(** {1 Debugging} *)
 
 external __LOC__ : string = "%loc_LOC"
 (** [__LOC__] returns the location at which this expression appears in
@@ -218,7 +218,7 @@ external __POS_OF__ : 'a -> (string * int * int * int) * 'a = "%loc_POS"
     @since 4.02.0
  *)
 
-(** {6 Composition operators} *)
+(** {1 Composition operators} *)
 
 external ( |> ) : 'a -> ('a -> 'b) -> 'b = "%revapply"
 (** Reverse-application operator: [x |> f |> g] is exactly equivalent
@@ -234,7 +234,7 @@ external ( @@ ) : ('a -> 'b) -> 'a -> 'b = "%apply"
    @since 4.01
 *)
 
-(** {6 Integer arithmetic} *)
+(** {1 Integer arithmetic} *)
 
 (** Integers are 31 bits wide (or 63 bits on 64-bit processors).
    All operations are taken modulo 2{^31} (or 2{^63}).
@@ -300,7 +300,7 @@ val min_int : int
 (** The smallest representable integer. *)
 
 
-(** {7 Bitwise operations} *)
+(** {2 Bitwise operations} *)
 
 external ( land ) : int -> int -> int = "%andint"
 (** Bitwise logical and.
@@ -338,7 +338,7 @@ external ( asr ) : int -> int -> int = "%asrint"
    Right-associative operator at precedence level 8/11. *)
 
 
-(** {6 Floating-point arithmetic}
+(** {1 Floating-point arithmetic}
 
    OCaml's floating-point numbers follow the
    IEEE 754 standard, using double precision (64 bits) numbers.
@@ -564,7 +564,7 @@ external classify_float : (float [@unboxed]) -> fpclass =
    normal, subnormal, zero, infinite, or not a number. *)
 
 
-(** {6 String operations}
+(** {1 String operations}
 
    More string operations are provided in module {!String}.
 *)
@@ -574,7 +574,7 @@ val ( ^ ) : string -> string -> string
     Right-associative operator at precedence level 5/11. *)
 
 
-(** {6 Character operations}
+(** {1 Character operations}
 
    More character operations are provided in module {!Char}.
 *)
@@ -588,7 +588,7 @@ val char_of_int : int -> char
    outside the range 0--255. *)
 
 
-(** {6 Unit operations} *)
+(** {1 Unit operations} *)
 
 external ignore : 'a -> unit = "%ignore"
 (** Discard the value of its argument and return [()].
@@ -599,7 +599,7 @@ external ignore : 'a -> unit = "%ignore"
    avoids the warning. *)
 
 
-(** {6 String conversion functions} *)
+(** {1 String conversion functions} *)
 
 val string_of_bool : bool -> string
 (** Return the string representation of a boolean. As the returned values
@@ -670,7 +670,7 @@ val float_of_string_opt: string -> float option
     @since 4.05
 *)
 
-(** {6 Pair operations} *)
+(** {1 Pair operations} *)
 
 external fst : 'a * 'b -> 'a = "%field0"
 (** Return the first component of a pair. *)
@@ -679,7 +679,7 @@ external snd : 'a * 'b -> 'b = "%field1"
 (** Return the second component of a pair. *)
 
 
-(** {6 List operations}
+(** {1 List operations}
 
    More list operations are provided in module {!List}.
 *)
@@ -689,7 +689,7 @@ val ( @ ) : 'a list -> 'a list -> 'a list
     Right-associative operator at precedence level 5/11. *)
 
 
-(** {6 Input/output}
+(** {1 Input/output}
     Note: all input/output functions can raise [Sys_error] when the system
     calls they invoke fail. *)
 
@@ -709,7 +709,7 @@ val stderr : out_channel
 (** The standard error output for the process. *)
 
 
-(** {7 Output functions on standard output} *)
+(** {2 Output functions on standard output} *)
 
 val print_char : char -> unit
 (** Print a character on standard output. *)
@@ -737,7 +737,7 @@ val print_newline : unit -> unit
    buffering of standard output. *)
 
 
-(** {7 Output functions on standard error} *)
+(** {2 Output functions on standard error} *)
 
 val prerr_char : char -> unit
 (** Print a character on standard error. *)
@@ -764,7 +764,7 @@ val prerr_newline : unit -> unit
    standard error. *)
 
 
-(** {7 Input functions on standard input} *)
+(** {2 Input functions on standard input} *)
 
 val read_line : unit -> string
 (** Flush standard output, then read characters from standard input
@@ -795,7 +795,7 @@ val read_float_opt: unit -> float option
     @since 4.05.0 *)
 
 
-(** {7 General output functions} *)
+(** {2 General output functions} *)
 
 type open_flag =
     Open_rdonly      (** open for reading. *)
@@ -919,7 +919,7 @@ val set_binary_mode_out : out_channel -> bool -> unit
    do not distinguish between text mode and binary mode. *)
 
 
-(** {7 General input functions} *)
+(** {2 General input functions} *)
 
 val open_in : string -> in_channel
 (** Open the named file for reading, and return a new input channel
@@ -1035,7 +1035,7 @@ val set_binary_mode_in : in_channel -> bool -> unit
    do not distinguish between text mode and binary mode. *)
 
 
-(** {7 Operations on large files} *)
+(** {2 Operations on large files} *)
 
 module LargeFile :
   sig
@@ -1054,7 +1054,7 @@ module LargeFile :
   operating on files whose sizes are greater than [max_int]. *)
 
 
-(** {6 References} *)
+(** {1 References} *)
 
 type 'a ref = { mutable contents : 'a }
 (** The type of references (mutable indirection cells) containing
@@ -1081,12 +1081,12 @@ external decr : int ref -> unit = "%decr"
 (** Decrement the integer contained in the given reference.
    Equivalent to [fun r -> r := pred !r]. *)
 
-(** {6 Result type} *)
+(** {1 Result type} *)
 
 (** @since 4.03.0 *)
 type ('a,'b) result = Ok of 'a | Error of 'b
 
-(** {6 Operations on format strings} *)
+(** {1 Operations on format strings} *)
 
 (** Format strings are character strings with special lexical conventions
   that defines the functionality of formatted input/output functions. Format
@@ -1188,7 +1188,7 @@ val ( ^^ ) :
   Right-associative operator at precedence level 5/11. *)
 
 
-(** {6 Program termination} *)
+(** {1 Program termination} *)
 
 val exit : int -> 'a
 (** Terminate the process, returning the given status code
diff --git a/stdlib/printexc.mli b/stdlib/printexc.mli
index cc865085ca..873e385f67 100644
--- a/stdlib/printexc.mli
+++ b/stdlib/printexc.mli
@@ -92,7 +92,7 @@ val register_printer: (exn -> string option) -> unit
     @since 3.11.2
 *)
 
-(** {6 Raw backtraces} *)
+(** {1 Raw backtraces} *)
 
 type raw_backtrace
 (** The abstract type [raw_backtrace] stores a backtrace in
@@ -140,7 +140,7 @@ external raise_with_backtrace: exn -> raw_backtrace -> 'a
     @since 4.05.0
 *)
 
-(** {6 Current call stack} *)
+(** {1 Current call stack} *)
 
 val get_callstack: int -> raw_backtrace
 (** [Printexc.get_callstack n] returns a description of the top of the
@@ -151,7 +151,7 @@ val get_callstack: int -> raw_backtrace
     @since 4.01.0
 *)
 
-(** {6 Uncaught exceptions} *)
+(** {1 Uncaught exceptions} *)
 
 val set_uncaught_exception_handler: (exn -> raw_backtrace -> unit) -> unit
 (** [Printexc.set_uncaught_exception_handler fn] registers [fn] as the handler
@@ -172,7 +172,7 @@ val set_uncaught_exception_handler: (exn -> raw_backtrace -> unit) -> unit
 *)
 
 
-(** {6 Manipulation of backtrace information}
+(** {1 Manipulation of backtrace information}
 
     These functions are used to traverse the slots of a raw backtrace
     and extract information from them in a programmer-friendly format.
@@ -261,7 +261,7 @@ module Slot : sig
 end
 
 
-(** {6 Raw backtrace slots} *)
+(** {1 Raw backtrace slots} *)
 
 type raw_backtrace_slot
 (** This type allows direct access to raw backtrace slots, without any
@@ -324,7 +324,7 @@ val get_raw_backtrace_next_slot :
     @since 4.04.0
 *)
 
-(** {6 Exception slots} *)
+(** {1 Exception slots} *)
 
 val exn_slot_id: exn -> int
 (** [Printexc.exn_slot_id] returns an integer which uniquely identifies
diff --git a/stdlib/random.mli b/stdlib/random.mli
index 0cbaace3e9..f8eae5fac9 100644
--- a/stdlib/random.mli
+++ b/stdlib/random.mli
@@ -15,7 +15,7 @@
 
 (** Pseudo-random number generators (PRNG). *)
 
-(** {6 Basic functions} *)
+(** {1 Basic functions} *)
 
 val init : int -> unit
 (** Initialize the generator, using the argument as a seed.
@@ -64,7 +64,7 @@ val bool : unit -> bool
 (** [Random.bool ()] returns [true] or [false] with probability 0.5 each. *)
 
 
-(** {6 Advanced functions} *)
+(** {1 Advanced functions} *)
 
 (** The functions from module {!State} manipulate the current state
     of the random generator explicitly.
diff --git a/stdlib/scanf.mli b/stdlib/scanf.mli
index b848164e1c..c3d2a6a8aa 100644
--- a/stdlib/scanf.mli
+++ b/stdlib/scanf.mli
@@ -15,9 +15,9 @@
 
 (** Formatted input functions. *)
 
-(** {6 Introduction} *)
+(** {1 Introduction} *)
 
-(** {7 Functional input with format strings} *)
+(** {2 Functional input with format strings} *)
 
 (** The module {!Scanf} provides formatted input functions or {e scanners}.
 
@@ -48,7 +48,7 @@
     read in the input according to [fmt].
 *)
 
-(** {7 A simple example} *)
+(** {2 A simple example} *)
 
 (** As suggested above, the expression [bscanf ic "%d" f] reads a decimal
     integer [n] from the source of characters [ic] and returns [f n].
@@ -66,7 +66,7 @@
     keyboard, the result we get is [42].
 *)
 
-(** {7 Formatted input as a functional feature} *)
+(** {2 Formatted input as a functional feature} *)
 
 (** The OCaml scanning facility is reminiscent of the corresponding C feature.
     However, it is also largely different, simpler, and yet more powerful:
@@ -81,7 +81,7 @@
     facility is fully type-checked at compile time.
 *)
 
-(** {6 Formatted input channel} *)
+(** {1 Formatted input channel} *)
 
 module Scanning : sig
 
@@ -203,7 +203,7 @@ val stdib : in_channel
 
 end
 
-(** {6 Type of formatted input functions} *)
+(** {1 Type of formatted input functions} *)
 
 type ('a, 'b, 'c, 'd) scanner =
      ('a, Scanning.in_channel, 'b, 'c, 'a -> 'd, 'd) format6 -> 'c
@@ -235,7 +235,7 @@ exception Scan_failure of string
     [Scan_failure].
 *)
 
-(** {6 The general formatted input function} *)
+(** {1 The general formatted input function} *)
 
 val bscanf : Scanning.in_channel -> ('a, 'b, 'c, 'd) scanner
 
@@ -253,7 +253,7 @@ val bscanf : Scanning.in_channel -> ('a, 'b, 'c, 'd) scanner
     string.
 *)
 
-(** {6 Format string description} *)
+(** {1 Format string description} *)
 
 (** The format string is a character string which contains three types of
     objects:
@@ -265,7 +265,7 @@ val bscanf : Scanning.in_channel -> ('a, 'b, 'c, 'd) scanner
       (see scanning {!Scanf.indication}).
 *)
 
-(** {7:space The space character in format strings} *)
+(** {2:space The space character in format strings} *)
 
 (** As mentioned above, a plain character in the format string is just
     matched with the next character of the input; however, two characters are
@@ -285,7 +285,7 @@ val bscanf : Scanning.in_channel -> ('a, 'b, 'c, 'd) scanner
     [Price  =  1    $], or even [Price=1$].
 *)
 
-(** {7:conversion Conversion specifications in format strings} *)
+(** {2:conversion Conversion specifications in format strings} *)
 
 (** Conversion specifications consist in the [%] character, followed by
     an optional flag, an optional field width, and followed by one or
@@ -414,7 +414,7 @@ val bscanf : Scanning.in_channel -> ('a, 'b, 'c, 'd) scanner
     [ocamlyacc]-generated parsers.
 *)
 
-(** {7:indication Scanning indications in format strings} *)
+(** {2:indication Scanning indications in format strings} *)
 
 (** Scanning indications appear just after the string conversions [%s]
     and [%[ range ]] to delimit the end of the token. A scanning
@@ -443,7 +443,7 @@ val bscanf : Scanning.in_channel -> ('a, 'b, 'c, 'd) scanner
     characters).
 *)
 
-(** {7 Exceptions during scanning} *)
+(** {2 Exceptions during scanning} *)
 
 (** Scanners may raise the following exceptions when the input cannot be read
     according to the format string:
@@ -464,7 +464,7 @@ val bscanf : Scanning.in_channel -> ('a, 'b, 'c, 'd) scanner
     simply returns the characters read so far, or [""] if none were ever read.
 *)
 
-(** {6 Specialised formatted input functions} *)
+(** {1 Specialised formatted input functions} *)
 
 val sscanf : string -> ('a, 'b, 'c, 'd) scanner
 (** Same as {!Scanf.bscanf}, but reads from the given string. *)
@@ -490,7 +490,7 @@ val ksscanf :
 (** Same as {!Scanf.kscanf} but reads from the given string.
     @since 4.02.0 *)
 
-(** {6 Reading format strings from input} *)
+(** {1 Reading format strings from input} *)
 
 val bscanf_format :
   Scanning.in_channel -> ('a, 'b, 'c, 'd, 'e, 'f) format6 ->
@@ -535,7 +535,7 @@ val unescaped : string -> string
     @since 4.00.0
 *)
 
-(** {6 Deprecated} *)
+(** {1 Deprecated} *)
 
 val fscanf : Pervasives.in_channel -> ('a, 'b, 'c, 'd) scanner
   [@@ocaml.deprecated "Use Scanning.from_channel then Scanf.bscanf."]
diff --git a/stdlib/stream.mli b/stdlib/stream.mli
index 03b34a04b8..e52bab8961 100644
--- a/stdlib/stream.mli
+++ b/stdlib/stream.mli
@@ -27,7 +27,7 @@ exception Error of string
    accepted, but one of the following components is rejected. *)
 
 
-(** {6 Stream builders} *)
+(** {1 Stream builders} *)
 
 val from : (int -> 'a option) -> 'a t
 (** [Stream.from f] returns a stream built from the function [f].
@@ -56,14 +56,14 @@ val of_channel : in_channel -> char t
 (** Return the stream of the characters read from the input channel. *)
 
 
-(** {6 Stream iterator} *)
+(** {1 Stream iterator} *)
 
 val iter : ('a -> unit) -> 'a t -> unit
 (** [Stream.iter f s] scans the whole stream s, applying function [f]
    in turn to each stream element encountered. *)
 
 
-(** {6 Predefined parsers} *)
+(** {1 Predefined parsers} *)
 
 val next : 'a t -> 'a
 (** Return the first element of the stream and remove it from the
@@ -73,7 +73,7 @@ val empty : 'a t -> unit
 (** Return [()] if the stream is empty, else raise {!Stream.Failure}. *)
 
 
-(** {6 Useful functions} *)
+(** {1 Useful functions} *)
 
 val peek : 'a t -> 'a option
 (** Return [Some] of "the first element" of the stream, or [None] if
diff --git a/stdlib/sys.mli b/stdlib/sys.mli
index 715e119c13..3c86a14473 100644
--- a/stdlib/sys.mli
+++ b/stdlib/sys.mli
@@ -159,7 +159,7 @@ external runtime_parameters : unit -> string = "caml_runtime_parameters"
     @since 4.03.0 *)
 
 
-(** {6 Signal handling} *)
+(** {1 Signal handling} *)
 
 
 type signal_behavior =
@@ -185,7 +185,7 @@ val set_signal : int -> signal_behavior -> unit
 (** Same as {!Sys.signal} but return value is ignored. *)
 
 
-(** {7 Signal numbers for the standard POSIX signals.} *)
+(** {2 Signal numbers for the standard POSIX signals.} *)
 
 val sigabrt : int
 (** Abnormal termination *)
@@ -313,7 +313,7 @@ val runtime_warnings_enabled: unit -> bool
 
     @since 4.03.0 *)
 
-(** {6 Optimization} *)
+(** {1 Optimization} *)
 
 external opaque_identity : 'a -> 'a = "%opaque"
 (** For the purposes of optimization, [opaque_identity] behaves like an
diff --git a/stdlib/weak.mli b/stdlib/weak.mli
index 951cd9c04e..842520aa10 100644
--- a/stdlib/weak.mli
+++ b/stdlib/weak.mli
@@ -16,7 +16,7 @@
 (** Arrays of weak pointers and hash sets of weak pointers. *)
 
 
-(** {6 Low-level functions} *)
+(** {1 Low-level functions} *)
 
 type 'a t
 (** The type of arrays of weak pointers (weak arrays).  A weak
@@ -92,7 +92,7 @@ val blit : 'a t -> int -> 'a t -> int -> int -> unit
    do not designate a valid subarray of [ar2].*)
 
 
-(** {6 Weak hash sets} *)
+(** {1 Weak hash sets} *)
 
 (** A weak hash set is a hashed set of values.  Each value may
     magically disappear from the set when it is not used by the
diff --git a/typing/tast_mapper.mli b/typing/tast_mapper.mli
index a883b4eefe..2251fa5709 100644
--- a/typing/tast_mapper.mli
+++ b/typing/tast_mapper.mli
@@ -16,7 +16,7 @@
 open Asttypes
 open Typedtree
 
-(** {2 A generic Typedtree mapper} *)
+(** {1 A generic Typedtree mapper} *)
 
 type mapper =
   {
diff --git a/typing/typedtree.mli b/typing/typedtree.mli
index c168ed2a27..2e89ed5233 100644
--- a/typing/typedtree.mli
+++ b/typing/typedtree.mli
@@ -28,12 +28,12 @@ open Types
 
 type partial = Partial | Total
 
-(** {2 Extension points} *)
+(** {1 Extension points} *)
 
 type attribute = Parsetree.attribute
 type attributes = attribute list
 
-(** {2 Core language} *)
+(** {1 Core language} *)
 
 type pattern =
   { pat_desc: pattern_desc;
diff --git a/utils/misc.mli b/utils/misc.mli
index b05f9aa135..7b91844081 100644
--- a/utils/misc.mli
+++ b/utils/misc.mli
@@ -314,7 +314,7 @@ val delete_eol_spaces : string -> string
 
 
 
-(** {2 Hook machinery}
+(** {1 Hook machinery}
 
     Hooks machinery:
    [add_hook name f] will register a function that will be called on the