From 503104cd0cddc7a93a17fc7fed90af37d00e87b8 Mon Sep 17 00:00:00 2001
From: Mathieu Arnold <mat@FreeBSD.org>
Date: Tue, 8 Nov 2016 17:48:47 +0000
Subject: [PATCH] Add hints on how to add and sort man-ref entries.

Sponsored by:	Absolight
---
 share/xml/man-refs.ent | 3 +++
 share/xml/man-refs.pl  | 8 ++++++++
 2 files changed, 11 insertions(+)

diff --git a/share/xml/man-refs.ent b/share/xml/man-refs.ent
index 8d81bf5038..db053e93ac 100644
--- a/share/xml/man-refs.ent
+++ b/share/xml/man-refs.ent
@@ -21,6 +21,9 @@
      lexicographical order by the entity (i.e., the dots used in place of
      special characters should not be expanded when comparing).
 
+     This can be used to sort a section:
+     sed -E 's,.*refentrytitle>(.*)</refentrytit.*,\1 &,' | env LANG=C sort -u -k 1,1 | sed -Ee 's,[^ ]* [^ ]* ,,'
+
      $FreeBSD$
 -->
 
diff --git a/share/xml/man-refs.pl b/share/xml/man-refs.pl
index 28eeffbc36..ca1b7ec394 100644
--- a/share/xml/man-refs.pl
+++ b/share/xml/man-refs.pl
@@ -1,5 +1,13 @@
 #!/usr/bin/perl -w
 # $FreeBSD$
+#
+# To get the entities sorted the same way as the current man-refs.ent file is, this command can be used:
+#
+# find -s /usr/share/man/ -name '*.gz' | \
+#   sed -Ee 's,.*([[:digit:]])/(.*)\.[^.]+\.gz,\1 \2 &,' | \
+#   env LANG=C sort -k 1,1n -k 2,2 | \
+#   sed -e 's/.* //' | \
+#   perl share/xml/man-refs.pl
 
 use strict;