Documentation for native2ascii task

Submitted by: Andrew Sudell <asudell@Op.Net> git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@268127 13f79535-47bb-0310-9956-ffa450edef68
24 years ago · e876237361
--- a/docs/native2ascii.html
+++ b/docs/native2ascii.html
@@ -1,58 +1,131 @@
 <html>
 <head><title>Native2Ascii</title></head>
 <body>
 <h2>Native2Ascii</h2>
  <head><title>Native2Ascii</title></head>
  <body>
    <h2>Native2Ascii</h2>
    
    <h3>Description:</h3>
    
    <p>
      Converts files from native encodings to ASCII with escaped Unicode.
      A common usage is to convert source files maintained in a native
      operating system encoding, to ASCII prior to compilation.
    </p>

 <h3>Description:</h3>
    <p>
      Files in the directory <em>src</em>
      are converted from a native encoding to ASCII.
      By default, all files in the directory are converted.
      However, conversion may be limited to selected files using
      <em>includes</em> and <em>excludes</em> attributes.
      For more information on file matching patterns,
      see the section on
      <a href="index.html#directorybasedtasks">directory based tasks</a>.
      If no <em>encoding</em> is specified, 
      the default encoding for the JVM is used.
      If <em>ext</em> is specified, then output files are renamed
      to use it as a new extension.
      If <em>dest</em> and <em>src</em> point to the same directory,
      the <em>ext</em> attribute is required.
    </p>

 <p>Converts files from native encodings to ascii with escaped Unicode.
 A common usage is to convert source files maintained in a native
 operating system encoding, to ascii prior to compilation.</p>
    <p>
      This task forms an implicit <a href="index.html#fileset">File Set</a>,
      and supports all attributes of <code>&lt;fileset&gt;</code>
      (<code>dir</code> becomes <code>src</code>) as well as 
      nested <code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code>,
      and <code>&lt;patternset&gt;</code> elements.
    </p>

 <p>All matching files in the source directory are converted from a
 native encoding to ascii.  If no encoding is specified, the default
 encoding for the JVM is used.  If ext is specified, then output
 files are renamed to use it as a new extension.  If dest and
 src point to the same directory, ext is required.</p>
    <table border="1" cellpading="2" cellspacing="0">
      <tr>
        <td><b>Attribute</b></td>
        <td><b>Description</b></td>
        <td><b>Required<b></td>
      </tr>
      <tr>
        <td>reverse</td>
        <td>Reverse the sense of the conversion,
          i.e. convert from ASCII to native</td>
        <td align="center">No</td>
      </tr>
      <tr>
        <td>encoding</td>
        <td>The native encoding the files are in
          (default is the default encoding for the JVM)</td>
        <td align="center">No</td>
      </tr>
      <tr>
        <td>src</td>
        <td>The directory to find files in (default is <em>basedir</em>)</td>
        <td align="center">No</td>
      </tr>
      <tr>
        <td>dest</td>
        <td>The directory to output file to</td>
        <td align="center">Yes</td>
      </tr>
      <tr>
        <td>ext</td>
        <td>File extension to use in renaming output files</td>
        <td align="center">No</td>
      </tr>
      <tr>
        <td>defaultexcludes</td>
        <td>indicates whether default excludes should be used or not
          (&quot;yes&quot;/&quot;no&quot;).
          Default excludes are used when omitted.
        </td>
        <td align="center">No</td>
      </tr>
      <tr>
        <td>includes</td>
        <td>comma separated list of patterns of files that must be
          included. All files are included when omitted.</td>
        <td align="center">No</td>
      </tr>
      <tr>
        <td>includesfile</td>
        <td>the name of a file. Each line of this file is
          taken to be an include pattern</td>
        <td align="center">No</td>
      </tr>
      <tr>
        <td>excludes</td>
        <td>comma separated list of patterns of files that must be excluded.
          No files (except default excludes) are excluded when omitted.</td>
        <td align="center">No</td>
      </tr>
      <tr>
        <td>excludesfile</td>
        <td>the name of a file. Each line of this file is
          taken to be an exclude pattern</td>
        <td align="center">No</td>
      </tr>
    </table>
      
    <h3>Examples</h3>

 <p>This is a directory based task, and supports includes, includesfile,
 excludes, excludesfile, and defaultexcludes along with its specific
 attributes.</p>

 <pre>
 Attribute Description                              Required
 -----------------------------------------------------------
 reverse   Reverse the sense of the conversion,     No
          i.e. convert from ascii to native 

 encoding  The native encoding the files are in     No

 src       The directory to find files in           No

 dest      The directory to output file to          Yes

 ext       File extension to use in renaming        No
          output files 
 </pre>

 <h3>Examples</h3>

 <pre>
    <pre>
 &lt;native2ascii encoding=&quot;EUCJIS&quot; src=&quot;srcdir&quot; dest=&quot;srcdir&quot;
   includes=&quot;**/*.eucjis&quot; ext=&quot;.java&quot; /&gt;
 </pre>
    </pre>

 <p>Converts all files in the directory srcdir ending in eucjis
 from the EUCJIS encoding to ascii and renames the to end in
 .java.</p>
    <p>
      Converts all files in the directory <em>srcdir</em>
      ending in <code>.eucjis</code> from the EUCJIS encoding to ASCII
      and renames them to end in <code>.java</code>.
    </p>

 <pre>
 &lt;native2ascii encoding='EUCJIS&quot; src=&quot;native/japanese&quot; dest=&quot;src&quot;
   includes=&quot;**/*.java /&gt;
 </pre>

 <p>Converts all the files ending in .java in the directory native/japanese
 to ascii, placing the results in the directory src.  The names of
 the files remain the same.</p>
 </body>
 </html>
    <p>
      Converts all the files ending in <code>.java</code>
      in the directory <em>native/japanese</em> to ASCII,
      placing the results in the directory <em>src</em>.
      The names of the files remain the same.
    </p>
  </body>
 </html>