[Caml-list] Upcoming breaking changes in Ocamldoc 4.06

[octachron <octa@polychoron.fr>]

[-- Attachment #1: Type: text/plain, Size: 3064 bytes --]

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 <https://github.com/ocaml/ocaml/pull/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 <https://github.com/ocaml/ocaml/pull/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 <https://github.com/ocaml/ocaml/pull/802> and GPR#804 
<https://github.com/ocaml/ocaml/pull/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.


[-- Attachment #2: Type: text/html, Size: 3986 bytes --]