Sort whatis references below real pages more aggressively

I think this makes more sense in most cases, and it definitely fixes
some observed odd behaviour.

Fixes Debian bug #780235.

* src/man.c (compare_candidates): Compare IDs before comparing sections.
* NEWS.md: Document this.

2 files changed, 11 insertions, 10 deletions

diff --git a/NEWS.md b/NEWS.md
index 5ecb87d4..c75746c3 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -7,6 +7,8 @@ Fixes:
    prompts.  Note that this requires `less` >= 457 (released in 2012).
  * Silence error message when processing an empty manual page hierarchy with
    a nonexistent cache directory.
+ * `man(1)` now sorts whatis references below real pages, even if the whatis
+   references are from a section with higher priority.
 
 Improvements:
 
diff --git a/src/man.c b/src/man.c
index 7bf1dd34..64417f9e 100644
--- a/src/man.c
+++ b/src/man.c
@@ -2792,11 +2792,15 @@ static int compare_candidates (const struct candidate *left,
 			return 1;
 	}
 
-	/* Compare pure sections first, then ids, then extensions.
-	 * Rationale: whatis refs get the same section and extension as
-	 * their source, but may be supplanted by a real page with a
-	 * slightly different extension, possibly in another hierarchy (!);
-	 * see Debian bug #204249 for the gory details.
+	/* ULT_MAN comes first, etc.  Consider SO_MAN equivalent to ULT_MAN.
+	 * This has the effect of sorting mere whatis references below real
+	 * pages.
+	 */
+	cmp = compare_ids (lsource->id, rsource->id, true);
+	if (cmp)
+		return cmp;
+
+	/* Compare pure sections first, then extensions.
 	 *
 	 * Any extension spelt out in full in section_list effectively
 	 * becomes a pure section; this allows extensions to be selectively
@@ -2849,11 +2853,6 @@ static int compare_candidates (const struct candidate *left,
 			return cmp;
 	}
 
-	/* ULT_MAN comes first, etc. Consider SO_MAN equivalent to ULT_MAN. */
-	cmp = compare_ids (lsource->id, rsource->id, true);
-	if (cmp)
-		return cmp;
-
 	/* The order in section_list has already been compared above. For
 	 * everything not mentioned explicitly there, we just compare
 	 * lexically.