Глава 3. Справочное руководство пользователя

Глава 3. Справочное руководство пользователя
Пред.		След.

1. Написание документов

Аннотация

Ниже представлен обзор формата конфигурационных файлов и элементов, необходимых в master.top.xml, чтобы работала система ревизий. Также в этом разделе подробно описаны все элементы, необходимые для создания документов для ваших проектов, от глобальных объектов до компиляции документа.

1.1. Конфигурационные файлы

Ниже представлен подробный обзор конфигурационных файлов Borges'а и их формат.

1.1.1. conf/author.xml

В этом файле содержится информация об авторе (писателе, переводчике и т.п.), который будет использовать эту копию репозитория. Подразумевается, что проект Borges хранится в репозитории CVS и используется многими людьми. Каждый автор должен настроить этот файл для своей собственной копии репозитория, чтобы пользоваться системой ревизий и быть в состоянии компилировать документы.

     <?xml version='1.0' encoding='ISO-8859-1'?>
      <author>
       <initials>AJ</initials>
       <lang>ru</lang>
     </author>

Элемент <initials> содержит идентификатор автора. Он определяется в файле conf/authors.xml. В противном случае это должно быть сделано: смотрите Раздел 1.1.2, «conf/authors.xml».
Элемент <lang> содержит предпочитаемый язык автора. Обратите внимание, что мы используем слово «предпочитаемый», потому что язык может быть переопределён параметром LANG= при выполнении компиляций.

1.1.2. conf/authors.xml

Система должна знать каждого «участника» (писателя, переводчика, корректора и т.п.). Кроме того Borges использует эту информацию для управления версиями и в списке авторов. Участники перечислены в conf/authors.xml изначально заполнены заначениями по умолчанию. Поэтому откройте authors.xml в своём любимом тектовом редакторе и введите свои данные. Ниже представлен пример профиля.

<?xml version="1.0" encoding="ISO-8859-1"?>
<authorgroup>
      <editor id="AJ">
        <firstname>Pavel</firstname><surname>Maryanov</surname>
        <affiliation>
          <address><email>acid_jack@ukr.net</email></address>
        </affiliation>
      </editor>
      <author id="pp">
        <firstname>Peter</firstname><surname>Pingus</surname>
        <affiliation>
          <address><email>peter@pingus.com</email></address>
        </affiliation>
      </author>
</authorgroup>

Этот файл должен строго придерживаться следующей стандартной структуры:

Тип участника <editor> используется для хранения профиля менеджера проекта. Он должен быть исключительно единственным. Этот человек будет получать только задачи, не назначенные больше никому, так что только он может присвоить задаче статус pending.
Тип участника <author> используется для всех других участвующих в проекте людей. Их может быть столько, сколько нужно.
Каждый участник должен иметь уникальный и понятный id, используемый для идентификации его в системе. Он должен состоять только из букв.
Адрес электронной почты будет использоваться для отправки участнику заданий, над которыми необходимо работать (см. Раздел 3, «Отправка писем авторам»).

1.1.3. conf/manual-default.xml

Этот файл будет использоваться в качестве шаблона для создания конфигурационных файлов определённых документов (Раздел 1.1.4, «manuals/My_Book/conf.xml»). В нём содержится конфигурационные параметры таблиц стилей, используемых по умолчанию при создании выходных PDF- и HTML-документов. Пожалуйста, обратитесь к Раздел 3, «Настройка стиля выходного документа» для получения дополнительной информации о том, как настроить таблицы стилей по умолчанию для удовлетворения своих потребностей.

<?xml version='1.0' encoding='ISO-8859-1'?>
<configuration omf.seriesid="">
  <makefile>$DISTDIR/backend/Makefile.DB</makefile>
  <style format="pdf" toolchain="jade">../../drivers/docbook-jadetex.dsssl</style>
  <style format="flat.html" toolchain="xsl">../../drivers/docbook-xhtml.xsl</style>
  <style format="html" toolchain="xsl">../../drivers/docbook-xhtml-chunk.xsl</style>

  <document id="">

    <style format="pdf"/>
    <style format="html"/>

    <language lang="en">
      <style format="pdf" toolchain="jade">../../drivers/db-jadetex-letter-en.dsssl</style>
    </language>
    <language lang="fr"/>
    <language lang="es"/>

    <exclude>multilingual</exclude>
  </document>

</configuration>

<makefile> определяет Makefile, содержащий специфические правила для документа определённого типа. По умолчанию это документы DocBook. $DISTDIR указывает на каталог, в который установлен Borges (по умолчанию это /usr/share/Borges/). Это позволяет вам полностью переопределить новый набор целей и легко пользоваться ими.
<style>: в этом примере в первых трёх элементах <style> содержится таблица стилей, используемая для трёх выходных форматов, по умолчанию поставляемых с Borges. В элементе <document> <style> сообщает, какие форматы должен быть сгенерированы при создании всех документов. И, наконец, существует возможность задать определённую таблицу стилей для определённого языка и определённого документа так, как это сделано в последнем элементе <style> в приведенном выше примере.
<document> содержит конфигурацию для первого суб-документа. Атрибут id должен быть оставлен пустым, он будет автоматически заполнен во время вставки документа.
<language> сообщает, на какие языки предполагается перевести этот суб-документ. Эта информация будет использована в задачах координации и создания документов.
<exclude> пояснение смотрите в Раздел 1.1.4, «manuals/My_Book/conf.xml». Флаг multilingual по умолчанию исключён. Он может быть использован в модулях для пометки данных, включаемых только в многоязычные документы (см. Раздел 1.2.5, «Многоязычные документы»).

Помните, что в этом файле просто содержится конфигурация по умолчанию для документов, которые будут вставлены в проект. Наиболее вероятно, что вам понадобится настроить эту конфигурацию после вставки документа (Раздел 1.1.4, «manuals/My_Book/conf.xml»).

1.1.4. manuals/My_Book/conf.xml

В этом файле содержится конфигурация определённого документа и таблицы стилей, используемых при создании выходных PDF- или HTML-документов, а также «алиасы» и исключаемая информация для получения различных документов из одного супердокумента. Файл основан на conf/manual-default.xml (Раздел 1.1.3, «conf/manual-default.xml»).

<?xml version='1.0' encoding='ISO-8859-1'?>
<configuration omf.seriesid="7a5f2ef8-3239-11d8-8574-a94a75e630dd">
  <makefile>$DISTDIR/backend/Makefile.DB</makefile>
  <style format="pdf" toolchain="jade">../../drivers/docbook-jadetex.dsssl</style>
  <style format="flat.html" toolchain="xsl">../../drivers/docbook-xhtml.xsl</style>
  <style format="html" toolchain="xsl">../../drivers/docbook-xhtml-chunk.xsl</style>

  <document id="My_Book">

    <style format="pdf"/>
    <style format="html"/>

    <language lang="en">
      <style format="pdf" toolchain="jade">../../drivers/db-jadetex-letter-en.dsssl</style>
    </language>
    <language lang="fr"/>
    <language lang="es"/>

    <exclude>Mac</exclude>
    <exclude>multilingual</exclude>
  </document>

  <document id="My_Book_Mac">

    <style format="pdf"/>
    <style format="html"/>

    <language lang="en">
      <style format="pdf" toolchain="jade">../../drivers/db-jadetex-letter-en.dsssl</style>
    </language>
    <language lang="fr"/>
    <language lang="es"/>

    <exclude>PC</exclude>
    <exclude>multilingual</exclude>
  </document>

  <document id="ML-Doc" multilang="//part">
    <style format="pdf"/>
    <language lang="en"/>
    <language lang="fr"/>
    <language lang="es"/>
    <exclude>unilingual</exclude>
  </document>
</configuration>

Мы уже видели (Раздел 1.1.3, «conf/manual-default.xml») назначение элементов этого файла. Теперь мы подробнее остановимся на использовании элемента <exclude> и увидим, как был сконфигурирован этот документ.

<exclude> содержит имя «флагов», исключаемых из документа при компиляции с условиями. Подробное описание смотрите в Раздел 1.2.4, «Специализированные книги для различных целей».

В приведенном выше примере manuals/My_Book/conf.xml при выполнении команды

make -C manuals/My_Book My_Book.pdf

будет скомпилирован файл PDF с именем manuals/My_Book/My_Book.pdf с исключением изо всех модулей всех элементов, отмеченных условием condition="Mac"; при выполнении

make -C manuals/My_Book My_Book_Mac.pdf

будет скомпилирован файл PDF под именем manuals/My_Book/My_Book_Mac.pdf с исключением всех элементов, отмеченных условием condition="PC".

И, в заключение, есть ещё третий документ, доступный только в PDF, об этом нам говорит атрибут multilang, т.е. это документ, содержащий разные части на разных языках в пределах одной книги. В этом случае документ ML-Doc.pdf будет иметь только тело (<part>), повторяющееся на английском, французском и испанском языках. За дополнительной информацией обращайтесь, пожалуйста, к Раздел 1.2.5, «Многоязычные документы».

1.1.5. conf/repository.xml

Этот файл является самым важным конфигурационным файлом, потому он находится на самом верхнем уровне всего проекта Borges. Мы подробно рассмотрим здесь образец конфигурационного файла и увидим, что в нём можно изменить вручную.

 <?xml version='1.0' encoding='iso-8859-1'?>
<configuration>
  <repository>
    <title>Documentation Project</title>
    <borges>0.11.2</borges>
    <paths>
      <modules>modules</modules>
      <manuals>manuals</manuals>
    </paths>
    <doctype>-//OASIS//DTD DocBook XML V4.2//EN</doctype>
    <dtd>http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd</dtd>
    <outputs>
      <makefile>$DISTDIR/backend/Makefile.DB</makefile>
    </outputs>
    <manuals>
      <manual>Book</manual>
      <manual status="inactive">Took</manual>
    </manuals>

    <pool id="Printer">
      <document id="Book/Book">
        <language lang="en">
          <style format="pdf"/>
        </language>
        <language lang="fr">
          <style format="pdf"/>
        </language>
      </document>
    </pool>

    <languages>
      <lang>en</lang>
      <lang>fr</lang>
      <lang>es</lang>
    </languages>

    <revisions>
      <original>
        <type role="1time">
          <name>write</name><author>tbn</author><weight>10</weight>
        </type>
        <type role="2time">
          <name>update</name><author>tbn</author><weight role="proportional">8</weight>
        </type>
        <type>
          <name>tproof</name><author>tbn</author><weight>4</weight>
        </type>
        <type role="2translate">
          <name>pproof</name><author>tbn</author><weight>2</weight>
        </type>
        <type>
          <name>ispell</name><author>tbn</author><weight>1</weight>
        </type>
        <type>
          <name>lproof</name><author>tbn</author><weight>4</weight>
        </type>
      </original>
      <translation>
        <type role="1time">
          <name>translate</name><author>tbn</author><weight>8</weight>
        </type>
        <type>
          <name>synch</name><author>tbn</author><weight role="proportional">6</weight>
        </type>
        <type>
          <name>ispell</name><author>tbn</author><weight>1</weight>
        </type>
        <type>
          <name>lproof</name><author>tbn</author><weight>4</weight>
        </type>
      </translation>
      <cost>0.01</cost>
    </revisions>
   </repository>
 </configuration>

Теперь мы раздел за разделом рассмотрим, что вы можете изменить и как много.

<title> содержит название проекта. Используется в качестве заголовка в отчётах, создаваемых функциями генерации отчётов Borges. Обязательный.
<doctype> содержит символический DOCTYPE шаблона DTD, используемого для всех документов и модулей этого проекта. На один проект может быть только один DTD. Убедитесь, что вы используете один и тот же DTD в мастер-файлах своих документов. Если вы измените его, вы должны будете обновить соответственно все свои мастер-файлы. Обязательный.
<dtd> содержит URI шаблона DTD, указанного в параметре <doctype> выше. Обязательный.
<outputs> содержит местоположение файлов Makefile с шаблонами выходных документов. Файлы шаблонов выходных документов используются для поддержки Borges'ом различных DTD. На момент написания этого руководства поддерживался только DTD DocBook (отсюда расширение файлов .DB). Вы можете поместить сколь угодно много элементов <makefile>, указав в них правила без конфликтов. Обязательный.
Замечание
Вы также можете указать Makefile, используемый на основе супердокумента (см. Раздел 1.1.4, «manuals/My_Book/conf.xml»).
<manuals> содержит имя каталога различных документов, по одному элементу <manual> на документ. Это автоматически управляется целью adddoc (Раздел 3.2.4, «Вставка нового документа»).
Предостережение
Крайне рекомендуется не добавлять вручную здесь никакие руководства. Вместо этого используйте команду make adddoc. См. Раздел 3.2.4, «Вставка нового документа».
Подсказка
Даже, если GNU/Linux поддерживает символ пробела в путевых именах, рекомендуется не использовать их здесь. Вы можете использовать дефис (-) или символ подчёркивания (_) в качестве разделителя слов в путевых именах.
В нашем примере документ Took помечен атрибутом status="inactive". Это означает, что это руководство не будет учтено при создании отчётов или выходных документов.
<pool>: этот элемент, который может повторяться любое количество раз, используется для определения наборов документов для особых издательских носителей. См. Раздел 2.2.2, «Для набора документов».
<languages> содержит языки, поддерживаемые всеми документами, по одному элементу <lang> на язык в виде двухбуквенного ISO-кода этого языка (в нижнем регистре).
Предостережение
Крайне рекомендуется не добавлять вручную здесь никакие языки за исключением первого. Вместо этого используйте команду make addlang. См. Раздел 1.4, «Добавление в систему новых языков».
Здесь вы можете сделать две вещи:
- Изменить порядок языков: первый является языком по умолчанию и будет использоваться в некоторых редких случаях, когда системе нужен язык по умолчанию. Тогда порядок определяет очерёдность языков в отчётах.
- Как показано для документов выше, атрибут status="inactive" может быть добавлен в элемент <lang> для его временного отключения...
<revisions> содержит типы ревизий, управляемых системой ревизий. Их порядок определяет рабочий процесс модулей документа. Представленный здесь рабочий процесс по умолчанию поставляется с Borges. Существует возможность изменить названия этапов и их число, удалив или добавив новые этапы. Сначала мы проанализируем, как закодирован рабочий процесс по умолчанию (Рисунок 3.1, «Стандартный жизненный цикл модуля Borges»), а затем посмотрим, как его можно настроить. Рабочий процесс делится на два этапа:
оригинал
Это рабочий процесс, результатом которого являются оригинальные модули. В нём присутствуют два особых состояния. Первое, отмечаемое как role="1time", требуется только один раз (обычно первое написание) и для обновлений модуля больше не требуется. По завершении этапа, отмечаемого как role="2translate", будет запущен перевод на всех других языках, чтобы переводчики могли начать работать. И, наконец, задание, отмеченное как role="2time", будет доступно для будущих релизов только после написания модуля.
перевод
Это рабочий процесс, результатом которого являются переведённые модули. Состояние, отмечаемое как role="1time", требуется только один раз (обычно первоначальный перевод) и для обновлений модуля больше не потребуется.
Смотрите Рисунок 3.1, «Стандартный жизненный цикл модуля Borges», чтобы узнать, как эти задачи взаимодействуют с другими. Каждый рабочий процесс состоит из задач со следующей информацией:
- <name> содержит название ревизии системы. Это обозначения, которые мы даём ревизиям рабочего процесса по умолчанию: write - первоначальное написание модуля; translate - первоначальный перевод модуля; tproof - техническое чтение корректуры модуля; pproof - педагогическое чтение корректуры модуля; ispell - проверка орфографии модуля и lproof - языковое чтение корректуры модуля. После этого следует этап update - обновления оригинальных модулей в будущих релизах, и synch - синхронизация переводов с оригиналом.
- <author> содержит инициалы автора «по умолчанию» или идентификатор типа ревизии. Если для типа ревизии автор ещё не назначен, должен быть использован tbn (To Be Named).
- <weight> используется для оценки относительной стоимости задачи по отношению к задаче написания. Например, задача педагогического чтения корректуры (pproof) имеет относительный коэффициент 2 по отношению к задаче write (10). Это означает, что стоимость педагогического чтения корректуры мы оцениваем в 5 раз меньше, чем написание текста (см. Раздел 4, «Бухгалтерские отчёты»). Естественно вы можете использовать здесь любые значения.
  Вы могли заметить, что некоторые коэффициенты добавляются к атрибуту role="proportional". Это означает, что стоимость этой задачи будет увеличена при внесении изменений в этот модуль. Смотрите Раздел 4, «Бухгалтерские отчёты» для уточнения способа этих вычислений.
Элемент <revisions> повторяется для каждого определённого в системе языка. Это позволяет определить отдельных авторов для каждого языка. Смотрите Раздел 1.4, «Добавление в систему новых языков», чтобы узнать о том, как определить этих авторов во время добавления языка.
<cost> - это оценочная стоимость одного написанного символа для задачи написания (см. Раздел 4, «Бухгалтерские отчёты»). Все другие стоимости будут получены из этой с учётом соответствующих коэффициентов. Укажите своё собственное значение.

1.1.6. master.top.xml и система ревизий

Часть <revhistory> файла master.top.xml играет важную роль в системе ревизий Borges.

Ниже представлен образец части <revhistory>:

      <revhistory>
       <revision lang="en">
        <revnumber>1</revnumber>
        <date>2002-06-04</date>
        <authorinitials>pp</authorinitials>
        <revremark>First Draft</revremark>
       </revision>
       <revision lang="fr">
        <revnumber>1</revnumber>
        <date>2002-06-14</date>
        <authorinitials>pt</authorinitials>
        <revremark>Begin French Translation</revremark>
       </revision>
       <revision lang="es">
        <revnumber>1</revnumber>
        <date>2002-06-10</date>
        <authorinitials>rp</authorinitials>
        <revremark>Begin Spanish Translation</revremark>
       </revision>
      </revhistory>

Каждый пункт <revision> содержит данные, связанные с одним из переводов документа. Он имеет атрибут lang с двухбуквенным ISO-кодом языка (в нижнем регистре). Первый пункт автоматически создаётся во время генерации документа (см. Раздел 3.2.4, «Вставка нового документа»), а следующие за ним пункты добавляются переводчиками для записи даты, когда был начат перевод документа:

<revnumber> содержит номер ревизии (или номер редакции) документа. Соответствует текущему релизу документа (см. Раздел 4.3, «Старший релиз проекта»). Обязательный.
<date> содержит дату, с которой началась работа на соответствующем языке. Используется функцией создания отчётов Borges'а для оценки дат завершения работ над ревизиями; в приведенном выше примере работа нат французской версией началась 10^го июня 2002 года. Формат: ГГГГ-ММ-ДД. Обязательный.
<authorinitials> содержит инициалы (уникальный идентификатор) автора, отвечающего за эту ревизию. Необязательный.
<revremark> содержит замечания к самой ревизии. Это замечание не выводится на печатных документах посредством стиля DSSSL, по умолчанию поставляемого с Borges. Поэтому вам понадобится настроить таблицу стилей, если вы хотите, чтобы замечания были напечатаны. Необязательный.

1.2. Функции создания документов

В следующих разделах будут подробно рассмотрены функции Borges для создания документов. Разделы представлены безо всякого порядка.

1.2.1. Глобальные объекты

Глобальные объекты - это объекты, которые вы собираетесь использовать вообще безо всяких изменений во всех версиях проекта и и/или во всех своих проектах. Они находятся в каталоге entities/ и представляют собой XML-файлы с расширением .ent

Поместите все объекты, которые не будут изменяться на всех языках и во всех документах, в каталог entities/.

Поместите все объекты, которые будут изменяться на всех языках, но не будут изменяться в документах, в каталог entities/ll/, где ll - двухбуквенный ISO-код языка (в нижнем регистре).

Хорошие кандидаты на роль глобальных объектов:

названия команий;
названия программ (ПО);
названия операционных систем;
большинство акронимов^[1].

1.2.2. Изображения

Вставка изображений в свои документы так же проста, как вставка элементов <figure> в свои модули. Например:

     <figure>
      <title>Обалденный рисунок</title>
      <mediaobject>
       <imageobject>
        <imagedata align="center" fileref="images/image_file_name.png format="PNG"/>
       </imageobject>
      </mediaobject>
     </figure>

вставит изображение PNG из файла с именем image_file_name.png, выровненным по центру страницы с заголовком «Обалденный рисунок» (без кавычек).

Нет необходимости говорить, что Borges сам позаботится о поиске изображения в соответствующем каталоге images/ll/, где ll - двухбуквенный ISO-код языка (в нижнем регистре), на котором будет откомпилирован модуль.

Вы также можете поместить изображения, нейтральные в отношении языков, в каталог images/, и Borges будет брать их оттуда.

Доступные форматы изображений для ваших документов: PNG (format="PNG"), PDF (format="PDF") и EPS (format="EPS"). Borges автоматически поместит их в нужное место. Если требуемый формат недоступен, Borges автоматически позаботится о преобразовании изображения в нужный формат. Поддерживаемые форматы входных изображений:

.png: Portable Network Graphic (растровый формат);
.jpg: Сжатый растровый формат, пригодный для фотографий;
.eps: Encapsulated PostScript (векторный формат);
.pdf: Encapsulated Portable Document Format (векторный формат);
.fig: родной выходной формат приложения для создания диаграмм xfig.

Отсутствующие изображения

В случае, если вы вставили изображение в модуль и забыли сделать сам рисунок, система заменит его стандартным изображением, чтобы не нарушать компиляцию. Изображение, используемое по умолчанию - images/missing.jpg, и вы можете заменить его на любое другое.

Вдобавок, всякий раз, когда Borges находит отсутствующее изображение, он сообщает об этом в текстовом файле <manual>.missing.xx.img. Таким образом, если вы только что скомпилировали документ (скажем, UserGuide) на французском языке и обратили внимание, что некоторые изображения отсутствуют (вместо них стандартный рисунок), список отсутствующих изображений вы можете получить из файла manuals/UserGuide/UserGuide.missing.fr.img. Вы также можете непосредственно сгенерировать этот файл для проверки наличия всех изображений при помощи команды make -C manuals/UserGuide/ UserGuide.missing.fr.img

1.2.3. Поддержка индекса

DocBook в состоянии сгенерировать автоматический индекс (алфавитный указатель), собрав все индексные термины, найденные в исходном документе. Borges автоматически создаст такой индекс, запрошенный вами в мастер-документе. Если вы хотите, чтобы индекс был добавлен в конец вашей книги, просто добавьте в конец вашего файла master.top.xml следующее:

   <index id="index">
     <title>Алфавитный указатель</title>
     <para>Автоматический индекс.</para>
   </index>
</book>

1.2.4. Специализированные книги для различных целей

Часто вам нужно сделать небольшие изменения в своей книге, рассчитанной на разных читателей, например, техническое руководство для семейства продуктов с небольшими отличиями между ними.

Так, вместо того, чтобы писать разные книги для разных аудиторий, лучше было бы иметь возможность написать один набор модулей для всех читателей с исключёнными частями из разных документов для каждой из аудиторий.

Borges позволяет это сделать, благодаря «компиляции с условиями». Компиляции с условиями позволяет вам «пометить» некоторые части своих модулей или весь модуль, чтобы исключить их в определённых компиляциях, но не в остальных.

Давайте рассмотрим пример. Вы пишете руководство пользователя для операционной системы Tortoise, работающей на обеих архитектурах Intel и Sparc. Между обоими руководствами существуют только небольшие отличия.

Вам нужно только добавить атрибут condition="i386", чтобы пометить элемент (раздел, параграф, фразу, замечание, предупреждение, подсказку и т.п.) как действительный только для версии Intel. Пометьте аналогичным образом элементы, имеющие отношение к версии Sparc, атрибутом condition="sparc". Если элемент представляет собой весь модуль, добавьте атрибут в мастер-файл:

        <sect1 condition="i386">
         <title>Какой-то заголовок</title>
         <para role="module">some_sect-sect1</para>
         <para>Введение в ОС Tortoise, подсветка спецификаций Intel.</para>
        </sect1>

Далее вам нужно сообщить Borges'у, как получить оба руководства пользователя из супердокумента Tortoise-UserGuide. Это выполняется в конфигурационном файле супердокумента Раздел 1.1.4, «manuals/My_Book/conf.xml». В нашем примере этот файл может быть таким:

    <?xml version='1.0' encoding='ISO-8859-1'?>
    <configuration>
     <stylesheet>
      <dssslprint>../drivers/docbook-jadetex.dsssl</dssslprint>
      <xslxhtmlchunk>../drivers/docbook-xhtml-chunk.xsl</xslxhtmlchunk>
      <xslxhtmlflat>../drivers/docbook-xhtml.xsl</xslxhtmlflat>
     </stylesheet>
     <manuals>
      <manual>
       <lang>en</lang>
       <format>html</format>
       <exclude>sparc</exclude>
      </manual>
       <manual id="Tortoise-Sparc">
       <lang>en</lang>
       <format>html</format>
       <exclude>i386</exclude>
      </manual>   
     </manuals>
    </configuration>

После этого команда

     make -C manuals/My_Book Tortoise-i386.pdf

скомпилирует всю книгу в PDF, отбросив элементы с условием condition="sparc".

1.2.5. Многоязычные документы

1.2.6. Проверка документов

Время от времени рекомендуется, чтобы вы проверяли свои модули на правильность кода XML. Выполните

make -C manuals/My_Book master.validate

чтобы проверить весь свой супердокумент для своего предпочитаемого (рабочего) языка.

Подсказка

Используйте параметр LANG=ll для проверки с другим языком, отличном от предпочитаемого. ll - двухбуквенный ISO-код (в нижнем регистре) языка проверяемого супердокумента.

Проверка обычного мастер-документа не означает, что все ваши суб-документы тоже будут правильными. Чтобы убедиться, что документ Tortoise-i386 на самом деле является правильным (с учётом исключений и индексов), выполните:

make -C manuals/My_Book Tortoise-i386.flat.validate

И, наконец, если вы хотите проверить только один модуль, выполните:

make -C modules/en tortoise-install-sect1.validate

Предостережение

На данный момент при проверке модуля правильность перекрёстных ссылок (<xref>) не проверяется.

1.2.7. Создание переведённых параграфов, прозрачных для системы ревизий

При переводе модуля на другой язык, часто возникает ситуация, когда переводчик хочет добавить сноску с замечаниями или несколько поясняющих слов в отдельном параграфе. Также некторые лицензии (например, GPL и GFDL) требуют, чтобы вы включили некоторую их часть на оригинальном языке.

Автоматизированная система управления ревизиями Borges'а сообщит о разнице между переведённым и оригинальным модулями только из-за того, что были добавлены эти сноски/параграфы, даже если они корректные или в некоторых случаях являются необходимыми; что ж, тогда каким образом вы можете сделать эти параграфы «невидимыми» для системы ревизий?

Borges решает эту «проблему» элегантным способом, не нарушающим совместимости с DocBook, путём использования атрибута revision="-1". Например:

<para revision="-1">En otro idioma</para>

исключит этот параграф (в этом примере на испанском) при сравнении с оригиналом для поиска различий в ревизиях.

Таким способом вы можете иметь такие «дополнительные» параграфы в своём переводе, не беспокоясь о неверных отчётах по ревизиям.

1.3. Функции изменения документов

Всякий раз, когда вы изменяете структуру супердокумента, необходимо информировать систему о таких модификациях. При этом будут отдельно создаваться шаблоны модулей для добавленных модулей.

Просто выполните команду make alltemplates.

Если ваш проект использует CVS, новые шаблоны модулей будут автоматически добавлены в репозиторий CVS. См. Раздел 2.1, «Команды с изменённым поведением».

1.4. Добавление в систему новых языков

Когда один из ваших документов нуждается в переводе, или вы просто решили, что один из ваших документов должен быть переведён, об этом новом языке нужно сообщить системе. Это выполняется одной командой:

make addlang NEWLANG=ll

объявит новый язык ll^[2] документа для всего проекта. На самом деле при этом будут выполнены следующие задачи:

обновлён conf/repository.xml;
созданы все языковые каталоги для модулей, изображений, объектов и т.д.;
скопированы файлы объектов из используемого по умолчанию (первый в списке языков в главном конфигурационном файле) в новые языковые каталоги;
созданы шаблоны всех модулей для этого нового языка для всех определённых документов;
добавлены все новые файлы в репозиторий CVS, если он доступен. Обратите внимание, что вам ещё понадобится вручную зафиксировать эти файлы;

После этого переводчики должны будут:

Перевести объекты в manuals/My_Doc/ll/*.ent.
Перевести объекты в entities/ll/*.ent.
Перевести модули в modules/ll/*.xml;
Сделать скриншоты и перевести диаграммы из images/xx/ в images/ll/, где xx - другой язык, для которого изображения уже были созданы.

^[1] Акронимы используются «практически» без изменений во всех языках/проектах. Акроним, который изменяется, - это, например, ISDN, который на испанском звучит как RDSI.

^[2] ll - двухбуквенный ISO-код этого языка. См. ISO 639.

Пред.	Уровень выше	След.
3. Создание нового проекта	Начало	2. Создание конечных документов