Аннотация
Мы сначала опишем этапы, необходимые для настройки Borges для нового проекта, а затем представим пошаговый пример.
Сначала вам нужно создать скелет нового проекта на основе предоставленного шаблона, как описано в Раздел 2, «Первые шаги»:
$ /usr/share/Borges/bin/configure ~/Новый_проект ru 2.1 $ cd ~/Новый_проект
Вы должны заменить ru на код языка, который вы хотите использовать по умолчанию в своей системе, если это уже не русский. Аналогичным образом 2.1 - это начальная версия документации, над которой вы начинаете работать. Если ничего не указано, будет использована 1.0.
Затем вы должны выполнить следующие этапы (подробнее см. ниже Раздел 3.2, «Пошаговый пример»):
Объявите языки, которые планируется задействовать в этом проекте, кроме языка по умолчанию.
Подготовьте мастер-файл. Должен быть создан и отредактирован мастер-файл, описывающий структуру вашего проекта.
Перечислите начальных участников, задействованных в проекте.
Определите объекты. Должны быть определены объекты заголовков и имён (например, имена приложений, названия компаний и т.п.). О важности объектов рассказано в Раздел 3.2.6, «Определение объектов» и в Раздел 1.2.1, «Глобальные объекты».
Создайте руководящие указания для писателей. Руководящие указания - это PDF- или HTML-файл, откопилированный из мастер-файла, в котором находится структура вашего проекта. После создания файл следует же прочитать при помощи подходящей утилиты (например, Xpdf или Acrobat Reader), чтобы проверить его правильность.
Назначьте задания каждому из участников. В идеале вы должны теперь обладать возможностью назначать ответственных для каждой отдельно взятой задачи жизненного цикла каждого модуля.
Напишите модули и создайте изображения. Теперь авторы могут начать писать различные модули, составляющие ваш проект, и создавать изображения для модулей (если необходимо).
Проверьте результат. Вы можете проверить состояние выполненных работ по своему проекту (написание, перевод и т.д.), компилируя время от времени проект и читая полученный PDF.
В следующем разделе представлен пошаговый пример для разъяснения описанных выше пунктов.
Представим, что вы хотите начать новую книгу под названием «My_Book», состоящую из предисловия и двух глав: первая из двух разделов, а вторая - из трёх. Вы также хотите включить одно приложение и хотите, чтобы ваша книга была переведена на француский и испанский языки.
Что ж, вот, что вы должны сделать, шаг за шагом.
Во всех следующих примерах для упрощения в файлах опущены комментарии. К счастью все конфигурационные файлы имеют собственную документацию, поэтому вы всегда можете обратиться к ней, чтобы узнать о какой-либо определённой конфигурационной опции. Вы можете обратиться к Раздел 1.1, «Конфигурационные файлы» для получения информации о конфигурационных файлах.
Во всех примерах командных строк подразумевается, что ваш текущий каталог - ~/Новый_проект/ (для проверки вы можете воспользоваться командой pwd).
Borges разработан для управления несколькими руководствами и языками; чтобы определить детали вашего проекта, он использует файл с именем repository.xml, находящийся в каталоге conf/.
Редактировать главный конфигурационный файл на данном этапе не обязательно. Вы можете пока что оставить значения по умолчанию и вернуться назад, когда вам действительно понадобится изменить параметры.
Файл conf/repository.xml вашего нового проекта должен выглядеть примерно так:
<?xml version="1.0" encoding="ISO-8859-1"?>
<configuration>
<repository>
<title>Documentation Project</title>
<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>
</manuals>
<languages>
<lang>en</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>
Файл снабжён прекрасными пояснениями (для ясности комментарии здесь были убраны), однако на некоторые моменты следует обратить внимание. В разделе <manuals> перечислены все документы (по одному пункту <manual> на документ), с которыми работает Borges. В разделе <languages> перечислены все поддерживаемые языки для всех проектов (по одному пункту <lang>, содержащему двухбуквенный код ISO, для каждого из языков).
Документ еще не определён и нет языка, за исключением языка по умолчанию, который вы пожелали использовать для своего проекта. Позже из командной строки будут добавлены другие документы и языки.
Списки <manuals> и <languages> управляются Borges'ом и вы не должны изменять их вручную. То же самое касается элемента <borges>, который используется для записи версии Borges, используемой репозиторием.
Раздел <revisions> определяет рабочий процесс документа, представляющий «жизненный цикл» модулей или «этапы», через которые должны пройти все модули документа. Дополнительную информацию смотрите в Раздел 1.1.5, «conf/repository.xml».
Это выполняется одной единственной командой. Т.к. нам кроме английского мы хотим добавить ещё французский и испанский языки, нам потребуется выполнить:
make addlang NEWLANG=fr make addlang NEWLANG=es
По сути цель addlang выполнит следующие действия:
обновит conf/repository.xml;
создаст все каталоги, предназначенные для хранения файлов, имеющих отношение к языку (в modules/ entities/ и images/) и заполнит их стандартными файлами;
создаст все шаблоны модулей для этого нового языка для всех определённых документов;
добавит новые файлы в репозиторий CVS, если он доступен.
Цель addlang имеет дополнительные опции, за дополнительной информацией обращайтесь к Раздел 1.4, «Добавление в систему новых языков».
Мы уже много говорили о «структуре документа», не так ли? Ну что ж, пришло время определить её. Нам нужно создать файл с именем master.top.xml. Вы можете скопировать /usr/share/Borges/Sample/master.top.xml в ~/Новый_проект/master.top.xml и отредактировать его как вам угодно.
Файл master.top.xml для вашего проекта должен выглядеть примерно так:
<?xml version='1.0' encoding='koi8-r'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"/usr/share/sgml/docbook/xml-dtd-4.2/docbookx.dtd"[
<!ENTITY % entities SYSTEM "entities">
%entities;
]>
<book id="My_Book" lang="⟨">
<title>&book-title;</title>
<preface role="module" id="legal-notice">
<para>Вставьте сюда содержимое раздела юридического замечания
разработчика. Если не всё здесь может поместиться на
физической странице, задайте вопрос команде.</para>
</preface>
<chapter>
<title>&chapter-1-title;</title>
<sect1 role="module" id="chap1-sect1-section">
<title>Заголовок первой главы</title>
<para>Напишите здесь содержимое главы 1, раздела 1</para>
</sect1>
<sect1 role="module" id="chap1-sect2-section">
<title>Заголовок второй главы</title>
<para>Напишите здесь содержимое главы 1, раздела 2</para>
</sect1>
</chapter>
<chapter>
<title>&chapter-2-title;</title>
<sect1 role="module" id="chap2-sect1-section">
<title>Заголовок первого раздела второй главы</title>
<para>Напишите здесь содержимое главы 2, раздела 1</para>
</sect1>
<sect1 role="module" id=""chap2-sect2-section>
<title>Заголовок второго раздела второй главы</title>
<para>Напишите здесь содержимое главы 2, раздела 2</para>
</sect1>
<sect1 role="module" id="chap2-sect3-section">
<title>Заголовок третьего раздела второй главы</title>
<para>Напишите здесь содержимое главы 2, раздела 3</para>
</sect1>
</chapter>
<appendix role="module" id="app1-appendix">
<title>Заголовок первого приложения</title>
<para>Напишите здесь дополнительную интересную информацию</para>
</appendix>
</book>
Если попробовать представить себе это в «модульном» виде, то можно сказать, что книга содержит: заголовок, предисловие, главы и приложения. Таким образом, это как раз то, что представлено в приведенном выше примере master.top.xml, ни больше, ни меньше.
В конце концов наш мастер-документ выглядит как стандартный документ DocBook. Однако следует сделать ещё одно замечание: атрибут role="module". Наличие этого атрибута у элементов (обычно sectX, chapter, appendix) означает, что они управляются Borges'ом.
<sect1 role="module" id="chap1-sect1-section">
<title>Заголовок первого раздела</title>
<para>Напишите здесь содержимое главы 1, раздела 1</para>
</sect1>
будет использован для создания шаблона модуля. Он будет показан как есть в руководящих указаниях документа, но будет заменён содержимым модуля, как только последнее будет написано автором в модуле chap1-sect1-section.xml. Обратите внимание, что название модуля взято из ID элемента структурирования.
Такой способ получения результирующего документа непосредственно из его спецификаций обеспечивает отсутствие разногласий между спецификациями и конечным результатом. Более того, система публикует эти директивы для писателей в файле спецификации и в шаблонах модулей. В финальном документе они исчезнут. Не стесняйтесь создавать такие руководящие указания нужной вам длины.
Вам может понадобится изменить объявление XML SYSTEM DTD-шаблона DocBook ("/usr/share/sgml/docbook/xml-dtd-4.2/docbookx.dtd") согласно условиям вашей системы. Обратите внимание, что, если вы вы используете другую версию DTD, вам понадобится соответственно обновить номер версии в элементах doctype и dtd главного конфигурационного файла.
Теперь, когда структура документа определена, система может создать необходимые для этого нового документа каталоги и файлы. Всё это выполняется одной единственной командой:
make adddoc doc=My_book master=~/Новый_проект/master.top.xml
при этом будет создан новый документ My_Book на базе мастер-файла ~/Новый_проект/master.top.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>
Замените существующие данные на свои собственные, возможно, удалив при этом элемент <author>, если в данный момент вы один работаете над этим проектом. Убедитесь в уникальности используемых ID.
Дополнительную информацию о структуре этих файлов смотрите в Раздел 1.1.2, «conf/authors.xml».
Теперь, если вы это этого ещё не сделали, пора сообщить системе, кто вы такой в файле conf/author.xml (см. Раздел 1.1.1, «conf/author.xml»).
Этот этап является необязательным и может быть выполнен в процессе написания документов.
Должны быть определены объекты проекта и документов. Объекты проекта являются общими для всех документов, например: названия компьютерных программ. Объекты документов используются только в отдельных документах. Все файлы объектов являются XML-файлами. Файлы объектов должны иметь расширение .ent.
Файлы объектов проекта находятся в каталоге entities/.
Главные файлы объектов находятся в каталоге manuals/My_Book/ll/, где ll - двухбуквенный ISO-код языка. В нём должны быть определены объекты, определённые в файле master.top.xml.
Подробно глобальные объекты рассмотрены в Раздел 1.2.1, «Глобальные объекты».
Когда вы добавляете в репозиторий новый супердокумент, строки, найденные в мастер-файле и подлежащие переводу, автоматически преобразовываются в объекты, которые были созданы в ll/strings.ent. Затем вам просто нужно открыть этот файл и наполнить его своим содержимым. По умолчанию Borges заполняет содержимое объектов как FILL ME: имя-объекта.
Ниже представлен пример файла strings.ent:
<?xml version='1.0' encoding='KOI8-R'?> <!ENTITY e-mail "E-mail:"> <!ENTITY web "Веб:">
make -C manuals/My_Book master.top.pdf LANG=en
и проверьте полученный PDF в своей любимой программе просмотра PDF.
Вы также можете выполнить команду
make -C manuals/My_Book master.top.flat.html LANG=en
чтобы создать указания для писателей в формате HTML.
Если всё прошло удачно, вы увидите книгу с оглавленем, всеми главами и разделами и написанными вами указаниями.
По умолчанию задания назначаются людям, объявленным в главном конфигурационном файле (Раздел 1.1.5, «conf/repository.xml»). Вам может понадобится переназначить задания, в осообенности те, что были назначены tbn'у. Обратитесь к Раздел 4.1.3, «Назначение заданий», чтобы узнать, как сделать это. Однако этот этап является необязательным.
Всё, что теперь осталось сделать - наполнить свою книгу содержимым: напишите модули и создайте изображения и/или схемы, которые будет содержать ваша книга. При необходимости должны быть созданы и правильно заполнены новые файлы объектов.
Итак, откройте файлы модулей XML (например, modules/en/chap2-sect1-section.xml с первым разделом второй главы книги на английском языке) в своём любимом текстовом редакторе и начинайте наполнять его содержимым. Мы не будем рассказывать вам здесь, как использовать DocBook, в Интернете достаточно превосходного материала о нём. Начните с посещения The DocBook Wiki.
Если вы используете в своих модулях объекты, убедитесь, что вы создали новый файл с ними (например, файл entities/ru/acronym-list.ent с объектами для акронимов на русском). Обратитесь к Раздел 1.2.1, «Глобальные объекты» для получения дополнительной информации об объектах.
Также Borges позволяет использовать изображения и схемы. Поддерживаемые форматы: PNG и JPEG (растровые изображения), EPS (векторная графика) и схемы XFig. Обратитесь к Раздел 1.2.2, «Изображения» для получения дополнительной информации об изображениях.
Общие для всех языков изображения и чертежи должны находится в каталоге images/, а изображения и схемы для каждого из языков должны находиться в каталогах images/ll/, где ll - двухбуквенный ISO-код языка.
И в заключение вы должны проверить результаты. Выполните команду
make -C manuals/My_Book master.pdf LANG=en
чтобы скомпилировать документ в формат PDF и откройте его в своей любимой программе чтения PDF.
Вы также можете скомпилировать документ в формате HTML в виде одного (flat) или нескольких (chunked) HTML-файлов. Команда
make -C manuals/My_Book master.html LANG=en
скомпилирует документ, разибитый на несколько HTML-файлов. Откройте в своём веб-браузере файл ~/Новый_проект/manuals/My_Book/html/index.html для проверки результатов. Команда
make -C manuals/My_Book master.flat.html LANG=en
скомпилирует один HTML-файл. «Натравите» свой веб-браузер на файл ~/Новый_проект/manuals/My_Book/master.flat.html, чтобы проверить результат.
Несколько моментов, на которые стоит обратить внимание:
Нет необходимости говорить, что последние два раздела Раздел 3.2, «Пошаговый пример» должны выполняться «в процессе». Нет нужды в написании всех модулей своей книги, чтобы проверить то, как она выглядит на данный момент.
Параметр LANG=en, переданный командам make в разделах выше, нужен только в том случае, если ваш предпочитаемый язык не английский. Это необходимо для компиляции документов на языке, отличном о того, что объявлен в конфигурационном файле вашего профиля author.xml.