[src/trunk]: src/lib/libc/iconv Explain why we did not follow the standard.

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

details:   https://anonhg.NetBSD.org/src/rev/8e4806535ec4
branches:  trunk
changeset: 783690:8e4806535ec4
user:      christos <christos%NetBSD.org@localhost>
date:      Fri Jan 04 01:21:45 2013 +0000

description:
Explain why we did not follow the standard.
Worth revisiting the proposal:
http://marc.info/?l=netbsd-tech-userlevel&m=110019726222841

diffstat:

 lib/libc/iconv/iconv.3 |  23 +++++++++++++++++++++--
 1 files changed, 21 insertions(+), 2 deletions(-)

diffs (44 lines):

diff -r 34ccd6f06083 -r 8e4806535ec4 lib/libc/iconv/iconv.3
--- a/lib/libc/iconv/iconv.3    Fri Jan 04 00:49:44 2013 +0000
+++ b/lib/libc/iconv/iconv.3    Fri Jan 04 01:21:45 2013 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: iconv.3,v 1.14 2010/05/05 22:07:58 wiz Exp $
+.\" $NetBSD: iconv.3,v 1.15 2013/01/04 01:21:45 christos 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 May 5, 2010
+.Dd January 3, 2013
 .Dt ICONV 3
 .Os
 .\" ----------------------------------------------------------------------
@@ -234,6 +234,25 @@
 .Fn iconv
 conform to
 .St -p1003.1-2001 .
+.Pp
+Unfortunately due a historical mistake (documented in 
+.Pa 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
+.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 (
+.Pa 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.
 .\" ----------------------------------------------------------------------
 .Sh BUGS
 If