Merge pull request #10139 from johnwhitington/no-navbar

Remove confusing navigation bar from stdlib documentation

Changes

@@ -55,8 +55,18 @@ Working version
 
 ### Tools:
 
+- #10139: Remove confusing navigation bar from stdlib documentation.
+  Adds a -nonavbar option to ocamldoc, and uses it to improve navigation within
+  the reference manual.
+  (John Whitington, review by David Allsopp)
+
 ### Manual and documentation:
 
+- #10139: Remove confusing navigation bar from stdlib documentation.
+  Removes the 'Up', 'Previous' and 'Next' links from the top of each standard
+  library module's documentation.
+  (John Whitington, review by David Allsopp)
+
 ### Compiler user-interface and warnings:
 
 - #9960: extend ocamlc/ocamlopt's -o option to work when compiling C files

api_docgen/Makefile

@@ -99,13 +99,13 @@ html/libref/Stdlib.html: $(ALL_LIBREF:%=build/%.odoc)
 	$(MKDIR) -p html/libref
 	$(OCAMLDOC_RUN) -html -d html/libref \
 	-charset="utf8" \
-	-nostdlib -hide Stdlib -lib Stdlib -t "OCaml library" \
+	-nonavbar -nostdlib -hide Stdlib -lib Stdlib -t "OCaml library" \
 	$(addprefix -load , $(ALL_LIBREF:%=build/%.odoc))
 
 html/compilerlibref/Compiler_libs.html: $(ALL_COMPILERLIBREF:%=build/%.odoc)
 	$(MKDIR) -p html/compilerlibref
 	$(OCAMLDOC_RUN) -html -d html/compilerlibref \
-	-nostdlib -hide Stdlib -t "OCaml compiler library" \
+	-nonavbar -nostdlib -hide Stdlib -t "OCaml compiler library" \
 	-charset="utf8" \
 	-intro Compiler_libs.mld \
 	$(addprefix -load , $(ALL_COMPILERLIBREF:%=build/%.odoc))

manual/README.md

@@ -18,7 +18,7 @@ package manager may not do this for you. Run `kpsewhich hevea.sty` to check.
 Building
 --------
 
-0. Install the OCaml distribution.
+0. Install the OCaml distribution. You must build the native compiler.
 
 1. Run `make` in the manual.
 

manual/manual/Makefile

@@ -4,16 +4,8 @@ export LD_LIBRARY_PATH   ?= "$(SRC)/otherlibs/unix/:$(SRC)/otherlibs/str/"
 export DYLD_LIBRARY_PATH ?= "$(SRC)/otherlibs/unix/:$(SRC)/otherlibs/str/"
 SET_LD_PATH = CAML_LD_LIBRARY_PATH=$(LD_LIBRARY_PATH)
 
-OCAMLDOC = $(if $(wildcard $(SRC)/ocamldoc/ocamldoc.opt),\
-  $(SRC)/ocamldoc/ocamldoc.opt,\
-  $(SET_LD_PATH) $(SRC)/runtime/ocamlrun $(SRC)/ocamldoc/ocamldoc)\
-  -hide Stdlib -lib Stdlib -nostdlib \
-  -pp "$(AWK) -v ocamldoc=true -f $(SRC)/stdlib/expand_module_aliases.awk"
-
-
 TEXQUOTE = $(SRC)/runtime/ocamlrun ../tools/texquote2
 
-
 FILES = allfiles.tex biblio.tex foreword.tex version.tex warnings-help.etex
 
 TEXINPUTS = ".:..:../refman:../library:../cmds:../tutorials:../../styles:"

ocamldoc/odoc_args.ml

@@ -281,7 +281,8 @@ let default_options = Options.list @
   "-index-only", Arg.Set Odoc_html.index_only, M.index_only ;
   "-colorize-code", Arg.Set Odoc_html.colorize_code, M.colorize_code ;
   "-short-functors", Arg.Set Odoc_html.html_short_functors, M.html_short_functors ;
-  "-charset", Arg.Set_string Odoc_html.charset, (M.charset !Odoc_html.charset)^
+  "-charset", Arg.Set_string Odoc_html.charset, (M.charset !Odoc_html.charset) ;
+  "-nonavbar", Arg.Clear Odoc_html.show_navbar, M.no_navbar ^
   "\n\n *** LaTeX options ***\n";
 
 (* latex only options *)

ocamldoc/odoc_html.ml

@@ -30,6 +30,7 @@ let index_only = ref false
 let colorize_code = ref false
 let html_short_functors = ref false
 let charset = ref "iso-8859-1"
+let show_navbar = ref true
 
 
 (** The functions used for naming files and html marks.*)
@@ -743,7 +744,7 @@ class virtual info =
           | Some d ->
                bs b "<div class=\"info-deprecated\">\n";
                bs b "<span class=\"warning\">";
-               bs b Odoc_messages.deprecated ;
+               bs b (Odoc_messages.deprecated^". ");
                bs b "</span>" ;
                self#html_of_text b d;
                bs b "</div>\n"
@@ -1182,32 +1183,34 @@ class html =
        @param post optional name for optional next module/class
        @param name name of current module/class *)
     method print_navbar b pre post name =
-      bs b "<div class=\"navbar\">";
-      (
-       match pre with
-         None -> ()
-       | Some name ->
-           bp b "<a class=\"pre\" href=\"%s\" title=\"%s\">%s</a>\n"
-             (fst (Naming.html_files name))
-             name
-             Odoc_messages.previous
-      );
-      bs b "&nbsp;";
-      let father = Name.father name in
-      let href = if father = "" then self#index else fst (Naming.html_files father) in
-      let father_name = if father = "" then "Index" else father in
-      bp b "<a class=\"up\" href=\"%s\" title=\"%s\">%s</a>\n" href father_name Odoc_messages.up;
-      bs b "&nbsp;";
-      (
-       match post with
-         None -> ()
-       | Some name ->
-           bp b "<a class=\"post\" href=\"%s\" title=\"%s\">%s</a>\n"
-             (fst (Naming.html_files name))
-             name
-             Odoc_messages.next
-      );
-      bs b "</div>\n"
+      if !show_navbar then begin
+        bs b "<div class=\"navbar\">";
+        (
+         match pre with
+           None -> ()
+         | Some name ->
+             bp b "<a class=\"pre\" href=\"%s\" title=\"%s\">%s</a>\n"
+               (fst (Naming.html_files name))
+               name
+               Odoc_messages.previous
+        );
+        bs b "&nbsp;";
+        let father = Name.father name in
+        let href = if father = "" then self#index else fst (Naming.html_files father) in
+        let father_name = if father = "" then "Index" else father in
+        bp b "<a class=\"up\" href=\"%s\" title=\"%s\">%s</a>\n" href father_name Odoc_messages.up;
+        bs b "&nbsp;";
+        (
+         match post with
+           None -> ()
+         | Some name ->
+             bp b "<a class=\"post\" href=\"%s\" title=\"%s\">%s</a>\n"
+               (fst (Naming.html_files name))
+               name
+               Odoc_messages.next
+        );
+        bs b "</div>\n"
+      end
 
     (** Return html code with the given string in the keyword style.*)
     method keyword s =

ocamldoc/odoc_man.ml

@@ -206,7 +206,7 @@ class virtual info =
            | Some d ->
                let b = Buffer.create 256 in
                bs b ".B \"";
-               bs b Odoc_messages.deprecated;
+               bs b (Odoc_messages.deprecated^".");
                bs b "\"\n";
                self#man_of_text b d;
                bs b "\n";

ocamldoc/odoc_messages.ml

@@ -52,6 +52,7 @@ let html_short_functors = " Use short form to display functor types "^html_only
 let charset c = Printf.sprintf
   "<s> Add information about character encoding being s\n\t\t(default is %s)"
   c
+let no_navbar = " Do not include the navigation bar "^html_only
 let generate_html = " Generate HTML documentation"
 let generate_latex = " Generate LaTeX documentation"
 let generate_texinfo = " Generate TeXinfo documentation"
@@ -388,7 +389,7 @@ let authors = "Author(s)"
 let version = "Version"
 let since = "Since"
 let before = "Before"
-let deprecated = "Deprecated."
+let deprecated = "Deprecated"
 let raises = "Raises"
 let returns = "Returns"
 let inherits = "Inherits"

ocamldoc/odoc_misc.ml

@@ -217,7 +217,7 @@ let string_of_info i =
   let module M = Odoc_types in
   (match i.M.i_deprecated with
     None -> ""
-  | Some d -> Odoc_messages.deprecated^"! "^(string_of_text d)^"\n")^
+  | Some d -> Odoc_messages.deprecated^". "^(string_of_text d)^"\n")^
   (match i.M.i_desc with
     None -> ""
   | Some d when d = [Odoc_types.Raw ""] -> ""

ocamldoc/odoc_texi.ml

@@ -529,7 +529,7 @@ class texi =
                  [ ( match info.i_deprecated with
                  | None -> []
                  | Some t ->
-                     (Raw (Odoc_messages.deprecated ^ " ")) ::
+                     (Raw (Odoc_messages.deprecated ^ ". ")) ::
                      (self#fix_linebreaks t)
                      @ [ Newline ; Newline ] ) ;
                    self#text_of_desc info.i_desc ;

ocamldoc/odoc_to_text.ml

@@ -153,7 +153,7 @@ class virtual info =
           let t =
             (match info.i_deprecated with
               None -> []
-            | Some t -> ( Italic [Raw (Odoc_messages.deprecated^" ")] ) :: t
+            | Some t -> ( Italic [Raw (Odoc_messages.deprecated^". ")] ) :: t
              ) @
             (match info.i_desc with
               None -> []

testsuite/tests/tool-ocamldoc/Documentation_tags.html.reference

@@ -24,7 +24,7 @@
 
 <pre><span id="VALheterological"><span class="keyword">val</span> heterological</span> : <code class="type">unit</code></pre><div class="info ">
 <div class="info-deprecated">
-<span class="warning">Deprecated.</span>since the start of time</div>
+<span class="warning">Deprecated. </span>since the start of time</div>
 <ul class="info-attributes">
 <li><b>Author(s):</b> yes</li>
 <li><b>Before Time </b> not implemented</li>