Сборка документов из кусочков на базе одного источника

Прежде чем активно заняться методом разработки систем на основе моделей я реализовал некоторые преимущества данного подхода путем использования обычных текстовых документов. Для этого мне понадобилось реализовать возможность сборки документов из кусочков.

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

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

Чтобы реализовать возможность сборки документов из кусочков необходимо каждый раздел нижнего уровня помещать в отдельном файле. После этого мы сможем повторно использовать их в нескольких документах. Собирать - это значит включать в некоторый индексный файл собираемого документа.

Можно даже организовать несколько уровней сборки. Допустим, на нижнем уровне мы имеем файлы, содержащие текст разделов нижнего уровня. На втором уровне мы создаем по одному файлу для каждого раздела следующего уровня. И собираем в этом файле (с помощью включения в индекс) разделы нижнего уровня, просто включая в индекс соответствующие файлы. Двигаясь таким образом вверх мы постепенно соберем документ из отдельных файлов. Большинство файлов (кроме тех, что содержат разделы нижнего уровня) будут содержать просто индексы включения других файлов.

- файл 0
   - включение файла 1
   - включение файла 5
- файл 1
   - включение файла 2
   - включение файла 3
   - включение файла 4
- файл 5
   - включение файла 6
   - включение файла 7
   - включение файла 8

Для того чтобы структурировать полученные файлы на диске мы создадим каталоги, в которые поместим полученные файлы. Структура каталогов на диске может отражать иерархию документа, а может и отличаться от нее. Например, на диске у нас может получиться вот такая структура, не совпадающая с логической структурой документа.

- каталог на диске 1
    - файл 0
    - файл 1
    - файл 5
- каталог на диске 1
   - файл 2
   - файл 3
   - файл 4

   - файл 6

   - файл 7
   - файл 8

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

Для реализации подобного подхода могут использоваться разные технологии, например HTML, XML DocBook или DITA XML. В качестве редакторов могут использоваться HTML, XML редакторы или Web CMS. Пример таких редакторов, которые я использовал XML Spy и XMetal - для редактирования XML DocBook и DITA XML, или Daisy CMS для создания документов в формате Web CMS.