Deprecate outputFile.base in the docs

[stefan-jung]

Expected Behavior

The parameter outputFile.base is explained on PDF Parameters. This parameter is deprecated in org.dita.pdf2/build_template.xml#L144:

<target name="publish.map.pdf.init">
  <property name="inputFile" location="${dita.temp.dir}/${merged.file}"/>
  <!-- Deprecated since 3.0. Use args.output.base instead -->
  <condition property="outputFile.base" value="${args.output.base}" else="${dita.map.filename.root}">
    <isset property="args.output.base"/>
  </condition>
  <property name="artworkPrefix" value="${artwork.dir}"/>
</target>

Possible Solution

The docs should state that args.output.base should be used instead.

Steps to Reproduce

[infotexture]

We generate the parameter listings from the parameters that are included in each plug-in, so as long as a parameter is included in the code, it will appear in the docs.

So far, I don't think we have a programmatic means of listing replacements for deprecated parameters. The example above offers a clear alternative, but I'm not sure there's a consistent convention like this that we could rely on to annotate deprecated parameters with their recommended successors.

In the meantime, we can manually push in additional information like this to make the deprecation more visible in the docs.

@jelovirt Any other ideas? 🤔

[jelovirt]

@infotexture We already have support for deprecated="true" in plugin.xml, see for example https://github.com/dita-ot/dita-ot/blob/develop/src/main/plugins/org.dita.base/plugin.xml#L123. That should be added to https://github.com/dita-ot/dita-ot/blob/develop/src/main/plugins/org.dita.pdf2/plugin.xml#L25.

Then the code that generates the parameter listing should be improved to generate e.g "(Deprecated)" after the parameter name.

[infotexture]

Turns out we already add importance="deprecated" on params.xsl#L116-L118, and extension-points.xsl#L96-L98, so the info is there in the generated DITA source, but that attribute isn’t propagated to the HTML output.

I'll add a passthrough action to the DITAVAL files to preserve that attribute in the output, so we can style deprecated parameters and extension points with CSS.