Enhance dita command example for Ant with optional arguments

[stefan-jung]

This is the snippet:

<macrodef name="dita-cmd">
    <attribute name="input"/>
    <attribute name="format"/>
    <attribute name="propertyfile"/>
    <sequential>
      <exec executable="${dita.dir}/bin/dita">
        <arg line="-i @{input} -f @{format} -propertyfile @{propertyfile}"/>
      </exec>
    </sequential>
  </macrodef>

Unfortunately the Ant <macrodef> is not handy for using optional attributes. So, if you'd like to create a macro that also supports --filter, like so:

<macrodef name="dita-cmd">
    <attribute name="input"/>
    <attribute name="format"/>
    <attribute name="filter"/>
    <attribute name="propertyfile"/>
    <sequential>
      <exec executable="${dita.dir}/bin/dita">
        <arg line="-i @{input} -f @{format} --filter=@{filter} --propertyfile=@{propertyfile}"/>
      </exec>
    </sequential>
  </macrodef>

... it would break, if you'd like to call the macro without a filter attribute.

I recommend to add a note that recommends to pass filter files by using the args.filter property in the propertyfile.

[infotexture]

This behavior is not peculiar to the filter parameter, so I'm not sure it's worth mentioning that by name. As the Ant MacroDef task docs explain:

The values of the attributes get substituted into the templated task.
The attributes will be required attributes unless a default value has been set.

I'll add a note to clarify that any optional parameters should be defined in .properties files.