Changeset 181

Show
Ignore:
Timestamp:
04/17/07 14:30:42 (1 year ago)
Author:
mrook
Message:

Fix typo (closes issue #95)

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/docs/phing_guide/book/chapters/ProjectComponents.html

    r123 r181  
    1616<h1>Project Components</h1> 
    1717 
    18 <p> This goal of this chapter is to make you familiar with the basic components  
    19   of a buildfile. After reading this chapter, you should be able to read and understand  
    20   the basic structure of any buildfile even if you don't know exactly what the  
     18<p> This goal of this chapter is to make you familiar with the basic components 
     19  of a buildfile. After reading this chapter, you should be able to read and understand 
     20  the basic structure of any buildfile even if you don't know exactly what the 
    2121  individual pieces do. </p> 
    22 <p>For supplemental reference information, you should see <a href="appendixes/AppendixB-CoreTasks.html">Appendix  
    23   B</a>, <a href="appendixes/AppendixC-CoreTypes.html">Appendix C</a> and <a href="appendixes/AppendixD-ProjectComponents.html">Appendix  
     22<p>For supplemental reference information, you should see <a href="appendixes/AppendixB-CoreTasks.html">Appendix 
     23  B</a>, <a href="appendixes/AppendixC-CoreTypes.html">Appendix C</a> and <a href="appendixes/AppendixD-ProjectComponents.html">Appendix 
    2424  D</a>. </p> 
    2525 
    2626<h2><a name="Projects"></a>Projects</h2> 
    2727 
    28 <p> In the structure of a Phing buildfile, there must be exactly one <em>Project</em>  
    29   defined; the <em>&lt;project&gt; </em>tag is the root element of the buildfile,  
    30   meaning that everything else in the buildfile is contained within the <em>&lt;project</em>  
     28<p> In the structure of a Phing buildfile, there must be exactly one <em>Project</em> 
     29  defined; the <em>&lt;project&gt; </em>tag is the root element of the buildfile, 
     30  meaning that everything else in the buildfile is contained within the <em>&lt;project</em> 
    3131  &gt; element.</p> 
    3232 
    …… 
    3939</pre> 
    4040 
    41 <p> The listing above shows a sample <em>&lt;project&gt;</em> tag that has all  
    42   attributes available for Projects. The <em>name</em> and <em>description</em>  
    43   attributes are fairly self-explanatory; the <em>default</em> attribute specifies  
    44   the default <em>Target</em> to execute if no target is specified (<a href="#Target">Targets</a>  
    45   are described below). For a complete reference, see <a href="appendixes/AppendixD-ProjectComponents.html#Project">Appendix  
     41<p> The listing above shows a sample <em>&lt;project&gt;</em> tag that has all 
     42  attributes available for Projects. The <em>name</em> and <em>description</em> 
     43  attributes are fairly self-explanatory; the <em>default</em> attribute specifies 
     44  the default <em>Target</em> to execute if no target is specified (<a href="#Target">Targets</a> 
     45  are described below). For a complete reference, see <a href="appendixes/AppendixD-ProjectComponents.html#Project">Appendix 
    4646  D</a>. </p> 
    4747 
    4848<h2><a name="ComponentsInGeneral"></a>Project Components in General</h2> 
    4949 
    50 <p> Project components are everything you can be find inside a project. So Targets  
    51   are project components, as are Tasks, Types, etc. Project components may have  
    52   attributes and nested tags. Attributes only contain simple values, i.e. strings,  
    53   integers etc. Nested elements may be complex Phing types (like FileSets) or  
    54   simple wrapper classes for values with custom keys (see <a href="appendixes/AppendixC-CoreTypes.html#Fileset">FileSet</a>  
     50<p> Project components are everything you can be find inside a project. So Targets 
     51  are project components, as are Tasks, Types, etc. Project components may have 
     52  attributes and nested tags. Attributes only contain simple values, i.e. strings, 
     53  integers etc. Nested elements may be complex Phing types (like FileSets) or 
     54  simple wrapper classes for values with custom keys (see <a href="appendixes/AppendixC-CoreTypes.html#Fileset">FileSet</a> 
    5555  for example). </p> 
    5656 
    57 <p> Any nested elements must be supported by the class that implements the project  
    58   component, and because the nested tags are handled by the project component  
    59   class the same nested tag may have different meanings (and different attributes)  
    60   depending on the context. So, for example, the nested tag <em>&lt;param</em>.../&gt;  
    61   within the <em>&lt;phingcall&gt;</em> tag is handled very differently from the<em>&lt;param.../&gt;</em>  
    62   tag within the <em>&lt;xsltfilter&gt;</em> tag -- in the first case setting  
     57<p> Any nested elements must be supported by the class that implements the project 
     58  component, and because the nested tags are handled by the project component 
     59  class the same nested tag may have different meanings (and different attributes) 
     60  depending on the context. So, for example, the nested tag <em>&lt;param</em>.../&gt; 
     61  within the <em>&lt;phingcall&gt;</em> tag is handled very differently from the<em>&lt;param.../&gt;</em> 
     62  tag within the <em>&lt;xsltfilter&gt;</em> tag -- in the first case setting 
    6363  project properties, in the second case setting XSLT parameters. </p> 
    6464 
    6565<h2><a name="Targets"></a>Targets</h2> 
    6666 
    67 <p> Targets are collections of project components (but not other targets) that  
    68   are assigned a unique name within their project. A target generally performs  
    69   a specific task -- or calls other targets that perform specific tasks -- and  
    70   therefore a target is a bit like a <em> function</em> (but a target has no return  
     67<p> Targets are collections of project components (but not other targets) that 
     68  are assigned a unique name within their project. A target generally performs 
     69  a specific task -- or calls other targets that perform specific tasks -- and 
     70  therefore a target is a bit like a <em> function</em> (but a target has no return 
    7171  value).</p> 
    72 <p>Targets may <em>depend</em> on other targets. For example, if target A depends  
    73   on a target B, then when target A is called to be executed, target B will be  
    74   executed first. Phing automatically resolves these dependencies. You cannot  
    75   have circular references like: &quot;target A depends on target B that depends  
     72<p>Targets may <em>depend</em> on other targets. For example, if target A depends 
     73  on a target B, then when target A is called to be executed, target B will be 
     74  executed first. Phing automatically resolves these dependencies. You cannot 
     75  have circular references like: &quot;target A depends on target B that depends 
    7676  on target A&quot;. </p> 
    7777 
    …… 
    9090</pre> 
    9191 
    92 <p> When Phing is asked to execute the <em>othertask</em> target, it will see  
    93   the dependency and execute <em>buildpage </em>first. Notice that the the dependency  
     92<p> When Phing is asked to execute the <em>othertask</em> target, it will see 
     93  the dependency and execute <em>buildpage </em>first. Notice that the the dependency 
    9494  task can be defined after the dependent task.</p> 
    9595 
    9696<h2><a name="Tasks"></a>Tasks</h2> 
    9797 
    98 <p> Tasks are responsible for doing the work in Phing. Basically, tasks are the  
    99   individual actions that your buildfile can perform. For example, tasks exist  
    100   to copy a file, create a directory, TAR files in a directory. Tasks may also  
    101   be more complex such as XsltTask which copies a file and transforms the file  
    102   using XSLT, SmartyTask which does something similar using Smarty templates,  
    103   or CreoleTask which executes SQL statements against a specified DB. See <a href="appendixes/AppendixB-CoreTasks.html#XsltTask">Appendix  
     98<p> Tasks are responsible for doing the work in Phing. Basically, tasks are the 
     99  individual actions that your buildfile can perform. For example, tasks exist 
     100  to copy a file, create a directory, TAR files in a directory. Tasks may also 
     101  be more complex such as XsltTask which copies a file and transforms the file 
     102  using XSLT, SmartyTask which does something similar using Smarty templates, 
     103  or CreoleTask which executes SQL statements against a specified DB. See <a href="appendixes/AppendixB-CoreTasks.html#XsltTask">Appendix 
    104104  B</a> for descriptions of Phing tasks.</p> 
    105105 
    …… 
    115115a value <em>&quot;A simple string.&quot;</em> as a parameter, it 
    116116is evaluated as a string and accessible as one. You can also reference 
    117 properties as described in  
     117properties as described in 
    118118<a href="GettingStarted.html#PropertyElement">Getting Started</a>. 
    119119</p> 
    120120 
    121 <p> <em>Note:</em> There are special values that are not mapped to strings, but  
    122   to boolean values instead. The values <em>true</em>, <em>false</em>, <em>yes</em>,  
    123   <em>no</em>, <em>on</em> and <em>off</em> are translated to true/false boolean  
     121<p> <em>Note:</em> There are special values that are not mapped to strings, but 
     122  to boolean values instead. The values <em>true</em>, <em>false</em>, <em>yes</em>, 
     123  <em>no</em>, <em>on</em> and <em>off</em> are translated to true/false boolean 
    124124  values. </p> 
    125125 
    …… 
    139139</pre> 
    140140 
    141 <p> Here, <em>CopyTask</em> is passed a complex parameter, a Fileset. Tasks may  
    142   support multiple complex types in addition to simple parameters. Note that the  
    143   names of the nested tags used to create the complex types depend on the task  
    144   implementation. Tasks may support default Phing types (see <a href="#Types">below</a>)  
     141<p> Here, <em>CopyTask</em> is passed a complex parameter, a Fileset. Tasks may 
     142  support multiple complex types in addition to simple parameters. Note that the 
     143  names of the nested tags used to create the complex types depend on the task 
     144  implementation. Tasks may support default Phing types (see <a href="#Types">below</a>) 
    145145  or may introduce other types, for example to wrap key/value pairs. </p> 
    146146 
    147 <p> Refer to <a href="appendixes/AppendixB-CoreTasks.html">Appendix B</a> for  
     147<p> Refer to <a href="appendixes/AppendixB-CoreTasks.html">Appendix B</a> for 
    148148  a list of system tasks and their parameters.</p> 
    149149 
    …… 
    152152<h3><a name="TypesBasics"></a>Basics</h3> 
    153153 
    154 <p> Besides the simple types (strings, integer, booleans) you can use in the parameters  
    155   of tasks, there are more complex Phing <em>Types</em>. As mentioned above, they  
     154<p> Besides the simple types (strings, integer, booleans) you can use in the parameters 
     155  of tasks, there are more complex Phing <em>Types</em>. As mentioned above, they 
    156156  are passed to a task by using nesting tags: </p> 
    157157 
    …… 
    172172</pre> 
    173173 
    174 <p> Note that types may consist of multiple nested tags -- and multiple levels  
     174<p> Note that types may consist of multiple nested tags -- and multiple levels 
    175175  of nested tags, as you can see in the second task call above.</p> 
    176176 
    177177<h3><a name="TypesReferencing"></a>Referencing Types</h3> 
    178178 
    179 <p> An additional fact about types you should notice is the possibility of <em>referencing</em>  
    180   type instances, i.e. you define your type somewhere in your build file and assign  
    181   an id to it. Later, you can refer to that type by the id you assigned. Example:  
     179<p> An additional fact about types you should notice is the possibility of <em>referencing</em> 
     180  type instances, i.e. you define your type somewhere in your build file and assign 
     181  an id to it. Later, you can refer to that type by the id you assigned. Example: 
    182182</p> 
    183183 
    …… 
    186186  &lt;fileset id=&quot;foo&quot;&gt; 
    187187    &lt;include name=&quot;*.php&quot; /&gt; 
    188   &lt;/fileset;&gt; 
     188  &lt;/fileset&gt; 
    189189 
    190190  &lt;!-- Target that uses the type --&gt; 
    …… 
    214214<h3><a name="FileSet"></a>FileSet</h3> 
    215215 
    216 <p> FileSets are groups of files. You can include or exclude specific files and  
    217   patterns to/from a FileSet. The use of patterns is explained below. For a start,  
     216<p> FileSets are groups of files. You can include or exclude specific files and 
     217  patterns to/from a FileSet. The use of patterns is explained below. For a start, 
    218218  look at the following example: </p> 
    219219 
    …… 
    232232</pre> 
    233233 
    234 <p> The use of patterns is quite straightforward: If you simply want to match  
    235   a part of a filename or dirname, you use <strong>*</strong>. If you want to  
    236   include multiple directories and/or files, you use <strong>**</strong>. This  
     234<p> The use of patterns is quite straightforward: If you simply want to match 
     235  a part of a filename or dirname, you use <strong>*</strong>. If you want to 
     236  include multiple directories and/or files, you use <strong>**</strong>. This 
    237237  way, filesets provide an easy but powerful way to include files. </p> 
    238238 
    239239<h3><a name="FileList"></a>FileList</h3> 
    240 <p>FileLists, like FileSets, are collections of files; however, a FileList is  
    241   an explicitly defined list of files -- and the files don't necessarily have  
     240<p>FileLists, like FileSets, are collections of files; however, a FileList is 
     241  an explicitly defined list of files -- and the files don't necessarily have 
    242242  to exist on the filesystem. </p> 
    243 <p>Besides being able to refer to nonexistent files, another thing that FileLists  
    244   allow you to do is specify files <em>in a certain order</em>. Files in FileSets  
    245   are ordered based on the OS-level directory listing functions, in some cases  
    246   you may want to specify a list of files to be processed in a certain order --  
     243<p>Besides being able to refer to nonexistent files, another thing that FileLists 
     244  allow you to do is specify files <em>in a certain order</em>. Files in FileSets 
     245  are ordered based on the OS-level directory listing functions, in some cases 
     246  you may want to specify a list of files to be processed in a certain order -- 
    247247  e.g. when concatenating files using the <em>&lt;append&gt;</em> task.</p> 
    248248<pre title="FileList example">&lt;filelist dir=&quot;base/&quot; files=&quot;file1.txt,file2.txt,file3.txt&quot;/&gt; 
    …… 
    253253<h4><a name="FilterchainsFilters"></a>FilterChains and Filters</h4> 
    254254 
    255 <p> FilterChains can be compared to Unix pipes. Unix pipes add a great deal of  
    256   flexibility to command line operations; for example, if you wanted to copy just  
    257   those lines that contained the string <em>blee</em> from the first 10 lines  
     255<p> FilterChains can be compared to Unix pipes. Unix pipes add a great deal of 
     256  flexibility to command line operations; for example, if you wanted to copy just 
     257  those lines that contained the string <em>blee</em> from the first 10 lines 
    258258  of a file called <em>foo</em> to a file called <em>bar</em>, you could do: </p> 
    259259 
    …… 
    262262</pre> 
    263263 
    264 <p> Something like this is not possible with the tasks and types that we have  
    265   learned about thus far, and this is where the incredible usefulness of <em>FilterChains</em>  
    266   becomes apparent. They emulate Unix pipes and provide a powerful dimension of  
     264<p> Something like this is not possible with the tasks and types that we have 
     265  learned about thus far, and this is where the incredible usefulness of <em>FilterChains</em> 
     266  becomes apparent. They emulate Unix pipes and provide a powerful dimension of 
    267267  file/stream manipulation for the tasks that support them.</p> 
    268268 
    269 <p> FilterChain usage is quite straightforward: you pass the complex Phing type  
    270   <em>filterchain</em> to a task that supports FilterChains and add individual  
    271   filters to the FilterChain. In the course of executing the task, the filters  
    272   are applied (in the order in which they appear in the XML) to the contents of  
     269<p> FilterChain usage is quite straightforward: you pass the complex Phing type 
     270  <em>filterchain</em> to a task that supports FilterChains and add individual 
     271  filters to the FilterChain. In the course of executing the task, the filters 
     272  are applied (in the order in which they appear in the XML) to the contents of 
    273273  the files that are being manipulated by your task.</p> 
    274274 
    275275<pre> 
    276276&lt;filterchain&gt; 
    277   &lt;replacetokens&gt;     
     277  &lt;replacetokens&gt; 
    278278    &lt;token key=&quot;BC_PATH&quot; value=&quot;${top.builddir}/&quot;/&gt; 
    279279    &lt;token key=&quot;BC_PATH_USER&quot; value=&quot;${top.builddir}/testsite/user/${lang}/&quot;/&gt; 
    …… 
    283283    &lt;param name=&quot;lines&quot; value=&quot;10&quot;/&gt; 
    284284  &lt;/filterreader&gt; 
    285 &lt;/filterchain&gt;           
    286 </pre> 
    287 <p> The code listing above shows you some example of how to use filter chains.  
    288   For a complete reference see <a href="appendixes/AppendixC-CoreTypes.html#Filters">Appendix  
    289   C</a>. This filter chain would replace all occurences of <em>BC_PATH</em> and  
    290   <em>BC_PATH_USER</em> with the values assigned to them in lines 4 and 5. Additionally,  
     285&lt;/filterchain&gt; 
     286</pre> 
     287<p> The code listing above shows you some example of how to use filter chains. 
     288  For a complete reference see <a href="appendixes/AppendixC-CoreTypes.html#Filters">Appendix 
     289  C</a>. This filter chain would replace all occurences of <em>BC_PATH</em> and 
     290  <em>BC_PATH_USER</em> with the values assigned to them in lines 4 and 5. Additionally, 
    291291  it will only return the last 10 lines of the files. </p> 
    292 <p>Notice above that FilterChain filters have a &quot;shorthand&quot; notation  
    293   and a long, generic notation. Most filters can be described using both of these  
     292<p>Notice above that FilterChain filters have a &quot;shorthand&quot; notation 
     293  and a long, generic notation. Most filters can be described using both of these 
    294294  forms:</p> 
    295 <pre title="Filter shorthand / longhand comparison">&lt;replacetokens&gt;     
     295<pre title="Filter shorthand / longhand comparison">&lt;replacetokens&gt; 
    296296  &lt;token key=&quot;BC_PATH&quot; value=&quot;${top.builddir}/&quot;/&gt; 
    297297  &lt;token key=&quot;BC_PATH_USER&quot; value=&quot;${top.builddir}/testsite/user/${lang}/&quot;/&gt; 
    …… 
    305305&lt;/filterreader&gt; 
    306306</pre> 
    307 <p> As the pipe concept in Unix, the filter concept is quite complex but powerful.  
    308   To get a better understanding of different filters and how they can be used,  
    309   take a look at any of the many uses of FilterChains in the build files for the  
     307<p> As the pipe concept in Unix, the filter concept is quite complex but powerful. 
     308  To get a better understanding of different filters and how they can be used, 
     309  take a look at any of the many uses of FilterChains in the build files for the 
    310310  binarycloud <a href="Bibliography.html#bc">[bc]</a> project.</p> 
    311311 
    312312<h4><a name="Mappers"></a>File Mappers</h4> 
    313313 
    314 <p> With FilterChains and filters provide a powerful tool for changing <em>contents</em>  
    315   of files, Mappers provide a powerful tool for changing the <em>names</em> of  
     314<p> With FilterChains and filters provide a powerful tool for changing <em>contents</em> 
     315  of files, Mappers provide a powerful tool for changing the <em>names</em> of 
    316316  files.</p> 
    317317 
    318 <p> To use a Mapper, you must specify a pattern to match on and a replacement  
    319   pattern that describes how the matched pattern should be transformed. The simplest  
     318<p> To use a Mapper, you must specify a pattern to match on and a replacement 
     319  pattern that describes how the matched pattern should be transformed. The simplest 
    320320  form is basically no different from the DOS <em>copy</em> command: </p> 
    321321 
    …… 
    332332</pre> 
    333333 
    334 <p>Consider the example below to see how Mappers can be used in a build file.  
    335   This example includes some of the other concepts introduced in this chapter,  
    336   such as FilterChains and FileSets. If you don't understand everything, don't  
    337   worry. The important point is that Mappers are types too, which can be used  
     334<p>Consider the example below to see how Mappers can be used in a build file. 
     335  This example includes some of the other concepts introduced in this chapter, 
     336  such as FilterChains and FileSets. If you don't understand everything, don't 
     337  worry. The important point is that Mappers are types too, which can be used 
    338338  in tasks that support them.</p> 
    339339<pre>&lt;copy&gt; 
    …… 
    352352</pre> 
    353353 
    354 <p>For a complete reference, see <a href="appendixes/AppendixC-CoreTypes.html#Mappers">Appendix  
     354<p>For a complete reference, see <a href="appendixes/AppendixC-CoreTypes.html#Mappers">Appendix 
    355355  C</a>.</p> 
    356356 
    357357<h2><a name="Conditions">Conditions</a></h2> 
    358358 
    359 <p>Conditions are nested elements of the  
     359<p>Conditions are nested elements of the 
    360360<a href="appendixes/AppendixB-CoreTasks.html#ConditionTask">condition</code></a> and 
    361361<a href="appendixes/AppendixB-CoreTasks.html#IfTask">if</a> tasks.