fix(clap_mangen): Mangen should 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,14 @@ 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| opt.get_display_order());
+
+    for opt in opts {
         let (lhs, rhs) = option_markers(opt);
         match (opt.get_short(), opt.get_long()) {
             (Some(short), Some(long)) => {
@@ -89,7 +96,11 @@ 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| opt.get_display_order());
+
+    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)]
@@ -131,7 +142,7 @@ pub(crate) fn options(roff: &mut Roff, items: &[&Arg]) {
         }
     }
 
-    for pos in items.iter().filter(|a| a.is_positional()) {
+    for pos in sorted_items.iter().filter(|a| a.is_positional()) {
         let mut header = vec![];
         let (lhs, rhs) = option_markers(pos);
         header.push(roman(lhs));