From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Original-To: caml-list@sympa.inria.fr Delivered-To: caml-list@sympa.inria.fr Received: from mail3-relais-sop.national.inria.fr (mail3-relais-sop.national.inria.fr [192.134.164.104]) by sympa.inria.fr (Postfix) with ESMTPS id 7D77D7F61E for ; Fri, 3 Nov 2017 11:53:55 +0100 (CET) Authentication-Results: mail3-smtp-sop.national.inria.fr; spf=None smtp.pra=octa@polychoron.fr; spf=Pass smtp.mailfrom=octa@polychoron.fr; spf=None smtp.helo=postmaster@relay2-d.mail.gandi.net Received-SPF: None (mail3-smtp-sop.national.inria.fr: no sender authenticity information available from domain of octa@polychoron.fr) identity=pra; client-ip=217.70.183.194; receiver=mail3-smtp-sop.national.inria.fr; envelope-from="octa@polychoron.fr"; x-sender="octa@polychoron.fr"; x-conformance=sidf_compatible Received-SPF: Pass (mail3-smtp-sop.national.inria.fr: domain of octa@polychoron.fr designates 217.70.183.194 as permitted sender) identity=mailfrom; client-ip=217.70.183.194; receiver=mail3-smtp-sop.national.inria.fr; envelope-from="octa@polychoron.fr"; x-sender="octa@polychoron.fr"; x-conformance=sidf_compatible; x-record-type="v=spf1" Received-SPF: None (mail3-smtp-sop.national.inria.fr: no sender authenticity information available from domain of postmaster@relay2-d.mail.gandi.net) identity=helo; client-ip=217.70.183.194; receiver=mail3-smtp-sop.national.inria.fr; envelope-from="octa@polychoron.fr"; x-sender="postmaster@relay2-d.mail.gandi.net"; x-conformance=sidf_compatible IronPort-PHdr: =?us-ascii?q?9a23=3Ajy+xaBMXxktvlYnDyMcl6mtUPXoX/o7sNwtQ0KIM?= =?us-ascii?q?zox0K/n5rarrMEGX3/hxlliBBdydsK0UzbeO+4nbGkU+or+5+EgYd5JNUxJXwe?= =?us-ascii?q?43pCcHRPC/NEvgMfTxZDY7FskRHHVs/nW8LFQHUJ2mPw6a8TWO6msZExD7cA50?= =?us-ascii?q?PfjdG4jIjs3x2frh1YfUZlBPjya0arNoKxP++QLaqsA+mYxmO60xzQHOpD1GYb?= =?us-ascii?q?IFlitTOVuPkkOktY+L95l5/nEItg=3D=3D?= X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: =?us-ascii?q?A0BBAQDRSfxZh8K3RtlWBoRIA2sug3aZO?= =?us-ascii?q?phRggEKI4UYAoRVQxQBAQEBAQEBAQEBEgEBAQgNCQgoL4I4IoJEBiNmCUQCAlc?= =?us-ascii?q?TCAEBihIRDIlpnWeCJyaKdiEFgy6CB4FSghOCTIUOKoMjgkIgBaIOgQFugSmET?= =?us-ascii?q?pkOhzyMYYk1gTk2gg1+EYMugmuBdI0bAYEQAQEB?= X-IPAS-Result: =?us-ascii?q?A0BBAQDRSfxZh8K3RtlWBoRIA2sug3aZOphRggEKI4UYAoR?= =?us-ascii?q?VQxQBAQEBAQEBAQEBEgEBAQgNCQgoL4I4IoJEBiNmCUQCAlcTCAEBihIRDIlpn?= =?us-ascii?q?WeCJyaKdiEFgy6CB4FSghOCTIUOKoMjgkIgBaIOgQFugSmETpkOhzyMYYk1gTk?= =?us-ascii?q?2gg1+EYMugmuBdI0bAYEQAQEB?= X-IronPort-AV: E=Sophos;i="5.44,338,1505772000"; d="scan'208,217";a="243316483" Received: from relay2-d.mail.gandi.net ([217.70.183.194]) by mail3-smtp-sop.national.inria.fr with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 03 Nov 2017 11:53:54 +0100 X-Originating-IP: 92.158.245.230 Received: from [192.168.1.18] (AMarseille-655-1-612-230.w92-158.abo.wanadoo.fr [92.158.245.230]) (Authenticated sender: octa@polychoron.fr) by relay2-d.mail.gandi.net (Postfix) with ESMTPSA id 3133BC5A7F for ; Fri, 3 Nov 2017 11:53:53 +0100 (CET) To: caml-list@inria.fr References: From: octachron Message-ID: <68cb7b92-25af-e7b5-a3a8-1be940bf037b@polychoron.fr> Date: Fri, 3 Nov 2017 11:53:53 +0100 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.4.0 MIME-Version: 1.0 In-Reply-To: Content-Type: multipart/alternative; boundary="------------4865D322D71B8D67A0636068" Content-Language: en-GB Subject: [Caml-list] Upcoming breaking changes in Ocamldoc 4.06 This is a multi-part message in MIME format. --------------4865D322D71B8D67A0636068 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 8bit 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 "". 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 "
" 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 "
" tags will need to be updated. Happy documentation hacking, Florian "octachron" Angeletti. --------------4865D322D71B8D67A0636068 Content-Type: text/html; charset=utf-8 Content-Transfer-Encoding: 8bit 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.

--------------4865D322D71B8D67A0636068--