Re: (ITS#4590) fix ldap_abandon{,ext} man page to match current reality

[Kurt@OpenLDAP.org]

Regarding patches, per our contributing guidelines, all contributions
must be submitted via the issue tracking system.  Patches sent by
other means (personal email, OpenLDAP-devel submission, etc.) will
be considered providing for discussion purposes only.

As Ando noted, providing them by reference (e.g., URL) is preferred
over pasting into the ITS-web or ITS-email interface.  There are
also other considerations.  See
http://www.openldap.org/devel/contributing.html for details.

As noted in those guidelines, separate reports should be made
for separate issues.  A patch should cover changes only for a
particular issue.  It fine for the patch to cover multiple
files, assuming the patch addresses the same issue in all
files.  Patches that attempt to address multiple issues need
to be split out by issue (not by file).

Beyond this, I note that I have applied some additional changes
to ldap_abandon(3).

You'll note that I eliminated the ERRORS section.  I did so
as this section, when provided, should discuss the specific
error conditions in the interface(s).  A basic description
of the return value belongs in the DESCRIPTION section.

I didn't add the verbosity you suggested.   I am not sure it's
actually useful.  If the reader doesn't know what code indicates
success, they really ought to read ldap_error(3).

I didn't apply the NULL change as, IIRC, NULL doesn't mean use
no controls, it means use default controls.  To use no use no
controls, one has to pass a pointer to a NULL.  While we
could work out some text (which could be shared across multiple
pages via a .so) that discusses c/s control semantics, or
reference a yet to be written separate page discussing control
semantics, I rather we separately tackle this (e.g., separate
issue).

I'd prefer we, at least initially, focused on addressing
your initial post - providing (basic) documentation for
non-deprecated routines.

Regardless, I very much appreciate your documentation
contributions and am quite willing to consider all you choose
to offer.

Regards, Kurt

PS: please make sure that <openldap-its@openldap.org address
is copied on every message discussing an ITS so we have a
complete track on the issue.

At 12:26 PM 6/15/2006, fenlason@redhat.com wrote:
>Here's a small patch to add a bit more useful verbosity to the
>ldap_abandon man page.
>
>For additional man pages, should I open new bug reports for each, mail
>you the diffs, or something else?
>
>                        -- JF
>
>Index: ldap_abandon.3
>===================================================================
>RCS file: /repo/OpenLDAP/pkg/ldap/doc/man/man3/ldap_abandon.3,v
>retrieving revision 1.23
>diff -u -r1.23 ldap_abandon.3
>--- ldap_abandon.3      13 Jun 2006 22:19:32 -0000      1.23
>+++ ldap_abandon.3      15 Jun 2006 19:16:24 -0000
>@@ -43,11 +43,12 @@
> .I sctrls
> and
> .I cctrls
>-parameters, respectively.
>+parameters, respectively.  Either controls paramater may be NULL if no
>+controls of that type are needed.
> .SH ERRORS
> .B ldap_abandon_ext()
>-returns an LDAP error code indicating success or failure in sending
>-the Abandon request.
>+returns an LDAP error code indicating success (LDAP_SUCCESS) or failure
>+in sending the Abandon request.
> .LP
> See
> .BR ldap_error (3)
>@@ -57,7 +58,8 @@
> .B ldap_abandon()
> routine is deprecated in favor of the
> .B ldap_abandon_ext()
>-routine. 
>+routine.  It did not have the controls paramaters, and returned a simple
>+0/-1 on success/failure.
> .LP
> .so Deprecated
>