[src/trunk]: src/lib/libc/iconv Rework the description of the const issue to ...

[dholland <dholland%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/c52d5d6f4427
branches:  trunk
changeset: 783788:c52d5d6f4427
user:      dholland <dholland%NetBSD.org@localhost>
date:      Tue Jan 08 19:19:24 2013 +0000

description:
Rework the description of the const issue to improve the wording,
avoid saying "we", fix typos, etc.

XXX: groff and mandoc handle the URLs in here differently but both
XXX: mangle them, apparently because they're wider than one line.
XXX: Does anyone know how to fix this or do we need an URL shortener
XXX: on www.NetBSD.org?

diffstat:

 lib/libc/iconv/iconv.3 |  46 ++++++++++++++++++++++++++++------------------
 1 files changed, 28 insertions(+), 18 deletions(-)

diffs (69 lines):

diff -r 82f772dfd043 -r c52d5d6f4427 lib/libc/iconv/iconv.3
--- a/lib/libc/iconv/iconv.3    Tue Jan 08 19:03:16 2013 +0000
+++ b/lib/libc/iconv/iconv.3    Tue Jan 08 19:19:24 2013 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: iconv.3,v 1.16 2013/01/04 07:27:57 wiz Exp $
+.\" $NetBSD: iconv.3,v 1.17 2013/01/08 19:19:24 dholland Exp $
 .\"
 .\" Copyright (c)2003 Citrus Project,
 .\" All rights reserved.
@@ -24,7 +24,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd January 3, 2013
+.Dd January 8, 2013
 .Dt ICONV 3
 .Os
 .\" ----------------------------------------------------------------------
@@ -235,24 +235,34 @@
 conform to
 .St -p1003.1-2001 .
 .Pp
-Unfortunately due a historical mistake (documented in 
-.Lk https://www5.opengroup.org/sophocles2/show_mail.tpl?&source=L&listname=austin-group-l&id=7404 ) ,
-where the unix header page had the
-second argument of
+Historically, the definition of
+.Ft iconv
+has not been consistent across operating systems.
+This is due to an unfortunate historical mistake, documented in 
+.Lk https://www5.opengroup.org/sophocles2/show_mail.tpl?&source=L&listname=austin-group-l&id=7404 "this e-mail".
+The standards page for the header file
+.In iconv.h
+defined the second argument of
 .Fn iconv
 as
-.Ft char **
-and the manual page had the same as
-.Ft const char ** ,
-the definition of
-.Ft iconv
-has not been consistent across operating systems.
-Given the committee's decicion to follow the header definition, we had to make
-a decision between following the committee's change or keeping our existing
-definition which is arguably more correct like others have
-.Pq Lk http://www.gnu.org/savannah-checkouts/gnu/libiconv/documentation/libiconv-1.14/ .
-We chose to keep our definition and we believe that this is not a problem because
-most packages are aware of this issue and handle it anyway during configuration.
+.Ft char ** ,
+but the standards page for the
+.Fn iconv
+implementation defined it as
+.Ft const char ** .
+The standards committee later chose to change the function definition to
+follow the header file definition
+.Pq without const ,
+even though the version with const is arguably more correct.
+.Nx
+has always used the const form.
+It was decided to reject the committee's regression and become
+.Pq technically
+incompatible.
+GNU libiconv has taken the
+.Lk http://www.gnu.org/savannah-checkouts/gnu/libiconv/documentation/libiconv-1.14/ "same route".
+Most third party software affected by this issue already handles it
+during configuration.
 .\" ----------------------------------------------------------------------
 .Sh BUGS
 If