Аннотация
Кроме простого создания документов доступно много дополнительных возможностей, позволяющих пользователю одной командой легко изменить выходной формат или создать набор руководств. Здесь мы всё это подробно опишем.
Полученное руководство (в пригодном для чтения формате) легко идентифицируется по его имени с соответствующим расширением. Для документов DocBook в Borges доступны четыре формата с четырьмя расширениями:
Таблица 3.1. Выходные форматы Borges
Зная это, всё, что вам нужно сделать - это скомпилировать make'ом нужный формат. Например, если вы хотите получить документ Install-guide-RPM из супердокумента Install-guide на английском языке в формате PDF, просто выполните:
make -C manuals/Install-guide/ Install-guide-RPM.pdf LANG=en
Если необходимо опубликовать все доступные в этом проекте руководства на всех языках, их компиляция один за другим во всех форматах может порядком поднадоесть. Для этого случая Borges предоставляет цель для автоматической компиляции всех комбинаций руководство-язык-формат.
make all [SUBDOCS="<список документов>"]
Без опции SUBDOCS эта команда создаст все субдокументы, определённые в файлах conf.xml (Раздел 1.1.4, «manuals/My_Book/conf.xml»), всех документов, определённых для всего проекта (Раздел 3.2.4, «Вставка нового документа»).
Если вы укажете список SUBDOCS, будут созданы только указанные пары супердокумент/документ. Если вы хотите получить только руководства Install-guide-RPM и Install-guide-tar из супердокумента Install-guide, вы должны использовать SUBDOCS="Install-guide/Install-guide-RPM Install-guide/Install-guide-tar"
В этом примере мы должны выполнить компиляцию следующей командной строкой:
make all SUBDOCS="Install-guide/Install-guide-RPM Install-guide/Install-guide-tar"
Её результатом будут все руководства в каталоге Outputs/, отсортированные по языку и документу.
Документы из одного проекта по некоторым причинам часто публикуются по-отдельности или на отдельных издательских носителях. Эта возможность позволяет определить пулы документов определённых форматов и языков, что может быть использовано для создания одной командой всех ассоциированных выходных документов, или архива, содержащего исходные материалы только для этих документов.
Мы видели в Раздел 1.1.5, «conf/repository.xml», что мы можем определить элементы такого типа:
<pool id="Printer">
<document id="Book/Book">
<language lang="en">
<style format="pdf"/>
</language>
<language lang="fr">
<style format="pdf"/>
</language>
</document>
</pool>Элемент <style> должен всегда иметь атрибут format. Он должен быть внутри элемента <language> (с обязательным атрибутом lang), который должен быть внутри элемента <document> (с атрибутом id). Атрибут id идентифицирует рассматриваемую пару документ/субдокумент. Каждый из этих элементов может быть повторён столько раз, сколько нужно для получения нужной комбинации документа, языка и формата.
После того, как пул определён в conf/repository.xml с соответствующим id, можно начать создание определённых в нём документов одной единственной командой:
make all POOL=Printer
При этом будут созданы и помещены в каталог Outputs/Printer все документы, определённые в пуле с ID Printer.
Аналогичным образом следующая команда:
make archive POOL=Printer
создаст архив с именем Printer-9.2.tar.bz2 (9.2 будет заменено текущим релизом проекта), содержащий голую версию репозитория проекта, позволяющую создать только документы, определённые в пуле Printer, при помощи команды make all.
Эта возможность также позволяет вам создать все документы (всех форматов и языков, определённых в файле conf.xml file), ассоциированные с определённым супердокументом. Например,
make -C manuals/Install-guide/ all
выполнит всю работу для супредокумента Install-guide. Полученные файлы будут сохранены в каталоге manuals/Install-guide/Outputs/.
Если вы работате над написанием и/или переводом модуля, вам часто нужно взглянуть на него в одном из поддерживаемых выходных форматов. Возможность Borges'а компилировать один модуль позволяет вам сделать это без необходимости компиляции всего документа, содержащего рассматриваемый модуль. Таким образом, вам остаётся больше времени для работы, вместо многократных ожиданий компиляции всей книги.
Синтаксис команды компиляции одного модуля:
make -C manuals/module module MOD=<имя_модуля> FORMAT=<выходной_формат> [LANG=ll] [exclude=foo]
Обратите внимание, что каталогом для компиляции одного модуля всегда будет manuals/module, независимо от того, какому документу принадлежит этот модуль. Этот каталог автоматически создаётся при инициализации Borges и все компилируемые по-отдельности модули сохраняются в него.
Параметр LANG=ll является необязательным и используется для принудительной компиляции на языке, отличном от установленного по умолчанию. ll - это двухбуквенный ISO-код языка.
Параметр exclude= является необязательным и используется для исключения элементов из входных файлов XML. См. Раздел 1.1.4, «manuals/My_Book/conf.xml».
make -C manuals/module borges-compile-features-sect1.pdf LANG=es
вы получите PDF-файл manuals/module/borges-compile-features-sect1.pdf с содержимым модуля borges-compile-features-sect1 на испанском языке.
Аннотация
Open Metadata Framework - это инициатива ibiblio, предоставляющая открытую систему каталогизации документации. Она позволяет разнообразным проектам документации представлять свои документы посредством общего интерфейса в виде каталога, значительно упрощая при этом поиск и навигацию по ним. Для получения дополнительной информации смотрите домашнюю страницу OMF. Проект ScrollKeeper предлагает общий интерфейс для управления файлами OMF.
Чтобы создать файл OMF для определённого суб-документа, выполните, например:
make -C manuals/Install-guide/ Install-guide-RPM.omf
При этом будет создан один файл со всеми метаданными OMF, необходимыми для каталогизации всех выходных файлов (на всех языках и всех форматов), вытекающих из указанного документа и в соответствии с содержимым файла conf.xml.
Фактические метаданные для каталогизации извлекаются из заголовка мастер-документа. В следующей таблице представлены элементы DocBook (из элемента info (bookinfo, articleinfo и др.) мастер-файла), используемые для заполнения информацией различных элементов OMF.
Таблица 3.2. Соответствие элементов DocBook и OMF
| Элемент OMF | Эквивалент DocBook |
|---|---|
| creator | first author |
| title | title: subtitle |
| date | pubdate |
| description | abstract |
| type | releaseinfo |
| coverage/@architecture | @arch |
| coverage/@os | @os |
| rights/@type | legalnotice[1]/@conformance |
| rights/@license | legalnotice[1]/@role |
| rights/@holder | copyright/holder |
Обратитесь к Спецификации OMF для изучения значений элементов OMF.
Файлы OMF генерируются автоматически при создании всех форматов, ассоциированных с определёнными документами (make all)