diff --git a/src/odoc/bin/main.ml b/src/odoc/bin/main.ml
index e237e95ae5..874ffe09a4 100644
--- a/src/odoc/bin/main.ml
+++ b/src/odoc/bin/main.ml
@@ -42,7 +42,7 @@ let docs = "ARGUMENTS"
 
 let odoc_file_directories =
   let doc =
-    "Where to look for required .odoc files. (Can be present several times)."
+    "Where to look for required $(i,.odoc) files. Can be present several times."
   in
   Arg.(
     value
@@ -120,7 +120,7 @@ module Compile : sig
 
   val cmd : unit Term.t
 
-  val info : Term.info
+  val info : docs:string -> Term.info
 end = struct
   let has_page_prefix file =
     file |> Fs.File.basename |> Fs.File.to_string
@@ -173,26 +173,23 @@ end = struct
       ~warnings_options input
 
   let input =
-    let doc = "Input cmti, cmt, cmi or mld file" in
+    let doc = "Input $(i,.cmti), $(i,.cmt), $(i,.cmi) or $(i,.mld) file." in
     Arg.(required & pos 0 (some file) None & info ~doc ~docv:"FILE" [])
 
   let dst =
     let doc =
-      "Output file path. Non-existing intermediate directories are\n\
-      \                 created. If absent outputs a $(i,BASE).odoc file in \
-       the same\n\
-      \                 directory as the input file where $(i,BASE) is the \
-       basename\n\
-      \                 of the input file (for mld files the \"page-\" prefix \
-       will be\n\
-      \                 added if not already present in the input basename)."
+      "Output file path. Non-existing intermediate directories are created. If \
+       absent outputs a $(i,BASE.odoc) file in the same directory as the input \
+       file where $(i,BASE) is the basename of the input file. For mld files \
+       the \"page-\" prefix will be added if not already present in the input \
+       basename."
     in
     Arg.(value & opt (some string) None & info ~docs ~docv:"PATH" ~doc [ "o" ])
 
   let children =
     let doc =
-      "Specify the odoc file as a child. Can be used multiple times. Only \
-       applies to mld files"
+      "Specify the $(i,.odoc) file as a child. Can be used multiple times. \
+       Only applies to mld files"
     in
     let default = [] in
     Arg.(
@@ -200,21 +197,23 @@ end = struct
 
   let cmd =
     let package_opt =
-      let doc = "Package the input is part of (deprecated - use '--parent')" in
+      let doc =
+        "Package the input is part of. Deprecated: use '--parent' instead."
+      in
       Arg.(
         value
         & opt (some string) None
         & info ~docs ~docv:"PKG" ~doc [ "package"; "pkg" ])
     in
     let parent_opt =
-      let doc = "Parent page or subpage" in
+      let doc = "Parent page or subpage." in
       Arg.(
         value
         & opt (some string) None
         & info ~docs ~docv:"PARENT" ~doc [ "parent" ])
     in
     let resolve_fwd_refs =
-      let doc = "Try resolving forward references" in
+      let doc = "Try resolving forward references." in
       Arg.(value & flag & info ~doc [ "r"; "resolve-fwd-refs" ])
     in
     Term.(
@@ -223,9 +222,21 @@ end = struct
        $ package_opt $ parent_opt $ open_modules $ children $ input
        $ warnings_options))
 
-  let info =
-    Term.info "compile"
-      ~doc:"Compile a cmti, cmt, cmi or mld file to an odoc file."
+  let info ~docs =
+    let man =
+      [
+        `S "DEPENDENCIES";
+        `P
+          "Dependencies between compilation units is the same as while \
+           compiling the initial OCaml modules.";
+        `P "Mld pages don't have any dependency.";
+      ]
+    in
+    let doc =
+      "Compile a $(i,.cmti), $(i,.cmt), $(i,.cmi) or $(i,.mld) file to an \
+       $(i,.odoc) file."
+    in
+    Term.info "compile" ~docs ~doc ~man
 end
 
 module Support_files_command = struct
@@ -238,29 +249,29 @@ module Support_files_command = struct
 
   let cmd = Term.(const support_files $ without_theme $ dst ~create:true ())
 
-  let info =
+  let info ~docs =
     let doc =
       "Copy the support files (e.g. default theme, JavaScript files) to the \
        output directory."
     in
-    Term.info ~doc "support-files"
+    Term.info ~docs ~doc "support-files"
 end
 
 module Css = struct
   let cmd = Support_files_command.cmd
 
-  let info =
+  let info ~docs =
     let doc =
-      "DEPRECATED: Use `odoc support-files' to copy the CSS file for the \
+      "DEPRECATED: Use $(i,odoc support-files) to copy the CSS file for the \
        default theme."
     in
-    Term.info ~doc "css"
+    Term.info ~docs ~doc "css"
 end
 
 module Odoc_link : sig
   val cmd : unit Term.t
 
-  val info : Term.info
+  val info : docs:string -> Term.info
 end = struct
   let get_output_file ~output_file ~input =
     match output_file with
@@ -279,23 +290,41 @@ end = struct
 
   let dst =
     let doc =
-      "Output file path. Non-existing intermediate directories are\n\
-      \                 created. If absent outputs a .odocl file in the same\n\
-      \                 directory as the input file."
+      "Output file path. Non-existing intermediate directories are created. If \
+       absent outputs a $(i,.odocl) file in the same directory as the input \
+       file with the same basename."
     in
-    Arg.(value & opt (some string) None & info ~docs ~docv:"PATH" ~doc [ "o" ])
+    Arg.(
+      value
+      & opt (some string) None
+      & info ~docs ~docv:"PATH.odocl" ~doc [ "o" ])
 
   let cmd =
     let input =
       let doc = "Input file" in
-      Arg.(required & pos 0 (some file) None & info ~doc ~docv:"file.odoc" [])
+      Arg.(required & pos 0 (some file) None & info ~doc ~docv:"FILE.odoc" [])
     in
     Term.(
       const handle_error
       $ (const link $ odoc_file_directories $ input $ dst $ warnings_options
        $ open_modules))
 
-  let info = Term.info ~doc:"Link odoc files together" "link"
+  let info ~docs =
+    let man =
+      [
+        `S "DEPENDENCIES";
+        `P
+          "Any link step depends on the result of all the compile results that \
+           could potentially be needed to resolve forward references. A \
+           correct approximation is to start linking only after every compile \
+           steps are done, passing everything that's possible to $(i,-I). Link \
+           steps don't have dependencies between them.";
+      ]
+    in
+    let doc =
+      "Second stage of compilation. Link a $(i,.odoc) into a $(i,.odocl)."
+    in
+    Term.info ~docs ~doc ~man "link"
 end
 
 module type S = sig
@@ -307,15 +336,19 @@ module type S = sig
 end
 
 module Make_renderer (R : S) : sig
-  val process : unit Term.t * Term.info
+  val process : docs:string -> unit Term.t * Term.info
 
-  val targets : unit Term.t * Term.info
+  val targets : docs:string -> unit Term.t * Term.info
 
-  val generate : unit Term.t * Term.info
+  val generate : docs:string -> unit Term.t * Term.info
 end = struct
-  let input =
-    let doc = "Input file" in
-    Arg.(required & pos 0 (some file) None & info ~doc ~docv:"file.odoc" [])
+  let input_odoc =
+    let doc = "Input file." in
+    Arg.(required & pos 0 (some file) None & info ~doc ~docv:"FILE.odoc" [])
+
+  let input_odocl =
+    let doc = "Input file." in
+    Arg.(required & pos 0 (some file) None & info ~doc ~docv:"FILE.odocl" [])
 
   module Process = struct
     let process extra _hidden directories output_dir syntax input_file
@@ -339,16 +372,19 @@ end = struct
       Term.(
         const handle_error
         $ (const process $ R.extra_args $ hidden $ odoc_file_directories
-         $ dst ~create:true () $ syntax $ input $ warnings_options))
+         $ dst ~create:true () $ syntax $ input_odoc $ warnings_options))
 
-    let info =
+    let info ~docs =
       let doc =
-        Format.sprintf "Render %s files from an odoc one" R.renderer.name
+        Format.sprintf
+          "Render %s files from a $(i,.odoc). $(i,link) then $(i,%s-generate) \
+           should be used instead."
+          R.renderer.name R.renderer.name
       in
-      Term.info ~doc R.renderer.name
+      Term.info ~docs ~doc R.renderer.name
   end
 
-  let process = Process.(cmd, info)
+  let process ~docs = Process.(cmd, info ~docs)
 
   module Generate = struct
     let generate extra _hidden output_dir syntax extra_suffix input_file =
@@ -369,16 +405,16 @@ end = struct
       Term.(
         const handle_error
         $ (const generate $ R.extra_args $ hidden $ dst ~create:true () $ syntax
-         $ extra_suffix $ input))
+         $ extra_suffix $ input_odocl))
 
-    let info =
+    let info ~docs =
       let doc =
-        Format.sprintf "Generate %s files from an odocl one" R.renderer.name
+        Format.sprintf "Generate %s files from a $(i,.odocl)." R.renderer.name
       in
-      Term.info ~doc (R.renderer.name ^ "-generate")
+      Term.info ~docs ~doc (R.renderer.name ^ "-generate")
   end
 
-  let generate = Generate.(cmd, info)
+  let generate ~docs = Generate.(cmd, info ~docs)
 
   module Targets = struct
     let list_targets output_dir directories extra odoc_file =
@@ -394,8 +430,8 @@ end = struct
 
     let back_compat =
       let doc =
-        "For backwards compatibility when processing odoc rather than odocl \
-         files."
+        "For backwards compatibility when processing $(i,.odoc) rather than \
+         $(i,.odocl) files."
       in
       Arg.(
         value
@@ -405,18 +441,25 @@ end = struct
     let cmd =
       Term.(
         const handle_error
-        $ (const list_targets $ dst () $ back_compat $ R.extra_args $ input))
+        $ (const list_targets $ dst () $ back_compat $ R.extra_args
+         $ input_odocl))
 
-    let info = Term.info (R.renderer.name ^ "-targets") ~doc:"TODO: Fill in."
+    let info ~docs =
+      let doc =
+        Format.sprintf
+          "Print the files that would be generated by $(i,%s-generate)."
+          R.renderer.name
+      in
+      Term.info (R.renderer.name ^ "-targets") ~docs ~doc
   end
 
-  let targets = Targets.(cmd, info)
+  let targets ~docs = Targets.(cmd, info ~docs)
 end
 
 module Odoc_latex_url : sig
   val cmd : unit Term.t
 
-  val info : Term.info
+  val info : docs:string -> Term.info
 end = struct
   let reference =
     let doc = "The reference to be resolved and whose url to be generated." in
@@ -429,8 +472,8 @@ end = struct
       const handle_error
       $ (const reference_to_url $ odoc_file_directories $ reference))
 
-  let info =
-    Term.info ~doc:"Resolve a reference and output its corresponding url"
+  let info ~docs =
+    Term.info ~docs ~doc:"Resolve a reference and output its corresponding url."
       "latex-url"
 end
 
@@ -440,7 +483,7 @@ module Odoc_html_args = struct
   let renderer = Html_page.renderer
 
   let semantic_uris =
-    let doc = "Generate pretty (semantic) links" in
+    let doc = "Generate pretty (semantic) links." in
     Arg.(value & flag (info ~doc [ "semantic-uris"; "pretty-uris" ]))
 
   let closed_details =
@@ -451,7 +494,7 @@ module Odoc_html_args = struct
     Arg.(value & flag (info ~doc [ "closed-details" ]))
 
   let indent =
-    let doc = "Format the output HTML files with indentation" in
+    let doc = "Format the output HTML files with indentation." in
     Arg.(value & flag (info ~doc [ "indent" ]))
 
   (* Very basic validation and normalization for URI paths. *)
@@ -541,7 +584,7 @@ module Odoc_html = Make_renderer (Odoc_html_args)
 module Odoc_html_url : sig
   val cmd : unit Term.t
 
-  val info : Term.info
+  val info : docs:string -> Term.info
 end = struct
   let root_url =
     let doc =
@@ -562,15 +605,15 @@ end = struct
       $ (const reference_to_url $ Odoc_html_args.extra_args $ root_url
        $ odoc_file_directories $ reference))
 
-  let info =
-    Term.info ~doc:"Resolve a reference and output its corresponding url"
+  let info ~docs =
+    Term.info ~docs ~doc:"Resolve a reference and output its corresponding url."
       "html-url"
 end
 
 module Html_fragment : sig
   val cmd : unit Term.t
 
-  val info : Term.info
+  val info : docs:string -> Term.info
 end = struct
   let html_fragment directories xref_base_uri output_file input_file
       warnings_options =
@@ -590,13 +633,13 @@ end = struct
 
   let cmd =
     let output =
-      let doc = "Output HTML fragment file" in
+      let doc = "Output HTML fragment file." in
       Arg.(
         value & opt string "/dev/stdout"
         & info ~docs ~docv:"file.html" ~doc [ "o"; "output-file" ])
     in
     let input =
-      let doc = "Input documentation page file" in
+      let doc = "Input documentation page file." in
       Arg.(required & pos 0 (some file) None & info ~doc ~docv:"file.mld" [])
     in
     let xref_base_uri =
@@ -611,8 +654,8 @@ end = struct
       $ (const html_fragment $ odoc_file_directories $ xref_base_uri $ output
        $ input $ warnings_options))
 
-  let info =
-    Term.info ~doc:"Generates an html fragment file from an mld one"
+  let info ~docs =
+    Term.info ~docs ~doc:"Generates an html fragment file from an mld one."
       "html-fragment"
 end
 
@@ -630,7 +673,7 @@ module Odoc_latex = Make_renderer (struct
   let renderer = Latex.renderer
 
   let with_children =
-    let doc = "Include children at the end of the page" in
+    let doc = "Include children at the end of the page." in
     Arg.(value & opt bool true & info ~docv:"BOOL" ~doc [ "with-children" ])
 
   let extra_args =
@@ -659,12 +702,14 @@ module Depends = struct
       in
       Term.(const list_dependencies $ input)
 
-    let info =
-      Term.info "compile-deps"
+    let info ~docs =
+      Term.info "compile-deps" ~docs
         ~doc:
           "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."
+           reported in the output.\n\
+           Dependencies between compile steps are the same as when compiling \
+           the ocaml modules."
   end
 
   module Link = struct
@@ -705,11 +750,13 @@ module Depends = struct
       in
       Term.(const handle_error $ (const list_dependencies $ input))
 
-    let info =
-      Term.info "link-deps"
+    let info ~docs =
+      Term.info "link-deps" ~docs
         ~doc:
-          "lists the packages which need to be in odoc's load path to link the \
-           .odoc files in the given directory"
+          "Lists a subset of the packages and modules which need to be in \
+           odoc's load path to link the $(i, odoc) files in the given \
+           directory. Additional packages may be required to resolve all \
+           references."
   end
 
   module Odoc_html = struct
@@ -728,7 +775,8 @@ module Depends = struct
       let cmd _ = Link.list_dependencies in
       Term.(const handle_error $ (const cmd $ includes $ input))
 
-    let info = Term.info "html-deps" ~doc:"DEPRECATED: alias for link-deps"
+    let info ~docs =
+      Term.info "html-deps" ~docs ~doc:"DEPRECATED: alias for link-deps"
   end
 end
 
@@ -742,7 +790,11 @@ module Targets = struct
 
     let cmd = Term.(const list_targets $ Compile.dst $ Compile.input)
 
-    let info = Term.info "compile-targets" ~doc:"TODO: Fill in."
+    let info ~docs =
+      Term.info "compile-targets" ~docs
+        ~doc:
+          "Print the name of the file produced by $(i,compile). If $(i,-o) is \
+           passed, the same path is printed but error checking is performed."
   end
 
   module Support_files = struct
@@ -752,9 +804,10 @@ module Targets = struct
     let cmd =
       Term.(const list_targets $ Support_files_command.without_theme $ dst ())
 
-    let info =
-      Term.info "support-files-targets"
-        ~doc:"Lists the names of the files that 'odoc support-files' outputs."
+    let info ~docs =
+      Term.info "support-files-targets" ~docs
+        ~doc:
+          "Lists the names of the files that $(i,odoc support-files) outputs."
   end
 end
 
@@ -768,42 +821,58 @@ module Odoc_error = struct
     Ok ()
 
   let input =
-    let doc = "Input odoc or odocl file" in
+    let doc = "Input $(i,.odoc) or $(i,.odocl) file" in
     Arg.(required & pos 0 (some file) None & info ~doc ~docv:"FILE" [])
 
   let cmd = Term.(const handle_error $ (const errors $ input))
 
-  let info =
-    Term.info "errors"
-      ~doc:"Print errors that occurred while an .odoc file was generated."
+  let info ~docs =
+    Term.info "errors" ~docs
+      ~doc:"Print errors that occurred while compiling or linking."
 end
 
+let section_pipeline = "COMMANDS: Compilation pipeline"
+let section_generators = "COMMANDS: Alternative generators"
+let section_support = "COMMANDS: Scripting"
+let section_legacy = "COMMANDS: Legacy pipeline"
+let section_deprecated = "COMMANDS: Deprecated"
+
+(** Sections in the order they should appear. *)
+let main_page_sections =
+  [
+    section_pipeline;
+    section_generators;
+    section_support;
+    section_legacy;
+    section_deprecated;
+  ]
+
 let () =
   Printexc.record_backtrace true;
   let subcommands =
     [
-      Compile.(cmd, info);
-      Odoc_html.process;
-      Odoc_html.targets;
-      Odoc_html.generate;
-      Odoc_manpage.process;
-      Odoc_manpage.targets;
-      Odoc_manpage.generate;
-      Odoc_latex.process;
-      Odoc_latex.targets;
-      Odoc_latex.generate;
-      Html_fragment.(cmd, info);
-      Support_files_command.(cmd, info);
-      Css.(cmd, info);
-      Depends.Compile.(cmd, info);
-      Depends.Link.(cmd, info);
-      Depends.Odoc_html.(cmd, info);
-      Targets.Compile.(cmd, info);
-      Targets.Support_files.(cmd, info);
-      Odoc_link.(cmd, info);
-      Odoc_error.(cmd, info);
-      Odoc_html_url.(cmd, info);
-      Odoc_latex_url.(cmd, info);
+      Compile.(cmd, info ~docs:section_pipeline);
+      Odoc_link.(cmd, info ~docs:section_pipeline);
+      Odoc_html.generate ~docs:section_pipeline;
+      Support_files_command.(cmd, info ~docs:section_pipeline);
+      Odoc_manpage.generate ~docs:section_generators;
+      Odoc_latex.generate ~docs:section_generators;
+      Odoc_html_url.(cmd, info ~docs:section_support);
+      Odoc_latex_url.(cmd, info ~docs:section_support);
+      Targets.Support_files.(cmd, info ~docs:section_support);
+      Odoc_error.(cmd, info ~docs:section_support);
+      Odoc_html.targets ~docs:section_support;
+      Odoc_manpage.targets ~docs:section_support;
+      Odoc_latex.targets ~docs:section_support;
+      Depends.Compile.(cmd, info ~docs:section_support);
+      Targets.Compile.(cmd, info ~docs:section_support);
+      Html_fragment.(cmd, info ~docs:section_legacy);
+      Odoc_html.process ~docs:section_legacy;
+      Odoc_manpage.process ~docs:section_legacy;
+      Odoc_latex.process ~docs:section_legacy;
+      Depends.Link.(cmd, info ~docs:section_legacy);
+      Css.(cmd, info ~docs:section_deprecated);
+      Depends.Odoc_html.(cmd, info ~docs:section_deprecated);
     ]
   in
   let default =
@@ -815,8 +884,12 @@ let () =
         "Available subcommands: %s\nSee --help for more information.\n%!"
         (String.concat ~sep:", " available_subcommands)
     in
+    let man =
+      (* Show sections in a defined order. *)
+      List.map ~f:(fun s -> `S s) main_page_sections
+    in
     ( Term.(const print_default $ const ()),
-      Term.info ~version:"%%VERSION%%" "odoc" )
+      Term.info ~man ~version:"%%VERSION%%" "odoc" )
   in
   match Term.eval_choice ~err:Format.err_formatter default subcommands with
   | `Error _ ->