Изготовление ant-сценария для запуска под Эклипсом

Делаем проект под Эклипс-проект, а в нем заводим DITA-файлы, а также файл build.xml.

Общий вид файла build.xml

Cодержимое файла build.xml должно выглядеть примерно так:

<?xml version="1.0" encoding="UTF-8" ?>

<project name="make_eclipsehelp" default="dita2htmlhelp" basedir=".">

  <property name="map.name" value="RfpManual" />

  <property environment="env" />
  <property name="dita.dir" value="${env.DITA_DIR}" />

  <target name="dita2htmlhelp">
    <!-- Генерация документации в виде Html Help, т.е. chm-файла -->
  </target>

  <target name="dita2pdf">
    <!-- Генерация документации в виде pdf-файла -->
  </target>

  <target name="dita2eclipsehelp">
    <!-- Генерация документации в виде Eclipse Help -->
  </target>

</project>

basedir устанавливается на папку, в которой лежит файл build.xml, т.е. на папку, в которой находится Эклипс-проект. И дальше все относительные пути отсчитываются от этой папки.

Дальше устанавливаются значения свойств map.name и dita.dir. Затем идут определения целей dita2htmlhelp, dita2pdf и dita2eclipsehelp для генерации результата в разных форматах.

Установка свойств

Свойству map.name присваивается имя map-файла, описывающего способ сборки выходного документа из частей. Это делается в строчках

  <property name="map.name" value="RfpManual" />

Затем свойству dita.dir присваивается путь к папке, где находится DITA OT. А это значение берется из переменной окружения DITA_DIR следующим образом:

  <property environment="env" />
  <property name="dita.dir" value="${env.DITA_DIR}" />

Тут есть тонкость. Значение переменная окружения DITA_DIR может (или даже должно?) оканчиваться на \, но при этом в dita.dir загадочным образом оказывается путь без последнего \!

Общие части в определениях целей

Во всех определениях целей есть определения свойств, общие для всех типов результатов:

      <property name="args.input" value="src/${map.name}.ditamap" />
      <property name="output.dir" value="." />
      <property name="dita.temp.dir" value="temp" />
      <property name="dita.extname" value=".dita"/>
      <property name="clean.temp" value="yes" />

• args.input - путь к файлу, где лежит map-файл, описывающий структуру результата.
• output.dir - папка, в которую надо писать выходные файлы.
• dita.temp.dir - папка для временных файлов.
• dita.extname - расширение для DITA-файлов (xml или dita).
• clean.temp - надо ли чистить папку временных файлов перед началом работы.

Генерация документации в виде Html Help, т.е. chm-файла

  <target name="dita2htmlhelp">
      <property name="args.input" value="src/${map.name}.ditamap" />
      <property name="output.dir" value="." />
      <property name="dita.temp.dir" value="temp" />
      <property name="dita.extname" value=".dita"/>
      <property name="clean.temp" value="yes" />
      <property name="args.css" value="src/RfpManual.css" />
      <property name="args.csspath" value="css" />
      <property name="args.copycss" value="yes" />
    </ant>
  </target>

• args.css - путь к файлу, в котором лежит css-шаблон для "подкрутки" внешнего вида результата.
• args.csspath - путь к папке, в которую будет помещен css-шаблон в результате.
• args.copycss - нужно ли копировать css-шаблон на новое место в результате.

Генерация документации в виде pdf-файла

  <target name="dita2pdf">
    <ant antfile="${dita.dir}${file.separator}build_dita2pdf.xml">
      <property name="args.input" value="src/${map.name}.ditamap" />
      <property name="output.dir" value="." />
      <property name="dita.temp.dir" value="temp" />
      <property name="dita.extname" value=".dita"/>
      <property name="clean.temp" value="yes" />
      <property name="args.fo.output.rel.links" value="no"/>
    </ant>
  </target>

• args.fo.output.rel.links - нужно ли генерировать в pdf-документе перекрестные ссылки, как это делается для html-результатов.

Генерация документации в виде Eclipse Help

  <target name="dita2eclipsehelp">
    <ant antfile="${dita.dir}${file.separator}build_dita2eclipsehelp.xml">
      <property name="args.input" value="src/${map.name}.ditamap" />
      <property name="output.dir" value="." />
      <property name="dita.temp.dir" value="temp" />
      <property name="dita.extname" value=".dita"/>
      <property name="clean.temp" value="yes" />
      <property name="args.css" value="src/RfpManual.css" />
      <property name="args.csspath" value="css" />
      <property name="args.copycss" value="yes" />
      <property name="args.eclipse.version" value="1.0" />
      <property name="args.eclipse.provider" value="Program Systems Institute, Pereslavl-Zalessky, Russia" />
    </ant>
  </target>

• args.css - путь к файлу, в котором лежит css-шаблон для "подкрутки" внешнего вида результата.
• args.csspath - путь к папке, в которую будет помещен css-шаблон в результате.
• args.copycss - нужно ли копировать css-шаблон на новое место в результате.
• args.eclipse.version - версия плагина, чтобы вставить ее в plugin.xml.
• args.eclipse.provider - имя провайдера плагина, чтобы вставить его в plugin.xml.