PR#7363, ocamldoc: implicit level 0 for titles

This commit makes the heading hierarchy of ocamldoc start at {0 rather
than {1. This level {0 should be reserved for global titles, freeing
the use of {1 for normal subtitles.

8 files changed, 73 insertions, 15 deletions

diff --git a/manual/manual/library/Makefile b/manual/manual/library/Makefile
index 72b19865b8..a64a7d943d 100644
--- a/manual/manual/library/Makefile
+++ b/manual/manual/library/Makefile
@@ -78,8 +78,8 @@ interfaces: $(MLIS)
 	-I $(CSLDIR)/otherlibs/unix \
 	$(MLIS) \
 	-sepfiles \
-	-latextitle "6,subsection*" \
-	-latextitle "7,subsubsection*" \
+	-latextitle "1,subsection*" \
+	-latextitle "2,subsubsection*" \
 	-latex-type-prefix "TYP" \
 	-latex-module-prefix "" \
 	-latex-module-type-prefix "" \
diff --git a/ocamldoc/odoc_html.ml b/ocamldoc/odoc_html.ml
index 3bd9dc5abf..123cc7b537 100644
--- a/ocamldoc/odoc_html.ml
+++ b/ocamldoc/odoc_html.ml
@@ -472,9 +472,9 @@ class virtual text =
       let label1 = self#create_title_label (n, label_opt, t) in
       let (tag_o, tag_c) =
         if n > 6 then
-          (Printf.sprintf "div class=\"h%d\"" n, "div")
+          (Printf.sprintf "div class=\"h%d\"" (n+1), "div")
         else
-          let t = Printf.sprintf "h%d" n in (t, t)
+          let t = Printf.sprintf "h%d" (n+1) in (t, t)
       in
       bs b "<";
       bp b "%s id=\"%s\"" tag_o (Naming.label_target label1);
@@ -874,42 +874,44 @@ class html =
 
         "h1 { font-size : 20pt ; text-align: center; }" ;
 
-        "h2 { font-size : 20pt ; border: 1px solid #000000; "^
+        "h2 { font-size : 20pt ; text-align: center; }" ;
+
+        "h3 { font-size : 20pt ; border: 1px solid #000000; "^
         "margin-top: 5px; margin-bottom: 2px;"^
         "text-align: center; background-color: #90BDFF ;"^
         "padding: 2px; }" ;
 
-        "h3 { font-size : 20pt ; border: 1px solid #000000; "^
+        "h4 { font-size : 20pt ; border: 1px solid #000000; "^
         "margin-top: 5px; margin-bottom: 2px;"^
         "text-align: center; background-color: #90DDFF ;"^
         "padding: 2px; }" ;
 
-        "h4 { font-size : 20pt ; border: 1px solid #000000; "^
+        "h5 { font-size : 20pt ; border: 1px solid #000000; "^
         "margin-top: 5px; margin-bottom: 2px;"^
         "text-align: center; background-color: #90EDFF ;"^
         "padding: 2px; }" ;
 
-        "h5 { font-size : 20pt ; border: 1px solid #000000; "^
+        "h6 { font-size : 20pt ; border: 1px solid #000000; "^
         "margin-top: 5px; margin-bottom: 2px;"^
         "text-align: center; background-color: #90FDFF ;"^
         "padding: 2px; }" ;
 
-        "h6 { font-size : 20pt ; border: 1px solid #000000; "^
+        "div.h7 { font-size : 20pt ; border: 1px solid #000000; "^
         "margin-top: 5px; margin-bottom: 2px;"^
         "text-align: center; background-color: #90BDFF ; "^
         "padding: 2px; }" ;
 
-        "div.h7 { font-size : 20pt ; border: 1px solid #000000; "^
+        "div.h8 { font-size : 20pt ; border: 1px solid #000000; "^
         "margin-top: 5px; margin-bottom: 2px;"^
         "text-align: center; background-color: #E0FFFF ; "^
         "padding: 2px; }" ;
 
-        "div.h8 { font-size : 20pt ; border: 1px solid #000000; "^
+        "div.h9 { font-size : 20pt ; border: 1px solid #000000; "^
         "margin-top: 5px; margin-bottom: 2px;"^
         "text-align: center; background-color: #F0FFFF ; "^
         "padding: 2px; }" ;
 
-        "div.h9 { font-size : 20pt ; border: 1px solid #000000; "^
+        "div.h10 { font-size : 20pt ; border: 1px solid #000000; "^
         "margin-top: 5px; margin-bottom: 2px;"^
         "text-align: center; background-color: #FFFFFF ; "^
         "padding: 2px; }" ;
@@ -2312,7 +2314,7 @@ class html =
       let text2 =
         match text with
         | (Odoc_info.Raw s) :: q ->
-            (Odoc_info.Title (2, None, [Odoc_info.Raw s])) :: q
+            (Odoc_info.Title (1, None, [Odoc_info.Raw s])) :: q
         | _ -> text
       in
       self#html_of_text ~with_p:true b text2
diff --git a/ocamldoc/odoc_latex.ml b/ocamldoc/odoc_latex.ml
index ee1d942826..292d3d4ae8 100644
--- a/ocamldoc/odoc_latex.ml
+++ b/ocamldoc/odoc_latex.ml
@@ -30,6 +30,7 @@ open Module
 let separate_files = ref false
 
 let latex_titles = ref [
+  0, "section" ;
   1, "section" ;
   2, "subsection" ;
   3, "subsubsection" ;
@@ -1218,7 +1219,7 @@ class latex =
         let subtitle = match first_t with
           | [] -> []
           | t -> (Raw " : ") :: t in
-        [ Title (1, None, title @ subtitle ) ]
+        [ Title (0, None, title @ subtitle ) ]
       in
       self#latex_of_text fmt text;
       self#latex_for_module_label fmt m;
diff --git a/ocamldoc/odoc_texi.ml b/ocamldoc/odoc_texi.ml
index f816a80420..899dbafb80 100644
--- a/ocamldoc/odoc_texi.ml
+++ b/ocamldoc/odoc_texi.ml
@@ -248,6 +248,7 @@ class text =
 
   (** Associations between a title number and texinfo code. *)
     val titles = [
+      0, "@chapter " ;
       1, "@chapter " ;
       2, "@section " ;
       3, "@subsection " ;
@@ -258,6 +259,7 @@ class text =
       "@unnumberedsubsubsec "
 
     val headings = [
+      0, "@majorheading " ;
       1, "@majorheading " ;
       2, "@heading " ;
       3, "@subheading " ;
diff --git a/testsuite/tests/tool-ocamldoc-2/Makefile b/testsuite/tests/tool-ocamldoc-2/Makefile
index 863c72c52c..18ba07db7b 100644
--- a/testsuite/tests/tool-ocamldoc-2/Makefile
+++ b/testsuite/tests/tool-ocamldoc-2/Makefile
@@ -17,6 +17,8 @@ BASEDIR=../..
 COMPFLAGS=-I $(OTOPDIR)/ocamldoc
 LD_PATH=$(TOPDIR)/otherlibs/$(UNIXLIBVAR)unix:$(TOPDIR)/otherlibs/str
 DOCFLAGS=-I $(OTOPDIR)/stdlib $(COMPFLAGS)\
+	-latextitle "1,subsection*" \
+	-latextitle "2,subsubsection*" \
 	-latextitle "6,subsection*" \
 	-latextitle "7,subsubsection*" \
 	-latex-type-prefix "TYP" \
diff --git a/testsuite/tests/tool-ocamldoc-2/level_0.mli b/testsuite/tests/tool-ocamldoc-2/level_0.mli
new file mode 100644
index 0000000000..22c4665d21
--- /dev/null
+++ b/testsuite/tests/tool-ocamldoc-2/level_0.mli
@@ -0,0 +1,15 @@
+(** Test for level 0 headings 
+ 
+  {1 Level 1} 
+   
+   Standard heading levels start at 1.
+
+  {0 Level 0}
+  A level 0 heading is guaranted to be at the same level that
+  the main heading of the module.
+
+  This setup allows users to start their standard heading at level 1 rather 
+  than 2, without losing the ability to add global level heading, 
+  when, if ever, such heading is warranted
+
+ *)
diff --git a/testsuite/tests/tool-ocamldoc-2/level_0.reference b/testsuite/tests/tool-ocamldoc-2/level_0.reference
new file mode 100644
index 0000000000..331512ffc1
--- /dev/null
+++ b/testsuite/tests/tool-ocamldoc-2/level_0.reference
@@ -0,0 +1,36 @@
+\documentclass[11pt]{article} 
+\usepackage[latin1]{inputenc} 
+\usepackage[T1]{fontenc} 
+\usepackage{textcomp}
+\usepackage{fullpage} 
+\usepackage{url} 
+\usepackage{ocamldoc}
+\begin{document}
+\tableofcontents
+\section{Module {\tt{Level\_0}} : Test for level 0 headings }
+\label{Level-underscore0}\index{Level-underscore0@\verb`Level_0`}
+
+
+
+  \subsection*{Level 1}
+ 
+
+
+   Standard heading levels start at 1.
+
+
+  \section{Level 0}
+
+  A level 0 heading is guaranted to be at the same level that
+  the main heading of the module.
+
+
+  This setup allows users to start their standard heading at level 1 rather 
+  than 2, without losing the ability to add global level heading, 
+  when, if ever, such heading is warranted
+
+
+
+\ocamldocvspace{0.5cm}
+
+\end{document}
diff --git a/testsuite/tests/tool-ocamldoc-html/Paragraph.reference b/testsuite/tests/tool-ocamldoc-html/Paragraph.reference
index cf98ab4696..84dee74cf2 100644
--- a/testsuite/tests/tool-ocamldoc-html/Paragraph.reference
+++ b/testsuite/tests/tool-ocamldoc-html/Paragraph.reference
@@ -30,7 +30,7 @@
 <p>See also <a href=" http://caml.inria.fr/mantis/view.php?id=7352"> MPR:7352</a>,
     <a href=" http://caml.inria.fr/mantis/view.php?id=7353"> MPR:7353</a></p>
 
-<h2 id="here">Testing non-text elements </h2>
+<h3 id="here">Testing non-text elements </h3>
 <p><code class="code">code&nbsp;x&nbsp;</code> <i>should </i> be inside a p.</p>
 
 <p><em>But</em> <b>not</b></p>