ITS#7523 document the valsort control's value syntax

Not really sure that we like this syntax, but it's been there
for 8 years now so unlikely to change.

diff --git a/doc/man/man5/slapo-valsort.5 b/doc/man/man5/slapo-valsort.5
index 2406046aa2174e9d85c7420f505556f6c2432b5b..408825874739f70709e636797b5ee530e00d6cf3 100644 (file)
--- a/doc/man/man5/slapo-valsort.5
+++ b/doc/man/man5/slapo-valsort.5
@@ -21,6 +21,11 @@ in front of each value of the attribute for which weighted sorting is
 desired. This weighting factor is stripped off and not returned in search
 results unless the valsort control is specified (1.3.6.1.4.1.4203.666.5.14).
 
+The valsort control requires a value consisting of a Sequence that contains
+a boolean flag. The weighting factor is only returned if the boolean value is TRUE. In
+.BR lber-encode (3)
+format, the required value must conform to "{b}" syntax.
+
 .SH CONFIGURATION
 These
 .I slapd.conf
@@ -63,6 +68,22 @@ for an attribute with a syntax other than Integer or NumericString.
        valsort\-attr member ou=groups,dc=example,dc=com alpha\-ascend
 .fi
 
+To invoke
+.BR ldapsearch (1)
+with the valsort control, the control value must be set appropriately.
+The following octets represent the desired "{b}" encoding:
+.LP
+.nf
+       0x30 0x03 0x01 0x01 0xff
+.fi
+
+The control can be sent from the command-line using the base64
+encoding of the value:
+.LP
+.nf
+       ldapsearch -E 1.3.6.1.4.1.4203.666.5.14=::MAMBAf8=
+.fi
+
 .SH FILES
 .TP
 \fIETCDIR/slapd.conf\fP