#language ru
#format mk

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

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

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

Составляющие выпуска:
Исходный пакет для выпуска (в нашем частном случае -- 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^ выпуска.