From 329021e4de4f67d96ab600a52da7a0b65184e744 Mon Sep 17 00:00:00 2001 From: Stefan Bodewig Date: Mon, 6 Aug 2001 09:15:14 +0000 Subject: [PATCH] update documentation for PR: 1053 Submitted by: Peter B. West git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@269468 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/CoreTasks/fixcrlf.html | 186 ++++++++++++++++++++++------- 1 file changed, 145 insertions(+), 41 deletions(-) diff --git a/docs/manual/CoreTasks/fixcrlf.html b/docs/manual/CoreTasks/fixcrlf.html index 287ad0e80..80777e154 100644 --- a/docs/manual/CoreTasks/fixcrlf.html +++ b/docs/manual/CoreTasks/fixcrlf.html @@ -9,21 +9,38 @@

FixCRLF

Description

-

Adjusts a text file to local.

-

It is possible to refine the set of files that are being adjusted. This can be -done with the includes, includesfile, excludes, excludesfile and defaultexcludes -attributes. With the includes or includesfile attribute you specify the files you want to -have included by using patterns. The exclude or excludesfile attribute is used to specify -the files you want to have excluded. This is also done with patterns. And -finally with the defaultexcludes attribute, you can specify whether you -want to use default exclusions or not. See the section on directory based tasks, on how the -inclusion/exclusion of files works, and how to write patterns.

+

+ Adjusts a text file to local conventions. +

+ +

+ The set of files to be adjusted can be refined with the + includes, includesfile, excludes, + excludesfile and defaultexcludes + attributes. Patterns provided through the includes or + includesfile attributes specify files to be + included. Patterns provided through the exclude or + excludesfile attribute specify files to be + excluded. Additionally, default exclusions can be specified with + the defaultexcludes attribute. See the section on directory based + tasks, for details of file inclusion/exclusion patterns + and their usage. +

+

This task forms an implicit FileSet and supports all attributes of <fileset> (dir becomes srcdir) as well as the nested <include>, <exclude> and <patternset> elements.

+ +

+ 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. +

+

Parameters

@@ -72,24 +89,82 @@ supports all attributes of <fileset> ("yes"/"no"). Default excludes are used when omitted. - - - - - + + + + + + + + + + + + + + + + - + @@ -130,16 +216,16 @@ supports all attributes of <fileset>
No
crSpecifies how carriage return (CR) characters are to - be handled. Valid values for this property are: -
    -
  • add: ensure that there is a CR before every LF
    • -
  • asis: leave CR characters alone
    • -
  • remove: remove all CR characters
    • -
- 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. -

- Note: Unless this property is specified as "asis", extra CR characters - which do not precede a LF will be removed.

- 		No
eol + 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: +
    +
  • asis: leave EOL characters alone
    • +
  • cr: convert all EOLs to a single CR
    • +
  • lf: convert all EOLs to a single LF
    • +
  • crlf: convert all EOLs to the pair CRLF
    • +
+ 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". +

+ This is the preferred method for specifying EOL. The + "cr" attribute (see below) is + now deprecated. If both are specified, "eol" + takes precedence. +

+

+ N.B.: 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. +

+ 		No
cr + Deprecated. Specifies how CR characters are + to be handled at end-of-line (EOL). Valid values for this + property are: +
    +
  • asis: leave EOL characters alone.
    • +
  • + add: add a CR before any single LF characters. The + intent is to convert all EOLs to the pair CRLF. +
    • +
  • + remove: remove all CRs from the file. The intent is + to convert all EOLs to a single LF. +
    • +
+ 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". +

+ N.B.: 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. +

+ 		No
javafiles + Used only in association with the + "tab" 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". + No
tab Specifies how tab characters are to be handled. Valid @@ -100,16 +175,27 @@ supports all attributes of <fileset>
  • remove: convert tabs to spaces
    • Default for this parameter is "asis". +

    + N.B.: When the attribute + "javafiles" (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. +

    - Note: Unless this property is specified as "asis", extra spaces and - tabs after the last non-whitespace character on the line will be removed.

    + N.B.: There is an incompatibility between this + and the previous version in the handling of white + space at the end of lines. This version does + not remove trailing whitespace on lines. +

    		 No
    tablengthThe number of characters a TAB stop corresponds to. - Must be a positive power of 2, default for this parameter is 8.TAB character interval. Valid values are between + 2 and 80 inclusive. The default for this parameter is 8. No

    Examples

      <fixcrlf srcdir="${src}"
-       cr="remove" eof="remove"
+       eol="lf" eof="remove"
        includes="**/*.sh"
   />
    -

    Removes carriage return and eof characters from the shell scripts. Tabs and -spaces are left as is.

    +

    Replaces EOLs with LF characters and removes eof characters from + the shell scripts. Tabs and spaces are left as is.

      <fixcrlf srcdir="${src}"
-       cr="add"
+       eol="crlf"
        includes="**/*.bat"
   />
    -

    Ensures that there are carriage return characters prior to evey line feed. +

    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.

    @@ -147,16 +233,34 @@ DOS systems, and are removed if run on Unix systems.

    tabs="add" includes="**/Makefile" /> -

    Adds or removes CR characters to match local OS conventions, and -converts spaces to tabs when appropriate. EOF characters are left alone if +

    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.

    + 
      <fixcrlf srcdir="${src}"
+       tabs="remove"
+       tablength="3"
+       eol="lf"
+       javafiles="yes"
+       includes="**/*.java"
+  />
    +

    + 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. + 

      <fixcrlf srcdir="${src}"
        tabs="remove"
        includes="**/README*"
   />
    -

    Adds or removes CR characters to match local OS conventions, and -converts all tabs to spaces. EOF characters are left alone if run on +

    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.