Спецификация выпуска

Полиси на структуру выпуска

Выпуск предстваляет собой разновидность модуля документации, следюущую некоторым соглашениям. Выпуски наравне с модулями размещаются в Куче.

Составляющие выпуска: Исходный пакет для выпуска (в нашем частном случае — src.rpm) состоит из следующих компонент:

HTML-tree: Исходное дерево файлов, составляющее «мясо» выпуска со всем его дизайном. Отличается тем, что в нём могут встречаться гиперссылки формата adt (см. ниже). При сборке такие шиперссылки должны быть преобразованы в относительные ссылки на файлы соответствующих модулей
Спецификация выпуска: файл спецификации выпуска (см. следующий раздел), в котором перечислены модули, входящие в выпуск, и обозначены логические отношения между ними. Пока назовем его issueinfo.
docinfo.issue: Файл docinfo, содержащий поля Title, Abstract, Section. Обрабатывается при установке пакета выпуска скриптом alt-docs-genextras (чтобы поместить ссылку на выпуск в файл /usr/share/doc/alt-docs/index. html).
rpm.issue.spec: . spec-файл пакета выпуска. С ним такая тонкость, в нём нужно указать в Requires и BuildReq список пакетов-модулей, на которые должна быть зависимость. Сейчас это делается с помощью макроса rpm, который отрабатывает прямо при сборке пакета, и из-за этого невозможно так запросто сделать src.rpm для выпуска, если у тебя в системе уже не установлены все необходимые модули, на которые должны быть зависимости. Вместо этого список зависимостей должен создаваться docs_genspecм при генерации и обновлении спека. Текущий шаблон спека лежит в пакете rpm-build-docs — docs-issue-template.spec.
Format: issue: в файле docinfo присутствует запись Format: issue, что позволяет отличить выпуск от обычного модуля Кучи

Формат файла спецификации выпуска

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

для каждого модуля — список модулей, которые нужно поместить в этот модуль как ссылки типа «See also»;
(необязательно) порядок слдования модулей в выпуске (автоматически сформированном оглавлении выпуска).

Наиболее логичен формат в виде простой текстовой таблицы. Например, указывать для каждого модуля список других модулей, которые должны быть помещены в раздел “See Also” в заголовок данного модуля в выпуске.

<ModuleID>  [adt:ModuleID] ...

Пример 1.

Для повышения гибкости можно формат первой колонки тоже сделать adt:, это позволит указывать там не только ModuleID, но и любое место выпуска. Вопрос, зачем такое можно будет использовать, остаётся открытым.

Очередность следования модулей пусть будет просто очередностью их упоминания в файле issueinfo

Остается открытым вопрос, следует ли на основании issueinfo генерировать какое-то автоматическое оглавление? Предлагаю пока тоже этого не делать, а вводить по мере надобности.

Формат ссылок на модули

Разработать. Начать можно с тривиального:

adt:ModuleID

Т. е. допускать только ссылки целиком на модуль. И все, а более сложные виды ссылок будем вводить по мере надобности.

Сборочная процедура для выпусков

Должна решать задачи:

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

При сборке html-выпуска необходимо:

Создать каталог имя_выпуска в каталоге /usr/share/doc/alt-docs, в него поместить очищенное от adt дерево выпуска.
Обойти полностью всё html-дерево выпуска, и заменить там все гиперссылки формата adt: на ссылки на конкретные ресурсы в файловой системе или в Интернет.
Для каждого модуля, включённого в выпуск, создать в каталоге имя_выпуска каталог-симлинк на реальный каталог модуля.
На основании спецификации выпуска (см. выше) составить для каждого модуля подходящий заполнитель «расширенного колонтитула» (Iframe), содержащий ссылки на модули “see also” и поместить их в каталог-симлинк модуля.
Поместить в каталог выпуска все страницы, автоматически сгенерированные на основании спецификации выпуска (см. выше, пока, видимо, считать это множество пустым).
Поместить в каталог выпуска файл docinfo выпуска.