Add two scripts that manipulate man-refs.ent. add-manref.sh inserts a

new man page entity with the right format into the right place.
Revs. 1.82-1.84 of man-refs.ent are a good, although perhaps extreme,
example of what this is trying to prevent.  check-manref.sh makes sure
that the entities in man-refs.ent are in the right order, which is
necessary for add-manref.sh to work properly.

share/examples/add-manref.sh

@@ -0,0 +1,92 @@
+#!/bin/sh
+#
+# Script to properly insert an entry into the man-refs.ent file.
+# Originally by Dima Dorfman, public domain, 2001.
+#
+# This makes *a lot* of assumptions about the format; particularly it
+# requires that all man pages in a section are in one contiguous
+# block, and that everything is sorted alphabetically within the
+# aforementioned block.  This will edit the file in place, but will
+# not commit it; since it doesn't do a good job of handling corner
+# cases, the user should review its work before committing its
+# changes.
+#
+# This is also very ugly, but that's the price of not having Tcl in
+# the base system!
+#
+# Tested with doc/share/sgml/man-refs.ent rev. 1.85 (dd, 2001/06/30).
+#
+# Exit codes: 0- added; 1- exists; 2- something else;
+#
+# $FreeBSD$
+#
+
+# Input: $wol_l - line
+# Output: $wol_w - word
+word_on_line () {
+    wol_w=`grep -n . $i | grep "^${wol_l}:" | \
+	sed -E 's/^[[:digit:]]*:<\\!ENTITY man[.]([-[:alnum:].]*)[.][[:digit:]]* \".*$$/\1/'`;
+}
+
+if [ X$3 = X ]; then
+    echo "usage: $0 file name section";
+    exit 2;
+fi
+
+i=$1;
+n=$2;
+s=$3;
+k=`echo $n | sed 's/_/./g'`;
+
+firstline=`grep -n "^<\\!ENTITY man[.][-[:alnum:].]*[.]$s \"" $i | \
+    head -1 | cut -d: -f1`;
+if [ "X$firstline" = "X" ]; then
+    echo "Can't find first line of section $s.";
+    exit 2;
+fi
+echo "First line of section $s is $firstline.";
+lastline=`grep -n "^<\\!ENTITY man[.][-[:alnum:].]*[.]$s \"" $i | \
+    tail -1 | cut -d: -f1`;
+if [ "X$lastline" = "X" ]; then
+    echo "Can't find last line of section $s.";
+    exit 2;
+fi
+echo "Last line of section $s is $lastline.";
+
+l=$firstline;
+u=$lastline;
+while [ $u -ge $l ]; do
+    r=`expr $l + $u`;
+    m=`expr $r / 2`;
+    wol_l=$m;
+    word_on_line;
+    km=$wol_w;
+    if [ "$k" = "$km" ]; then
+	echo "$n($s) already exists; line $m";
+	exit 1;
+    elif [ "$k" '<' "$km" ]; then
+	u=`expr $m - 1`;
+    elif [ "$k" '>' "$km" ]; then
+	l=`expr $m + 1`;
+    else
+	echo "Thou shalt not defy the laws of mathematics!";
+	echo "Thou shalt not make silly bugs in thy shell scripts!";
+	exit 2;
+    fi
+done;
+
+t="<!ENTITY man.$k.$s \"<citerefentry/<refentrytitle/$n/<manvolnum/$s//\">";
+echo "Inserting line $l:";
+echo $t;
+echo -n "Last chance to interrupt (or press enter to continue)> ";
+read okay;
+ed -s $i <<EOF
+${l}i
+$t
+.
+w
+q
+EOF
+
+echo "All done!";
+exit 0;

share/examples/check-manref.sh

@@ -0,0 +1,71 @@
+#!/bin/sh
+#
+# Script to assert that the man-refs.ent file is in lexicographical
+# order by section number then by name.  Originally by Dima Dorfman,
+# public domain, 2001.
+#
+# This assumes that all the man pages for one section are in one
+# contiguous block.  It will scan the block and make sure that the man
+# pages are in lexicographical order.  Note that it only looks at the
+# man page entity, not the name, so the dots (.) used in place of
+# special characters (e.g., "_", "[") won't get expanded.  It will not
+# edit the file in place; only alert the operator to the discrepancy.
+# Furthermore, once it found something wrong, it will stop, so it may
+# be necessary to run it more than once per section to make sure
+# everything is clean.
+#
+# Used to create doc/share/sgml/man-refs.ent rev. 1.85 (dd, 2001/06/30).
+#
+# Exit codes: 0- okay; 1- something out of order; 2- something else;
+#
+# $FreeBSD$
+#
+
+# Input: $wol_l - line
+# Output: $wol_w - word
+word_on_line () {
+    wol_w=`grep -n . $i | grep "^${wol_l}:" | \
+	sed -E 's/^[[:digit:]]*:<\\!ENTITY man[.]([-[:alnum:].]*)[.][[:digit:]]* \".*$$/\1/'`;
+}
+
+if [ X$2 = X ]; then
+    echo "usage: $0 file section";
+    exit 2;
+fi
+
+i=$1;
+s=$2;
+
+firstline=`grep -n "^<\\!ENTITY man[.][-[:alnum:].]*[.]$s \"" $i | \
+    head -1 | cut -d: -f1`;
+if [ "X$firstline" = "X" ]; then
+    echo "Can't find first line of section $s.";
+    exit 2;
+fi
+echo "First line of section $s is $firstline.";
+lastline=`grep -n "^<\\!ENTITY man[.][-[:alnum:].]*[.]$s \"" $i | \
+    tail -1 | cut -d: -f1`;
+if [ "X$lastline" = "X" ]; then
+    echo "Can't find last line of section $s.";
+    exit 2;
+fi
+echo "Last line of section $s is $lastline.";
+
+x=$firstline;
+while [ $x != $lastline ]; do
+    wol_l=$x;
+    word_on_line;
+    if [ "$last" ]; then
+	if [ "$last" = "$wol_w" ]; then
+	    echo "Duplicate \"$last\" (l. $x).";
+	    exit 1;
+	elif [ "$last" '>' "$wol_w" ]; then
+	    echo "Out of order: \"$wol_w\" after \"$last\" (l. $x).";
+	    exit 1;
+	fi
+    fi
+    last=$wol_w;
+    x=`expr $x + 1`;
+done;
+
+exit 0;