<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE taskdoc SYSTEM "http://www.schmant.org/dtd/tfdoc-1.2.dtd" [
  <!ENTITY taskCategories SYSTEM 
    "http://www.schmant.org/taskref/taskcategories.xmlf">
  <!ENTITY taskFactory SYSTEM 
    "http://www.schmant.org/taskref/TaskFactory.xmlf">
  <!ENTITY generatorTaskFactory SYSTEM 
    "http://www.schmant.org/taskref/GeneratorTaskFactory.xmlf">
]>
<taskdoc>
<!-- Use an external entity reference to a file containing task category
     information. The included file is generated when the task documentation is
     built. -->
&taskCategories;
<!-- Place this task in the text tasks category.
     It would have been nice to be able to call the task package
     "se.rövarspråket" instead, but Java's XML parser could not locate files
     under the se.rövarspråket directory. In the future, when we're all zipping
     around in our flying cars, the whole world will use UTF-8. Sigh.
     (Robbers Language is rövarspråket in Swedish.) -->
<taskfactory 
  name="RobberLanguageTF" 
  package="se.rovarspraket"
  java-package="se.rovarspraket"
  category="catText" 
  entityfs-aware="yes">

<!-- The master detective! -->
<author>Bill Bergson (Kalle Blomkvist)</author>
<since>1.0</since>

<!-- Document this task's restriction. The restriction element is optional. -->
<restriction>This task only works with text files.</restriction>

<!-- Since the task is a process task, it is also an action and a generator
     task. -->
<implements interface="ActionTaskFactory"/>
<implements interface="GeneratorTaskFactory"/>
<implements interface="ProcessTaskFactory"/>

<!-- Use a CDATA block to be able to insert our own HTML formatting. Note the
     link to the target property. If you want to link to a class, use an
     explicit class link like |api:class:(class name)?linkClass=|. See
     ApiLinksTF documentation. -->
<produces><![CDATA[The interpreted value of the
<a href="#RobbersLanguageTF_target">target</a> property.]]></produces>

<short-description>Translate text files to the Robber
  Language.</short-description>

<!-- Note the link to the example. -->
<description><![CDATA[This task translates text files to
<a href="http://en.wikipedia.org/wiki/Rövarspråket">the Robber Language</a>.</p>

<p>The vowel to use when translating can be set in the
<a href="#RobberLanguageTF_vowel">vowel</a> property.</p>

<p>See <a href="#robberLanguageTF_ex_1">this example</a>.]]></description>

<!-- Insert common properties -->
&taskFactory;
&generatorTaskFactory;

<!-- The propertyset element is a container for properties. -->
<propertyset>
<property name="source" required="yes">
  <description>The text file to translate.</description>

  <!-- Document the property's setter method. If the property has several setter
       methods, they can be listed after each other. -->
  <setter-method name="setSource">

  <!-- The setter method description may be omitted if it is obvious what the
       method does. -->
  <description>Set one text file.</description>

  <!-- List all setter method parameters. Note how the interpretation is
       documented. See the documentation for the ArgumentInterpreterLinksTF for
       information on the format of the argument interpreter reference. -->
  <parameter
    name="o" 
    type="Object"
    interpreter="|ai:ai_readable_file;InterpretAsReadableFileStrategy|">A
  text file.</parameter>
  </setter-method>
</property>

<property name="target" required="yes">
  <description>The target location where the translated file will be
  put.</description>

  <setter-method name="setTarget">
  <parameter 
    name="o"
    type="Object"
    interpreter=
      "|ai:ai_new_writable_file;InterpretAsNewWritableFileStrategy|">The
    target file location.</parameter>
  </setter-method>
</property>

<property name="vowel">
  <description>The vowel to use when translating.</description>
  <setter-method name="setVowel">
    <parameter name="c" type="char">The vowel</parameter>
  </setter-method>

  <!-- This property has a default value. -->
  <default-value><![CDATA[<code>o</code>]]></default-value>
</property>

<property name="translatedCharacters">
  <description>The collection of characters that are translated.</description>
  <setter-method name="addTranslatedCharacter">
    <description>Add one translated character.</description>
    <parameter name="c" type="char">The character to translate.</parameter>
  </setter-method>
  <!-- This setter method flattens the argument list. -->
  <setter-method name="addTranslatedCharacters">
    <description>Add one or several translated characters.</description>
    <parameter name="o" type="Object">One character or an
    array or collection of characters.</parameter>
  </setter-method>
  <setter-method name="clearTranslatedCharacters">
    <description>Clear the list of translated characters.</description>
  </setter-method>
</property>

</propertyset>

<examplesintro>For more examples, see somewhere else.</examplesintro>

<example id="robberLanguageTF_ex_1">

  <!-- This description will be used in the examples reference. -->
  <short-description>Translate all files in a directory hierarchy to the Robber
    Language.</short-description>

  <!-- This description is displayed above the example. -->
  <description><![CDATA[Translate all files in the directory hierarchy under
  <code>src</code> to the Robber Language, putting the translated files in a
    directory hierarchy under <code>target</code>.]]></description>

  <!-- Use an include tag to include the example code. The example text will be
       inserted by the IncludeFilesTask when building the documentation.
     
       By keeping examples in separate files, they are made easier to test. -->
  <code>|include:se.rövarspråket/src/doc/taskref/robberLanguageTF_ex1.js|</code>
</example>
</taskfactory>
</taskdoc>