From bd64d7247df1eeeb9a3f808783f3bf618cbee16b Mon Sep 17 00:00:00 2001
From: Bruno Haible <bruno@clisp.org>
Date: Thu, 30 Jul 2020 20:20:57 +0200
Subject: [PATCH] unicodeio: Add comment.

* lib/unicodeio.c (unicode_to_mb): Clarify why the code distinguishes
different iconv behaviours.
---
 ChangeLog       | 6 ++++++
 lib/unicodeio.c | 8 ++++++++
 2 files changed, 14 insertions(+)

diff --git a/ChangeLog b/ChangeLog
index cf82ab2548..95851778c1 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2020-07-30  Bruno Haible  <bruno@clisp.org>
+
+	unicodeio: Add comment.
+	* lib/unicodeio.c (unicode_to_mb): Clarify why the code distinguishes
+	different iconv behaviours.
+
 2020-07-30  Paul Eggert  <eggert@cs.ucla.edu>
 
 	Work around some Oracle Studio attribute bugs
diff --git a/lib/unicodeio.c b/lib/unicodeio.c
index 7d5e1fbcd2..d587a278d6 100644
--- a/lib/unicodeio.c
+++ b/lib/unicodeio.c
@@ -129,6 +129,14 @@ unicode_to_mb (unsigned int code,
       res = iconv (utf8_to_local,
                    (ICONV_CONST char **)&inptr, &inbytesleft,
                    &outptr, &outbytesleft);
+      /* Analyze what iconv() actually did and distinguish replacements
+         that are OK (no need to invoke the FAILURE callback), such as
+           - replacing GREEK SMALL LETTER MU with MICRO SIGN, or
+           - replacing FULLWIDTH COLON with ':', or
+           - replacing a Unicode TAG character (U+E00xx) with an empty string,
+         from replacements that are worse than the FAILURE callback, such as
+           - replacing 'ç' with '?' (NetBSD, Solaris 11) or '*' (musl) or
+             NUL (IRIX).  */
       if (inbytesleft > 0 || res == (size_t)(-1)
           /* Irix iconv() inserts a NUL byte if it cannot convert.  */
 # if !defined _LIBICONV_VERSION && (defined sgi || defined __sgi)
-- 
2.39.5