fix(clap_mangen): Take into consideration display_order

In #3362 we have an issue where when we configure an arg via
.display_order(int), and then generate a manpage,
the synposis and options will render the order the args were
provided to the App rather than the order they were configured

e.g

Command::new(name)
arg(Arg::new("few").short('b').display_order(2))
arg(Arg::new("bar").short('a').display_order(1))

will show

...
SYNOPSIS
    <name> [-b] [-a] ...

...
OPTIONS
    -b
    -a

instead of

...
SYNOPSIS
    <name> [-a] [-b] ...

...
OPTIONS
    -a
    -b

and so on. This fix adds sorting in the synopsis and
options functions responsible for generating the
corresponding synopsis and options sections of the manpage.

Author: Eric Gumba

clap_mangen/src/render.rs

@@ -33,7 +33,11 @@ pub(crate) fn synopsis(roff: &mut Roff, cmd: &clap::Command) {
     let name = cmd.get_bin_name().unwrap_or_else(|| cmd.get_name());
     let mut line = vec![bold(name), roman(" ")];
 
-    for opt in cmd.get_arguments().filter(|i| !i.is_hide_set()) {
+    let mut opts: Vec<_> = cmd.get_arguments().filter(|i| !i.is_hide_set()).collect();
+
+    opts.sort_by_key(|opt| option_sort_key(opt));
+
+    for opt in opts {
         let (lhs, rhs) = option_markers(opt);
         match (opt.get_short(), opt.get_long()) {
             (Some(short), Some(long)) => {
@@ -89,7 +93,10 @@ pub(crate) fn synopsis(roff: &mut Roff, cmd: &clap::Command) {
 }
 
 pub(crate) fn options(roff: &mut Roff, items: &[&Arg]) {
-    for opt in items.iter().filter(|a| !a.is_positional()) {
+    let mut sorted_items = items.to_vec();
+    sorted_items.sort_by_key(|opt| option_sort_key(opt));
+
+    for opt in sorted_items.iter().filter(|a| !a.is_positional()) {
         let mut header = match (opt.get_short(), opt.get_long()) {
             (Some(short), Some(long)) => {
                 vec![short_option(short), roman(", "), long_option(long)]
@@ -217,7 +224,10 @@ fn possible_options(roff: &mut Roff, arg: &Arg, arg_help_written: bool) {
 }
 
 pub(crate) fn subcommands(roff: &mut Roff, cmd: &clap::Command, section: &str) {
-    for sub in cmd.get_subcommands().filter(|s| !s.is_hide_set()) {
+    let mut sorted_subcommands: Vec<_> =
+        cmd.get_subcommands().filter(|s| !s.is_hide_set()).collect();
+    sorted_subcommands.sort_by_key(|c| subcommand_sort_key(c));
+    for sub in sorted_subcommands {
         roff.control("TP", []);
 
         let name = format!(
@@ -378,3 +388,23 @@ fn format_possible_values(possibles: &Vec<&clap::builder::PossibleValue>) -> (Ve
     }
     (lines, with_help)
 }
+
+fn subcommand_sort_key(command: &clap::Command) -> (usize, &str) {
+    (command.get_display_order(), command.get_name())
+}
+
+/// Note that this function is duplicated from `clap::builder`
+fn option_sort_key(arg: &Arg) -> (usize, String) {
+    let key = if let Some(x) = arg.get_short() {
+        let mut s = x.to_ascii_lowercase().to_string();
+        s.push(if x.is_ascii_lowercase() { '0' } else { '1' });
+        s
+    } else if let Some(x) = arg.get_long() {
+        x.to_string()
+    } else {
+        let mut s = '{'.to_string();
+        s.push_str(arg.get_id().as_str());
+        s
+    };
+    (arg.get_display_order(), key)
+}

clap_mangen/tests/snapshots/configured_display_order_args.roff

@@ -4,22 +4,22 @@
 .SH NAME
 my\-app
 .SH SYNOPSIS
-\fBmy\-app\fR [\fB\-Q\fR|\fB\-\-third\fR] [\fB\-\-fourth\fR] [\fB\-O\fR|\fB\-\-first\fR] [\fB\-P\fR|\fB\-\-second\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fI1st\fR] [\fI2nd\fR] [\fI3rd\fR] 
+\fBmy\-app\fR [\fB\-O\fR|\fB\-\-first\fR] [\fB\-P\fR|\fB\-\-second\fR] [\fB\-Q\fR|\fB\-\-third\fR] [\fB\-\-fourth\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fI1st\fR] [\fI2nd\fR] [\fI3rd\fR] 
 .SH DESCRIPTION
 .SH OPTIONS
 .TP
-\fB\-Q\fR, \fB\-\-third\fR
-Should be 3rd
-.TP
-\fB\-\-fourth\fR
-Should be 4th
-.TP
 \fB\-O\fR, \fB\-\-first\fR
 Should be 1st
 .TP
 \fB\-P\fR, \fB\-\-second\fR
 Should be 2nd
 .TP
+\fB\-Q\fR, \fB\-\-third\fR
+Should be 3rd
+.TP
+\fB\-\-fourth\fR
+Should be 4th
+.TP
 \fB\-h\fR, \fB\-\-help\fR
 Print help
 .TP

clap_mangen/tests/snapshots/configured_subcmd_order.roff

@@ -15,12 +15,12 @@ Print help
 Print version
 .SH SUBCOMMANDS
 .TP
-my\-app\-b1(1)
-blah b1
-.TP
 my\-app\-a1(1)
 blah a1
 .TP
+my\-app\-b1(1)
+blah b1
+.TP
 my\-app\-help(1)
 Print this message or the help of the given subcommand(s)
 .SH VERSION

clap_mangen/tests/testsuite/roff.rs

@@ -170,8 +170,8 @@ fn configured_display_order_args() {
     let ordered_keywords = ["first", "second", "third", "fourth", "1st", "2nd", "3rd"];
     let default_ordered_keywords = ["third", "fourth", "first", "second", "1st", "2nd", "3rd"];
 
-    assert!(!common::is_correct_ordering(&ordered_keywords, &s));
-    assert!(common::is_correct_ordering(&default_ordered_keywords, &s));
+    assert!(common::is_correct_ordering(&ordered_keywords, &s));
+    assert!(!common::is_correct_ordering(&default_ordered_keywords, &s));
 
     common::assert_matches(
         snapbox::file!["../snapshots/configured_display_order_args.roff"],
@@ -189,8 +189,8 @@ fn configured_subcmd_order() {
     let ordered_keywords = ["a1", "b1"];
     let default_ordered_keywords = ["b1", "a1"];
 
-    assert!(!common::is_correct_ordering(&ordered_keywords, &s));
-    assert!(common::is_correct_ordering(&default_ordered_keywords, &s));
+    assert!(common::is_correct_ordering(&ordered_keywords, &s));
+    assert!(!common::is_correct_ordering(&default_ordered_keywords, &s));
 
     common::assert_matches(
         snapbox::file!["../snapshots/configured_subcmd_order.roff"],