Подключение модулей дополнительной документации в ALT Linux *********************************************************** * Пожалуйста, прочтите этот документ, если Вы собираетесь * * упаковать и отправить в Sisyphus пакет с электронной * * документацией или книгой в формате HTML. * *********************************************************** СОДЕРЖАНИЕ 1. Введение 2. Информация о пакете (файл docinfo) 3. Конвенции для оформления spec-файла (версия 0.2) 1. Введение В ALT Linux предусмотрена стандартизованная процедура для включения дополнительной документации в формате HTML: общей компьютерной литературы, руководств по отдельным программам и пакетам, учебников и учебных курсов, статей. Подключение такой документации при помощи этого метода позволяет пользователю прямо со стартовой страницы документации ALT Linux (пакет alt-docs-main) перейти к оглавлению всей установленной в системе дополнительной документации с гиперссылками на главные страницы соответствующих пакетов. Страница-оглавление генерируется автоматически (пакет alt-docs-genextras). 2. Информация о пакете (файл docinfo) Оглавление установленных пакетов с дополнительной документацией автоматически генерируется после установки или удаления любого пакета alt-docs-extras-* при помощи сценария alt-docs-genextras. Информация о пакете извлекается из файла docinfo в корневом каталоге пакета. Оглавление разбито на несколько тематических рубрик (список рубрик см. ниже при описании формата файла docinfo), внутри рубрики ссылки на документы располагаются в алфавитном порядке (по названиям документов). ************************************************************************ * Если файл docinfo содержит русскоязычный текст (что предполагается), * * он должен быть в кодировке koi8-r! * ************************************************************************ В файле docinfo должна содержаться следующая информация: Title: Название документа. Название будет текстом гиперссылки на стартовую страницу документа (index.html). Abstract: Аннотация документа. Этот текст будет включён в оглавление и должен давать представление о тематике документа и о том, для кого он предназначен (опытный пользователь, новичок, любознательный и т. п.). Строгих требований к аннотации нет, но из неё читатель должен иметь возможность понять, что это за документ и нужно ли ему его читать. Допустимо и даже желательно, чтобы краткое описание пакета (поле %description -l ru_RU.KOI8-R в spec-файле пакета) совпадало с аннотацией. Section: Тематическая рубрика. В настоящее время здесь может быть одно из следующих значений: textbook (Учебники/Учебные курсы) reference (Справочники и пользовательские руководства по конкретным программам и пакетам) freesoft (Свободное программное обеспечение: право, экономика, сообщество) misc (Всё прочее, без необходимости использовать нежелательно) Примечание: Если Вы считаете, что этот список должен быть расширен и можете предложить конкретные пункты, пишите в список рассылки docs@altlinux.ru. Текущий формат файла docinfo таков: ==Начало примера====================================== Section: Название документа Abstract: Аннотация документа (достаточно информативная, поэтому длиной в несколько строк). Section: textbook ==Конец примера======================================= ***************************************************************** * * * Обратите внимание: поля в файле docinfo должны быть разделены * * пустыми строками! * * * ***************************************************************** См. также пример в файле docinfo.sample. 3. Конвенции для оформления spec-файла (версия 0.2) Чтобы интегрировать описанным образом свой пакет с дополнительной документацией в систему документации ALT Linux, мантейнеру достаточно соблюсти несколько конвенций при составлении пакета. Текущая версия (0.2) предполагает следующее: * Пакет с дополнительной документацией называется alt-docs-extras-<ключевое_слово>. Примеры: alt-docs-extras-openoffice (руководство по OpenOffice.org); alt-docs-extras-linuxnovice (учебник для начинающего пользователя Linux); alt-docs-extras-informatika (учебник "Практическая информатика"). * Файлы с дополнительной документацией устанавливаются в каталог %_docdir/alt-docs-extras/<ключевое_слово>. В данный момент макрос %_docdir указывает на /usr/share/doc. Примеры: %_docdir/alt-docs-extras/openoffice/* Примечание: Подробнее о макросах для spec-файлов см. файл README.ALT-ru_RU.KOI8-R в пакете rpm. * Главная страница каждого пакета с дополнительной документацией называется index.html и располагается в корневом каталоге пакета (%_docdir/alt-docs-extras/<ключевое_слово>/). Пример: %_docdir/alt-docs-extras/openoffice/index.html Примечание: Не стоит называть этот файл index.htm (!) * Краткое описание пакета (название документа, аннотация, тематическая рубрика) находится в файле docinfo в корневом каталоге пакета. Пример: %_docdir/alt-docs-extras/openoffice/docinfo Формат файла docinfo описан выше, в разделе 2. * Для правильной регистрации нового пакета в списке дополнительной документации, а также для корректной работы с apt в spec-файле пакета должны быть выполнены следующие условия: 1. PreReq: alt-docs-genextras >= 0.2 (Сценарий для автоматической генерации оглавления должен быть установлен раньше пакета. Обязательно укажите версию, поскольку начиная с версии 0.2 изменился формат файлов docinfo.) 2. Provides: alt-docs-extra (Это общий сервис, который предоставляют все пакеты с дополнительной документацией. Если все они будут удалены, удалится и alt-docs-genextras, ставший бесполезным.) 3. %post %_bindir/alt-docs-genextras %postun %_bindir/alt-docs-genextras (В post-install и post-uninstall сценариях в spec-файле пакета вызывается сценарий alt-docs-genextras без параметров -- для автоматической генерации оглавления с вновь установленным и без только что удалённого пакета соответственно.)