Doc: Manpages: Group commands by sections

Sections are used to group commands by generating doc sections. The TOC
looks more readable. The first section is also nicer with some
separations between the list items.

Author: Julow

doc/gen_manpage/gen_manpage.ml

@@ -16,7 +16,7 @@ let cat_command cmd args =
         done
       with End_of_file -> ())
 
-type cmd = { name : string; section : string; summary : string }
+type cmd = { name : string; summary : string }
 
 let section_prefix = "COMMANDS: "
 
@@ -25,19 +25,19 @@ let parse_man' =
     | (kind', line) :: tl when kind = kind' -> collect (line :: acc) kind tl
     | tl -> (List.rev acc, tl)
   in
-  let rec commands ~section = function
+  let rec commands acc = function
     | (`Command, line) :: tl ->
         let name = List.hd (String.fields ~empty:false line) in
         let _, tl = collect [] `Command tl in
         let summary, tl = collect [] `Summary tl in
-        { name; section; summary = String.concat ~sep:" " summary }
-        :: commands ~section tl
-    | tl -> sections tl
+        commands ({ name; summary = String.concat ~sep:" " summary } :: acc) tl
+    | tl -> (List.rev acc, tl)
   and sections = function
     | (`Section, line) :: tl when String.is_prefix ~affix:section_prefix line ->
         let first = String.length section_prefix in
         let section = String.with_range ~first line in
-        commands ~section tl
+        let cmds, tl = commands [] tl in
+        (section, cmds) :: sections tl
     | _ :: tl -> sections tl
     | [] -> []
   in
@@ -60,19 +60,32 @@ let parse_man inp =
    with End_of_file -> ());
   parse_man' (List.rev !lines)
 
-let gen_preamble cmds =
-  Printf.printf "{0 Odoc}\n\n{1 odoc}\nOdoc is made of several sub-commands.\n";
+open Printf
+
+let gen_preamble sections =
+  printf "{0 Odoc}\n\n{1 odoc}\nOdoc is made of several sub-commands.\n";
   List.iter
-    (fun { name; summary; _ } ->
-      Printf.printf "- {!\"odoc-%s\"} %s\n" name summary)
-    cmds
+    (fun (section, cmds) ->
+      printf "\n%s:\n\n" section;
+      List.iter
+        (fun { name; summary; _ } ->
+          printf "- {!\"odoc-%s\"} %s\n" name summary)
+        cmds)
+    sections
 
-let gen_subcommand { name; _ } =
-  Printf.printf "\n{1 odoc %s}\n\n{@man[\n%!" name;
-  cat_command "odoc" [ name; "--help" ];
-  Printf.printf "]}\n"
+let gen_manpages sections =
+  List.iter
+    (fun (section, cmds) ->
+      printf "\n{1 %s}\n" section;
+      List.iter
+        (fun { name; _ } ->
+          printf "\n{2 odoc %s}\n\n{@man[\n%!" name;
+          cat_command "odoc" [ name; "--help" ];
+          printf "]}\n")
+        cmds)
+    sections
 
 let () =
-  let subcommands = with_process_in "odoc" [ "--help" ] parse_man in
-  gen_preamble subcommands;
-  List.iter gen_subcommand subcommands
+  let sections = with_process_in "odoc" [ "--help" ] parse_man in
+  gen_preamble sections;
+  gen_manpages sections

doc/manpage.mld

@@ -2,12 +2,21 @@
 
 {1 odoc}
 Odoc is made of several sub-commands.
+
+Compilation pipeline:
+
 - {!"odoc-compile"} Compile a .cmti, .cmt, .cmi or .mld file to an .odoc file.
 - {!"odoc-html-generate"} Generate html files from a .odocl.
 - {!"odoc-link"} Second stage of compilation. Link a .odoc into a .odocl.
 - {!"odoc-support-files"} Copy the support files (e.g. default theme, JavaScript files) to the output directory.
+
+Alternative generators:
+
 - {!"odoc-latex-generate"} Generate latex files from a .odocl.
 - {!"odoc-man-generate"} Generate man files from a .odocl.
+
+Scripting:
+
 - {!"odoc-compile-deps"} List units (with their digest) which needs to be compiled in order to compile this one. The unit itself and its digest is also reported in the output. Dependencies between compile steps are the same as when compiling the ocaml modules.
 - {!"odoc-errors"} Print errors that occurred while compiling or linking.
 - {!"odoc-html-targets"} Print the files that would be generated by html-generate.
@@ -16,16 +25,24 @@ Odoc is made of several sub-commands.
 - {!"odoc-latex-url"} Resolve a reference and output its corresponding url.
 - {!"odoc-man-targets"} Print the files that would be generated by man-generate.
 - {!"odoc-support-files-targets"} Lists the names of the files that odoc support-files outputs.
+
+Legacy pipeline:
+
 - {!"odoc-compile-targets"} Print the name of the file produced by compile. If -o is passed, the same path is printed but error checking is performed.
 - {!"odoc-html"} Render html files from a .odoc. link then html-generate should be used instead.
 - {!"odoc-html-fragment"} Generates an html fragment file from an mld one.
 - {!"odoc-latex"} Render latex files from a .odoc. link then latex-generate should be used instead.
 - {!"odoc-link-deps"} Lists a subset of the packages and modules which need to be in odoc's load path to link the odoc files in the given directory. Additional packages may be required to resolve all references.
 - {!"odoc-man"} Render man files from a .odoc. link then man-generate should be used instead.
+
+Deprecated:
+
 - {!"odoc-css"} DEPRECATED: Use odoc support-files to copy the CSS file for the default theme.
 - {!"odoc-html-deps"} DEPRECATED: alias for link-deps
 
-{1 odoc compile}
+{1 Compilation pipeline}
+
+{2 odoc compile}
 
 {@man[
 NAME
@@ -115,7 +132,7 @@ ENVIRONMENT
 
 ]}
 
-{1 odoc html-generate}
+{2 odoc html-generate}
 
 {@man[
 NAME
@@ -192,7 +209,7 @@ ENVIRONMENT
 
 ]}
 
-{1 odoc link}
+{2 odoc link}
 
 {@man[
 NAME
@@ -262,7 +279,7 @@ ENVIRONMENT
 
 ]}
 
-{1 odoc support-files}
+{2 odoc support-files}
 
 {@man[
 NAME
@@ -290,7 +307,9 @@ OPTIONS
 
 ]}
 
-{1 odoc latex-generate}
+{1 Alternative generators}
+
+{2 odoc latex-generate}
 
 {@man[
 NAME
@@ -338,7 +357,7 @@ ENVIRONMENT
 
 ]}
 
-{1 odoc man-generate}
+{2 odoc man-generate}
 
 {@man[
 NAME
@@ -383,7 +402,9 @@ ENVIRONMENT
 
 ]}
 
-{1 odoc compile-deps}
+{1 Scripting}
+
+{2 odoc compile-deps}
 
 {@man[
 NAME
@@ -410,7 +431,7 @@ OPTIONS
 
 ]}
 
-{1 odoc errors}
+{2 odoc errors}
 
 {@man[
 NAME
@@ -434,7 +455,7 @@ OPTIONS
 
 ]}
 
-{1 odoc html-targets}
+{2 odoc html-targets}
 
 {@man[
 NAME
@@ -499,7 +520,7 @@ OPTIONS
 
 ]}
 
-{1 odoc html-url}
+{2 odoc html-url}
 
 {@man[
 NAME
@@ -564,7 +585,7 @@ OPTIONS
 
 ]}
 
-{1 odoc latex-targets}
+{2 odoc latex-targets}
 
 {@man[
 NAME
@@ -599,7 +620,7 @@ OPTIONS
 
 ]}
 
-{1 odoc latex-url}
+{2 odoc latex-url}
 
 {@man[
 NAME
@@ -627,7 +648,7 @@ OPTIONS
 
 ]}
 
-{1 odoc man-targets}
+{2 odoc man-targets}
 
 {@man[
 NAME
@@ -659,7 +680,7 @@ OPTIONS
 
 ]}
 
-{1 odoc support-files-targets}
+{2 odoc support-files-targets}
 
 {@man[
 NAME
@@ -687,7 +708,9 @@ OPTIONS
 
 ]}
 
-{1 odoc compile-targets}
+{1 Legacy pipeline}
+
+{2 odoc compile-targets}
 
 {@man[
 NAME
@@ -720,7 +743,7 @@ OPTIONS
 
 ]}
 
-{1 odoc html}
+{2 odoc html}
 
 {@man[
 NAME
@@ -821,7 +844,7 @@ ENVIRONMENT
 
 ]}
 
-{1 odoc html-fragment}
+{2 odoc html-fragment}
 
 {@man[
 NAME
@@ -883,7 +906,7 @@ ENVIRONMENT
 
 ]}
 
-{1 odoc latex}
+{2 odoc latex}
 
 {@man[
 NAME
@@ -955,7 +978,7 @@ ENVIRONMENT
 
 ]}
 
-{1 odoc link-deps}
+{2 odoc link-deps}
 
 {@man[
 NAME
@@ -982,7 +1005,7 @@ OPTIONS
 
 ]}
 
-{1 odoc man}
+{2 odoc man}
 
 {@man[
 NAME
@@ -1050,7 +1073,9 @@ ENVIRONMENT
 
 ]}
 
-{1 odoc css}
+{1 Deprecated}
+
+{2 odoc css}
 
 {@man[
 NAME
@@ -1078,7 +1103,7 @@ OPTIONS
 
 ]}
 
-{1 odoc html-deps}
+{2 odoc html-deps}
 
 {@man[
 NAME