[devel] I: new documentation packages

[Kirill Maslinsky]

Доброе утро!

В incoming отправляется доведённый до ума пакет 

alt-docs-genextras-0.2-alt1.src.rpm,

необходимый для интеллектуального подключения дополнительной
документации в формате HTML в структуру документации ALT. 
К нему прилагаются 5 пересобранных пакетов с такой документацией. 

alt-docs-extras-informatika-0.1-alt2.src.rpm
alt-docs-extras-linuxnovice-0.1-alt2.src.rpm
alt-docs-extras-mozilla-0.1-alt2.src.rpm
alt-docs-extras-openoffice-0.1-alt2.src.rpm
alt-docs-extras-schooljunior-0.1-alt2.src.rpm

В аттачменте к этому письму см. краткое описание данной технологии, 
оно же руководство по использованию. 

-- 
Kirill Maslinsky
ALT Linux Team * Documentation Project   
----------- следующая часть -----------
Подключение модулей дополнительной документации в 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 без параметров -- для 
	автоматической генерации оглавления с вновь установленным и
	без только что удалённого пакета соответственно.)