Пакет rpm-build-docs

Внимание: на этой странице есть устаревшая информация!

Репозиторий исходного кода (git)

http://git.altlinux.org/people/kirill/packages/?p=rpm-build-docs.git

См. также документацию по git, и в первую очередь раздел руководства по повседневному использованию

Текущий мантейнер: KirillMaslinsky

Компоненты rpm-build-docs

Все пути указаны для дерева исходных текстов в git.

Генерация и обновление spec-файлов

См. ТЗ

Макросы RPM

Основная задача, которые решаются с помощью макросов — стандартизация спек-файлов, благодаря этому достигается независимость спеков от изменений в политиках сборочной среды; более конкретно, в макросах содержатся:

1. процедура вычисления имени пакета, тарболла, путей размещения файлов на основании Module ID
2. пути размещения компонентов в файловой системе
3. процедуры сборки модуля/выпуска
4. процедуры установки/удаления модуля/выпуска
5. процедура вычисления зависимостей (при сборке выпуска)Подлежит упразднению

rpm/rpm-build-docs	Определения макросов для использования в стандартных spec-файлах. Документированы прямо в этом файле
data/docs_genspec/docs-module-template.spec	Шаблон спека модуля, которым пользуется docs_genspec при начальном создании spec.
data/docs-issue-template.spec	Шаблон спека выпуска, редактировался вручную.Следует реализовать генерацию/обновление спека выпуска при помощи docs_genspec. Скорее всего шаблон спека выпуска потребуется несколько изменить

Сборка модулей

Основной процесс сборки HTML из исходных текстов модуля выполняется утилитами, которые вызываются в макросе %docs_build Решаемые здесь задачи:

1. Выбор и запуск процедуры сборки в HTML в зависимости от исходного формата.
2. Включение в собранный HTML стандартного навигационного блока и страницы с метаинформацией о документе (docinfo)

bin/docinfo2html	Создаёт HTML-страницу со сведениями о документе на основе docinfoПроверить, будет ли работать с docinfo в UTF8, в случае необходимости переписать
bin/docsbuild	Сборка из указанного формата в нормализованный HTML-модуль. Запускает сборочный скрипт для данного формата (см. ниже) и docs_navigation
data/docsbuild/modules.sh	Выстраивает соответствия имён форматов и сборочных скриптов для них
data/docsbuild/extras	Особый сборочный скрипт, используется, если для указанного формата нет специального сборочного скрипта. Создаёт HTML-страницу со ссылкой на файл (ы) в исходном формате и кратким пояснением, как его можно открыть.
data/docsbuild/*	Cборочные скрипты для конкретных форматов (сборка только в HTML)
bin/docs_navigation	Подставляет (локализованную) стандартную шапку навигации модуля в получившийся после сборки index.htmlЗаменить на подстановку iframe
data/docs_navigation/*.html	Локализованные шапки навигации модуляЗаменить на iframe

Сборка выпусков

См. ТЗ на выпуски

При сборке пакета-выпуска выполняется морально устаревшая процедура вычисления завимостей на пакеты модулей (см. макрос %docs_issue_requires). Решаемая задача:

1. Заполнение Requires: списком всех пакетов с необходимыми модулями.

bin/docs_issue_requires

Такая процедура порождает крайне нежелательную _сборочную_ зависимость на все модули, вошедшие в выпуск, она должна быть упразднена. Задачу заполнения Requires следует решать при генерации/обновлении спека средствами docs_genspec

Основная часть процесса создания выпуска из отдельных модулей выполняется процедурами, вызываемыми в макросе %docs_issue_build. Решаемые здесь задачи:

1. Определение входящих в модуль выпусков на основе индексной страницы выпускаМорально устарело, список предлагается указывать явно в спец. файле тривиального формата
2. Создание единой навигационной сети выпуска (без копирования модулей)

bin/docs_issue.pl

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

Установка/удаление модулей

Маросы, выполняющие установку: %docs_install_module, %docs_module_postin Макрос после удаления: %docs_module_postun Задачи:

1. копирование файлов куда надо
2. создание ссылок между модулями при отсутствии выпуска, своего рода выпуск по умолчанию. Выполняется скриптом docs_mklinks из пакета docs-utils, в rpm-build-docs не входит!

Установка/удаление выпусков

Макросы %docs_issue_postin, %docs_issue_postun

Задача:

1. Обновление списка установленных выпусков на главной странице. Выполняется скриптом alt-docs-genextras из пакета alt-docs-genextras, в rpm-build-docs не входит!

Изменения в процессе сборки документации

В мае 2007 года в пакете rpm-build-docs были сделаны изменения:

• Список зависимостей для выпусков (определяется макросом docs_issue_requires) вычисляется не по установленным пакетам с модулями документации, а прямо по содержимому файла выпуска (ссылки вида <A HREF= “adt:whatis_alt.kirill”/>). Из такой ссылки будет создана установочная зависимость на пакет docs-whatis_alt-kirill.
• Файлы документации в формате m-k перед сборкой конвертируются в кодировку koi8-r с помощью enca (с указанием русского языка для определения кодировки). Это сделано для обхода проблем со сборкой файлов m-k в кодировке utf-8.