bodewig 01/08/06 02:15:14
Modified: docs/manual/CoreTasks fixcrlf.html
Log:
update documentation for <fixcrlf>
PR: 1053
Submitted by: Peter B. West <[EMAIL PROTECTED]>
Revision Changes Path
1.3 +145 -41 jakarta-ant/docs/manual/CoreTasks/fixcrlf.html
Index: fixcrlf.html
===================================================================
RCS file: /home/cvs/jakarta-ant/docs/manual/CoreTasks/fixcrlf.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- fixcrlf.html 2001/02/13 12:31:51 1.2
+++ fixcrlf.html 2001/08/06 09:15:14 1.3
@@ -9,21 +9,38 @@
<h2><a name="fixcrlf">FixCRLF</a></h2>
<h3>Description</h3>
-<p>Adjusts a text file to local.</p>
-<p>It is possible to refine the set of files that are being adjusted. This
can be
-done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>,
<i>excludesfile</i> and <i>defaultexcludes</i>
-attributes. With the <i>includes</i> or <i>includesfile</i> attribute you
specify the files you want to
-have included by using patterns. The <i>exclude</i> or <i>excludesfile</i>
attribute is used to specify
-the files you want to have excluded. This is also done with patterns. And
-finally with the <i>defaultexcludes</i> attribute, you can specify whether
you
-want to use default exclusions or not. See the section on <a
-href="../dirtasks.html#directorybasedtasks">directory based tasks</a>, on
how the
-inclusion/exclusion of files works, and how to write patterns.</p>
+ <p>
+ Adjusts a text file to local conventions.
+ </p>
+
+ <p>
+ The set of files to be adjusted can be refined with the
+ <i>includes</i>, <i>includesfile</i>, <i>excludes</i>,
+ <i>excludesfile</i> and <i>defaultexcludes</i>
+ attributes. Patterns provided through the <i>includes</i> or
+ <i>includesfile</i> attributes specify files to be
+ included. Patterns provided through the <i>exclude</i> or
+ <i>excludesfile</i> attribute specify files to be
+ excluded. Additionally, default exclusions can be specified with
+ the <i>defaultexcludes</i> attribute. See the section on <a
+ href="../dirtasks.html#directorybasedtasks">directory based
+ tasks</a>, for details of file inclusion/exclusion patterns
+ and their usage.
+ </p>
+
<p>This task forms an implicit <a
href="../CoreTypes/fileset.html">FileSet</a> and
supports all attributes of <code><fileset></code>
(<code>dir</code> becomes <code>srcdir</code>) as well as the nested
<code><include></code>, <code><exclude></code> and
<code><patternset></code> elements.</p>
+
+ <p>
+ The output file is only written if it is a new file, or if it
+ differs from the existing file. This prevents spurious
+ rebuilds based on unchanged files which have been regenerated
+ by this task.
+ </p>
+
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
@@ -71,25 +88,83 @@
<td valign="top">indicates whether default excludes should be used or not
("yes"/"no"). Default excludes are used when
omitted.</td>
<td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">cr</td>
- <td valign="top">Specifies how carriage return (CR) characters are to
- be handled. Valid values for this property are:
- <ul>
- <li>add: ensure that there is a CR before every LF</li>
- <li>asis: leave CR characters alone</li>
- <li>remove: remove all CR characters</li>
- </ul>
- Default is based on the platform on which you are running this task.
- For Unix platforms, the default is remove. For DOS based systems
- (including Windows), the default is add.
- <p>
- Note: Unless this property is specified as "asis", extra CR
characters
- which do not precede a LF will be removed.</p>
- </td>
- <td valign="top" align="center">No</td>
</tr>
+ <tr>
+ <td valign="top">eol</td>
+ <td valign="top">
+ Specifies how end-of-line (EOL) characters are to be
+ handled. The EOL characters are CR, LF and the pair CRLF.
+ Valid values for this property are:
+ <ul>
+ <li>asis: leave EOL characters alone</li>
+ <li>cr: convert all EOLs to a single CR</li>
+ <li>lf: convert all EOLs to a single LF</li>
+ <li>crlf: convert all EOLs to the pair CRLF</li>
+ </ul>
+ Default is based on the platform on which you are running
+ this task. For Unix platforms, the default is "lf".
+ For DOS based systems (including Windows), the default is
+ "crlf". For Mac OS, the default is "cr".
+ <p>
+ This is the preferred method for specifying EOL. The
+ "<i><b>cr</b></i>" attribute (see below) is
+ now deprecated. If both are specified, "eol"
+ takes precedence.
+ </p>
+ <p>
+ <i>N.B.</i>: One special case is recognized. The three
+ characters CR-CR-LF are regarded as a single EOL.
+ Unless this property is specified as "asis",
+ this sequence will be converted into the specified EOL
+ type.
+ </p>
+ </td>
+ <td valign="top" align="center">No</td>
+ </tr>
+ <tr>
+ <td valign="top">cr</td>
+ <td valign="top">
+ <i><b>Deprecated.</b></i> Specifies how CR characters are
+ to be handled at end-of-line (EOL). Valid values for this
+ property are:
+ <ul>
+ <li>asis: leave EOL characters alone.</li>
+ <li>
+ add: add a CR before any single LF characters. The
+ intent is to convert all EOLs to the pair CRLF.
+ </li>
+ <li>
+ remove: remove all CRs from the file. The intent is
+ to convert all EOLs to a single LF.
+ </li>
+ </ul>
+ Default is based on the platform on which you are running
+ this task. For Unix platforms, the default is "remove".
+ For DOS based systems (including Windows), the default is
+ "add".
+ <p>
+ <i>N.B.</i>: One special case is recognized. The three
+ characters CR-CR-LF are regarded as a single EOL.
+ Unless this property is specified as "asis",
+ this sequence will be converted into the specified EOL
+ type.
+ </p>
+ </td>
+ <td valign="top" align="center">No</td>
+ </tr>
+ <tr>
+ <td valign="top">javafiles</td>
+ <td valign="top">
+ Used only in association with the
+ "<i><b>tab</b></i>" attribute (see below), this
+ boolean attribute indicates whether the fileset is a set
+ of java source files
+ ("yes"/"no"). Defaults to
+ "no". See notes in section on "tab".
+ </td>
+ <td valign="top" align="center">No</td>
+ </tr>
+ <tr>
<tr>
<td valign="top">tab</td>
<td valign="top">Specifies how tab characters are to be handled. Valid
@@ -100,16 +175,27 @@
<li>remove: convert tabs to spaces</li>
</ul>
Default for this parameter is "asis".
+ <p>
+ <i>N.B.</i>: When the attribute
+ "<i><b>javafiles</b></i>" (see above) is
+ "true", literal TAB characters occurring
+ within Java string or character constants are never
+ modified. This functionality also requires the
+ recognition of Java-style comments.
+ </p>
<p>
- Note: Unless this property is specified as "asis", extra
spaces and
- tabs after the last non-whitespace character on the line will be
removed.</p>
+ <i>N.B.</i>: There is an incompatibility between this
+ and the previous version in the handling of white
+ space at the end of lines. This version does
+ <i><b>not</b></i> remove trailing whitespace on lines.
+</p>
</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">tablength</td>
- <td valign="top">The number of characters a TAB stop corresponds to.
- Must be a positive power of 2, default for this parameter is 8.</td>
+ <td valign="top">TAB character interval. Valid values are between
+ 2 and 80 inclusive. The default for this parameter is 8.</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
@@ -130,16 +216,16 @@
</table>
<h3>Examples</h3>
<pre> <fixcrlf srcdir="${src}"
- cr="remove" eof="remove"
+ eol="lf" eof="remove"
includes="**/*.sh"
/></pre>
-<p>Removes carriage return and eof characters from the shell scripts. Tabs
and
-spaces are left as is.</p>
+<p>Replaces EOLs with LF characters and removes eof characters from
+ the shell scripts. Tabs and spaces are left as is.</p>
<pre> <fixcrlf srcdir="${src}"
- cr="add"
+ eol="crlf"
includes="**/*.bat"
/></pre>
-<p>Ensures that there are carriage return characters prior to evey line feed.
+<p>Replaces all EOLs with cr-lf pairs in the batch files.
Tabs and spaces are left as is.
EOF characters are left alone if run on
DOS systems, and are removed if run on Unix systems.</p>
@@ -147,16 +233,34 @@
tabs="add"
includes="**/Makefile"
/></pre>
-<p>Adds or removes CR characters to match local OS conventions, and
-converts spaces to tabs when appropriate. EOF characters are left alone if
+<p>Sets EOLs according to local OS conventions, and
+converts sequences of spaces and tabs to the minimal set of spaces and
+ tabs which will maintain spacing within the line. Tabs are
+ set at 8 character intervals. EOF characters are left alone if
run on DOS systems, and are removed if run on Unix systems.
Many versions of make require tabs prior to commands.</p>
+ <pre> <fixcrlf srcdir="${src}"
+ tabs="remove"
+ tablength="3"
+ eol="lf"
+ javafiles="yes"
+ includes="**/*.java"
+ /></pre>
+ <p>
+ Converts all EOLs in the included java source files to a
+ single LF. Replace all TAB characters except those in string
+ or character constants with spaces, assuming a tab width of 3.
+ If run on a unix system, any CTRL-Z EOF characters at the end
+ of the file are removed. On DOS/Windows, any such EOF
+ characters will be left untouched.
+ </p>
<pre> <fixcrlf srcdir="${src}"
tabs="remove"
includes="**/README*"
/></pre>
-<p>Adds or removes CR characters to match local OS conventions, and
-converts all tabs to spaces. EOF characters are left alone if run on
+<p>Sets EOLs according to local OS conventions, and
+converts all tabs to spaces, assuming a tab width of 8.
+EOF characters are left alone if run on
DOS systems, and are removed if run on Unix systems.
You never know what editor a user will use to browse README's.</p>
<hr>
