Спецификация выпуска
Полиси на структуру выпуска
Выпуск предстваляет собой разновидность модуля документации, следюущую некоторым соглашениям. Выпуски наравне с модулями размещаются в Куче.
Составляющие выпуска: Исходный пакет для выпуска (в нашем частном случае — 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] ...
Для повышения гибкости можно формат первой колонки тоже сделать adt:,
это позволит указывать там не только ModuleID, но и любое место выпуска. Вопрос, зачем такое можно будет использовать, остаётся открытым.
Очередность следования модулей пусть будет просто очередностью их упоминания в файле issueinfo
Остается открытым вопрос, следует ли на основании issueinfo генерировать какое-то автоматическое оглавление? Предлагаю пока тоже этого не делать, а вводить по мере надобности.
Формат ссылок на модули
Разработать. Начать можно с тривиального:
adt:ModuleID
Т. е. допускать только ссылки целиком на модуль. И все, а более сложные виды ссылок будем вводить по мере надобности.
Сборочная процедура для выпусков
Должна решать задачи:
- создание файловой структуры для выпуска (при установке в системе) в соответствии с его логической структурой
- создание и размещение автоматически сгенерированных файлов, содержащих структурную информацию, на основе спецификации выпуска
При сборке html-выпуска необходимо:
- Создать каталог
имя_выпуска
в каталоге/usr/share/doc/alt-docs
, в него поместить очищенное отadt
дерево выпуска. - Обойти полностью всё html-дерево выпуска, и заменить там все гиперссылки формата
adt:
на ссылки на конкретные ресурсы в файловой системе или в Интернет. - Для каждого модуля, включённого в выпуск, создать в каталоге
имя_выпуска
каталог-симлинк на реальный каталог модуля. - На основании спецификации выпуска (см. выше) составить для каждого модуля подходящий заполнитель «расширенного колонтитула» (Iframe), содержащий ссылки на модули “
see also
” и поместить их в каталог-симлинк модуля. - Поместить в каталог выпуска все страницы, автоматически сгенерированные на основании спецификации выпуска (см. выше, пока, видимо, считать это множество пустым).
- Поместить в каталог выпуска файл
docinfo
выпуска.