Dear Ocaml users,

The upcoming version 4.06.0 of the ocaml distribution contains an unusual amount
of bug fixes for ocamldoc. Unfortunately, three of these changes may break some
workflow; these breaking changes concern

 - the definition of module preamble
 - the semantic of ocamldoc heading levels
 - the html structure produced by ocamldoc

Nevertheless, only the first change may affect users using the default ocamldoc
settings and only in some corner cases. Contrarily, the heading level and html output
changes should mostly affect users of custom documentation styles.

More precisely,

- First(GPR#1037), the preamble of the documentation is now defined as the first
  documentation comment present in a ml or mli file, only if this documentation
  comment comes before any module elements.
  The intent here is to avoid using as a preamble a documentation comment extracted
  from the middle of the mli file and avoid repeating this comment:

       type t = A | B
       val x: t

      (** In other words, before 4.06, this documentation comment was considered
          as both a preamble for the whole file and a documentation comment for "y"
      *)
      val y: t

  This may cause some troubles with open statements laying at the top of an interface
  files:

       open M

       (** This is not considered as a preamble anymore *)


- Second(GPR#830), the semantic of heading
  level in ocamldoc has been changed to make it possible to use "{1" for standard
  documentation section. Before this change section headings should have started
  at "{2" and "{1" was reserved for the module titles. This is no longer the case.

  The default css style and mapping to latex and texinfo heading levels have been
  updated to make this change invisible in the default ocamldoc setting.

  As a consequence ocamldoc html backend maps now the ocamldoc heading level "{n" to
  the html heading level "<h(n+1)>". Custom css style that redefined the style of
  these headings will need to be updated.

  The other ocamldoc backends have been updated to translate both heading level
  "{1" and "{2" to the same heading level in the target language by default, but
  this can be changed using the "-latextitle" or "-infotitle" option.


- Third(GPR#802 and GPR#804), the output of the html renderer has been significantly
  updated to replace all use of "<br>" tags by semantic html tags which should make much
  easier to style consistently the resulting html with css. Similarly, the paragraph tag is now
  used in a much more regular way.

  Unfortunately, this also means that custom css that tried to recover semantic
  information from the position of "<br>" tags will need to be updated.

Happy documentation hacking,
Florian "octachron" Angeletti.