Update ldap_abandon(3) as example as to how to document

non-deprecated v. deprecated interfaces.

doc/man/man3/deprecated

@@ -0,0 +1,8 @@
+While deprecated,
+these interfaces generally remain in the library.  The macro
+LDAP_DEPRECATED can be defined to a non-zero value
+(e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use
+deprecated interaces.  It is recommended that developers writing new
+programs, or updating old programs, avoid use of deprecated interfaces.
+Over time, it is expected that documentation (and, eventually, support) for
+deprecated interfaces to be eliminated.

doc/man/man3/ldap.3

@@ -114,14 +114,8 @@ routines are used to sort the entries and values returned via
 the ldap search routines. 
 .SH DEPRECATED INTERFACES
 A number of interfaces are now considered deprecated.  For instance,
-ldap_add(3) is deprecated in favor of ldap_add_ext(3).  While deprecated,
-these interfaces generally remain in the library.  The macro
-LDAP_DEPRECATED can be defined to a non-zero value
-(e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use
-deprecated interaces.  It is recommended that developers writing new
-programs, or updating old programs, avoid use of deprecated interfaces.
-Over time, it is expected that documentation (and, eventually, support) for
-deprecated interfaces to be eliminated.
+ldap_add(3) is deprecated in favor of ldap_add_ext(3).
+.so deprecated
 .SH BER LIBRARY
 Also included in the distribution is a set of lightweight Basic
 Encoding Rules routines.  These routines are used by the LDAP library

doc/man/man3/ldap_abandon.3

@@ -3,15 +3,12 @@
 .\" Copyright 1998-2006 The OpenLDAP Foundation All Rights Reserved.
 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
 .SH NAME
-ldap_abandon, ldap_abandon_ext \- Abandon an LDAP operation in progress
+ldap_abandon_ext \- Abandon an LDAP operation in progress
 .SH LIBRARY
 OpenLDAP LDAP (libldap, -lldap)
 .SH SYNOPSIS
 .nf
 .B #include <ldap.h>
-.sp
-.BI "int ldap_abandon(LDAP *" ld ", int " msgid ");"
-.sp
 .BI "int ldap_abandon_ext(LDAP *" ld ", int " msgid ","
 .RS
 .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]);"
@@ -19,15 +16,15 @@ OpenLDAP LDAP (libldap, -lldap)
 .fi
 .SH DESCRIPTION
 The
-.B ldap_abandon()
+.B ldap_abandon_ext()
 routine is used to abandon or cancel an LDAP
 operation in progress.  The \fImsgid\fP passed should be the
 message id of an outstanding LDAP operation, as returned by
-.BR ldap_search (3),
-.BR ldap_modify (3),
+.BR ldap_search_ext (3),
+.BR ldap_modify_ext (3),
 etc.
 .LP
-.BR ldap_abandon ()
+.BR ldap_abandon_ext ()
 checks to see if the result of the operation has already come in.  If it
 has, it deletes it from the queue of pending messages.  If not,
 it sends an LDAP abandon operation to the the LDAP server.
@@ -37,19 +34,12 @@ will not be returned from a future call to
 .BR ldap_result (3).
 .LP
 .B ldap_abandon_ext()
-is equivalent to
-.B ldap_abandon()
-except that it allows server and client controls to be passed
-in
+allows server and client controls to be passed in via the
 .I sctrls
 and
-.IR cctrls ,
-respectively.
+.I cctrls
+parameters, respectively.
 .SH ERRORS
-.B ldap_abandon()
-returns 0 if everything goes ok, -1 otherwise,
-setting \fIld_errno\fP with an appropriate LDAP error code.
-.LP
 .B ldap_abandon_ext()
 directly returns an LDAP error code indicating success or failure of the
 operation.
@@ -57,6 +47,23 @@ operation.
 See
 .BR ldap_error (3)
 for details.
+.SH DEPRECATED INTERFACES
+The
+.B ldap_abandon()
+routine is deprecated in favor of the
+.B ldap_abandon_ext()
+routine. 
+.LP
+.so deprecated
+While deprecated,
+these interfaces generally remain in the library.  The macro
+LDAP_DEPRECATED can be defined to a non-zero value
+(e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use
+deprecated interaces.  It is recommended that developers writing new
+programs, or updating old programs, avoid use of deprecated interfaces.
+Over time, it is expected that documentation (and, eventually, support) for
+deprecated interfaces to be eliminated.
+
 .SH SEE ALSO
 .BR ldap (3),
 .BR ldap_result (3),