revise manpage sections

[hannesm]

as proposed in #1530

[reynir]

I tested this with unipi (see robur-coop/unipi#29) and I had to pass ~docs:Mirage_runtime.s_args to Cmdliner.Arg.info (which can be done once by defining a local function let info ?(docs = Mirage_runtime.s_args) = Cmdliner.Arg.info). Otherwise by default arguments end up in the OPTIONS section near the bottom right before COMMON OPTIONS. The sections are not completely sorted in reverse alphabetic order somehow.

[hannesm]

The reverse lexical ordering is for unknown sections -- where name, synopsis, description, commands, arguments, options, common options, exit codes, bugs, .. are known (and have a hardcoded ordering in cmdliner) -- and here the unknown ones are interjected in reverse lexical order after description.

[reynir]

I discovered we can control the order of the sections by specifying them in the desired order in the man page:

diff --git a/lib_runtime/functoria/functoria_runtime.ml b/lib_runtime/functoria/functoria_runtime.ml
index 1a162759..5b49f934 100644
--- a/lib_runtime/functoria/functoria_runtime.ml
+++ b/lib_runtime/functoria/functoria_runtime.ml
@@ -48,7 +48,7 @@ let initialized = ref false
 let help_version = 63
 let argument_error = 64
 
-let with_argv keys s argv =
+let with_argv sections keys s argv =
   let open Cmdliner in
   if !initialized then ()
   else
@@ -68,7 +68,8 @@ let with_argv keys s argv =
         Cmd.Exit.info ~doc:"on OCaml uncaught exception." 255;
       ]
     in
-    match Cmd.(eval_value ~argv (Cmd.v (info ~exits s) t)) with
+    let man = List.map (fun s -> `S s) sections in
+    match Cmd.(eval_value ~argv (Cmd.v (info ~man ~exits s) t)) with
     | Ok (`Ok _) ->
         initialized := true;
         ()
diff --git a/lib_runtime/functoria/functoria_runtime.mli b/lib_runtime/functoria/functoria_runtime.mli
index bbee324f..6ae7611a 100644
--- a/lib_runtime/functoria/functoria_runtime.mli
+++ b/lib_runtime/functoria/functoria_runtime.mli
@@ -41,7 +41,7 @@ val register : 'a Cmdliner.Term.t -> unit -> 'a
 
     [f] will raise [Invalid_argument] if called before cmdliner's evaluation. *)
 
-val with_argv : unit Cmdliner.Term.t list -> string -> string array -> unit
+val with_argv : string list -> unit Cmdliner.Term.t list -> string -> string array -> unit
 (** [with_argv keys name argv] evaluates the [keys] {{!Key.term} terms} on the
     command-line [argv]. [name] is the executable name. On evaluation error the
     application calls [exit(3)] with status [64]. If [`Help] or [`Version] were
diff --git a/lib_runtime/mirage_runtime.ml b/lib_runtime/mirage_runtime.ml
index a7f316ff..07736166 100644
--- a/lib_runtime/mirage_runtime.ml
+++ b/lib_runtime/mirage_runtime.ml
@@ -16,11 +16,11 @@
 
 open Cmdliner
 
-let s_ocaml = "COMMON OCAML RUNTIME OPTIONS"
+let s_ocaml = "OCAML RUNTIME OPTIONS"
 let s_log = "LOG AND MONITORING OPTIONS"
 let s_net = "NETWORK OPTIONS"
 let s_disk = "DISK OPTIONS"
-let s_arg = "UNIKERNEL ARGUMENTS"
+let s_arg = "ARGUMENTS"
 
 type log_threshold = [ `All | `Src of string ] * Logs.level option
 
@@ -249,7 +249,7 @@ let run_leave_iter_hooks () = run leave_iter_hooks
 let at_exit f = add f exit_hooks
 let at_leave_iter f = add f leave_iter_hooks
 let at_enter_iter f = add f enter_iter_hooks
-let with_argv = Functoria_runtime.with_argv
+let with_argv = Functoria_runtime.with_argv [ s_arg; s_net; s_log; s_disk; s_ocaml ]
 let runtime_args = Functoria_runtime.runtime_args
 let register = Functoria_runtime.register
 let argument_error = Functoria_runtime.argument_error

[hannesm]

oh nice, @reynir -- would you mind to push that change to this PR?

[hannesm]

-val with_argv : unit Cmdliner.Term.t list -> string -> string array -> unit
+val with_argv : string list -> unit Cmdliner.Term.t list -> string -> string array -> unit
 (** [with_argv keys name argv] evaluates the [keys] {{!Key.term} terms} on the

We should describe the new input (and make it an optional argument)!?

[reynir]

Please see latest commit. I didn't revert the change of section names, but maybe we should? I don't have any opinions on that.

[hannesm]

So, people will forget to use s_arg (which actually we don't need to redefine, we can just use Cmdliner.Manpage.s_arguments).

I propose to make the sections ARGUMENTS OPTTIONS and then our mirage-custom ones. The reasoning is that people will forget, and should nevertheless see their stuff on the top. WDYT?

[hannesm]

I tested this with the above linked unipi PR, and to me this is a great improvement.

Especially that the default section for optional arguments and required arguments (if you do not specify ~docs in your Cmdliner.Arg.info) are shown at the top in the manpage -- so users won't need to search for these.

Any other opinions?

[samoht]

Looks great, thanks!