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

non-deprecated v. deprecated interfaces.

diff --git a/doc/man/man3/deprecated b/doc/man/man3/deprecated
new file mode 100644 (file)
index 0000000..c4347ab
--- /dev/null
+++ b/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.

diff --git a/doc/man/man3/ldap.3 b/doc/man/man3/ldap.3
index 57a6f8be4e940b46bafeea41a749ec879f647ab9..b2aed2a629da9b10cf497c3ad63d1b03de846ecb 100644 (file)
--- a/doc/man/man3/ldap.3
+++ b/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

diff --git a/doc/man/man3/ldap_abandon.3 b/doc/man/man3/ldap_abandon.3
index a2327ea0e006b79010247439662fc16eeeef05cc..02bd5df2d6a9e9de6b159715e561faad6c0986d2 100644 (file)
--- a/doc/man/man3/ldap_abandon.3
+++ b/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),