warn against multi-byte encoding in tar

manual/Tasks/tar.html

@@ -133,7 +133,10 @@ to <q>gzip</q>, <q>bzip2</q>, or <q>xz</q>.</p>
     <td>The character encoding to use for filenames inside the tar file.  For a list of possible
       values see
       the <a href="https://docs.oracle.com/javase/8/docs/technotes/guides/intl/encoding.doc.html"
-      target="_top">Supported Encodings</a>.<br/><em>Since Ant 1.9.5</em>
+      target="_top">Supported Encodings</a>. In general the tar format
+      expects names to use a single byte encoding and specifying a
+      multi-byte encoding here may lead to archives that cannot be
+      properly extracted by my tar tools.<br/><em>Since Ant 1.9.5</em>
     <td>No; defaults to default JVM character encoding</td>
   </tr>
 </table>

src/etc/testcases/taskdefs/untar.xml

@@ -58,6 +58,14 @@
   </target>
 
   <target name="encodingTest">
+    <mkdir dir="${output}/untartestin"/>
+    <touch file="${output}/untartestin/foo"/>
+    <tar tarfile="${output}/untartest.tar" basedir="${output}/untartestin" encoding="Cp1251"/>
+    <mkdir dir="${output}/untartestout"/>
+    <untar src="${output}/untartest.tar" dest="${output}/untartestout" encoding="Cp1251"/>
+  </target>
+
+  <target name="multiByteEncodingTest">
     <mkdir dir="${output}/untartestin"/>
     <touch file="${output}/untartestin/foo"/>
     <tar tarfile="${output}/untartest.tar" basedir="${output}/untartestin" encoding="UnicodeBig"/>

src/tests/junit/org/apache/tools/ant/taskdefs/UntarTest.java

@@ -85,6 +85,14 @@ public class UntarTest {
                    buildRule.getProject().resolveFile(filename).exists());
     }
 
+    @Test
+    public void testMultiByteEncoding() {
+        buildRule.executeTarget("multiByteEncodingTest");
+        String filename = buildRule.getProject().getProperty("output") + "/untartestout/foo";
+        assertTrue("foo has been properly named",
+                   buildRule.getProject().resolveFile(filename).exists());
+    }
+
     @Test
     public void testResourceCollection() throws IOException {
         testLogoExtraction("resourceCollection");