Login | Register
My pages Projects Community openCollabNet

docbookcompiler
Project home

If you were registered and logged in, you could join this project.

Summary DocBookCompiler. Breaking a DocBook Document into Separate Files
Category construction
License BSD License
Owner(s) develar

DocBookCompiler

Vladimir Krivosheev

Содержание

Разделение документа на отдельные файлы
Использование DocBookCompiler

Разделение документа на отдельные файлы

Для работы над большим документом DocBook необходимо его логическую структуру отразить на файловую систему. Официальная документация рекомендует использовать для этого сущности SGML или XInclude. Очевидно, что и первый, и второй способы имеют недостатки:

  • вы должны вручную писать сущности SGML или xi:include, при этом имя файла, содержащего логическую часть документа будет дублироваться (в случае SGML даже два раза);

  • написание идентификаторов логических частей на вашей совести — опять дублирование имени файла.

Дублирование неизбежно ведет к ошибкам. Никому не хочется выполнять монотонную бессмысленную работу.

DocBookCompiler избавляет вас от всего этого. Он работает согласно идее изложенной в статье «DocBook: системный подход к документации» — вам надо просто отразить логическую структуру документа на файловую систему соблюдая три несложных правила:

  • Элемент DocBook должен размещаться в новом каталоге в файле index.xml — если он будет содержать элементы, которые необходимо выделить в отдельные файлы, или в новом файле. Имя каталога/файла должно начинаться с буквы — требование типа xml:id.

  • Вместо sect* и refsect* необходимо применять их рекурсивные аналоги — section и refsection.

  • Если порядок следования частей документа важен, установите порядковый номер в начале имени каталога/файла (разделитель «-»). По умолчанию сортировка по возрастанию.

    0-file_name.xml
1-catalog_name

Работа с полученным отражением логической структуры документа на файловую систему ничем не отличается от работы с обычными файлами и каталогами. Удаляйте, перемещайте, создавайте — потом запустите DocBookCompiler и за вас будет выполнена следующая работа:

  • установка xml:id частям документа;

  • сборка документа DocBook в соответствии с новой структурой.

DocBookCompiler также выполняет ряд других задач — к примеру, генерация примеров, но это уже посредством дополнительной настройки.

Использование DocBookCompiler

DocBookCompiler — это консольная программа на PHP.

Usage: $ docbookcompiler.php [-h] [-i "." [-o "../compiled.xml"] ] [-d 5] [-c <string>]
DocBookCompiler 1.0.0

-h / --help
-i / --input    input dir
-o / --output   output file
-d / --docbook  DocBook version
-c / --config   config file

.