[docs] HeapCheck v.0

[Kirill Maslinsky]

Снова привет!

> [2all] Пора задуматься о Сопровождающих модули.
Уже давно задумались. И даже пришло в голову несколько еретических 
мыслей. 

> Вот сопровождающий взялся делать из документа модуль, то есть пакет в
> Сизиф. Допустим, он преобразовал его в правильный DB. Что с этим DB
> делать дальше? Надо понимать, что Сопровождающий не обязан иметь доступ
> к devel:/cvs/docs, да и пользоваться CVSной, то есть рабочей (или
> нерабочей:) веткой среды сборки ему не стоит.

Давайте для начала определим, что такое модуль и что от него требуется. 

Модуль -- это:

1. Документ из Кучи, у которого есть Сопровождающий. 

2. Документ, доступный для просмотра в формате html.

3. Документ, снабжённый метаданными в стандартном виде: названием, сведениями
об авторах, аннотацией, классификацией, ``мягкими'' зависимостями на
документ(ы) в Куче и версии описываемого ПО, относящийся к определённому срезу
Сизифа (текущий или один из преждезамороженных).

4. Документ, для которого есть отдельный пункт в BTS (Bugzilla)

5. Документ, позволяющий организовать навигацию по модулям без вмешательства
в содержимое самих html-файлов модулей. 

6. Документ, представленный в виде пакета в Сизифе. 

Прошу отметить, что ни одно из этих требований не накладывает каких-либо
ограничений на разметку собственно текста документа, а требует только 
стандартного представления метаданных и определённых договорённостей относительно ссылок на другие модули. Причём метаданные совершенно 
необязательно (и, IMHO, нежелательно) хранить в самом документе, 
а лучше для этого использовать отдельный стандартный паспорт, как в 
Куче, для Модуля им может служить и rpm'ный spec. 

[2all] Технический вопрос: можно ли сделать такой движок, чтобы положенный
в определённое место html-файл (или html-дерево) отображались бы с 
шапкой и footer'ом с метаданными (автор, название, ссылка на BTS, 
навигация по модулям etc.), а в текст html-страницы при этом не приходилось 
бы вмешиваться или (что гораздо хуже) приходилось бы вставлять туда 
стандартные же header/footer?

Еретическая мысль: получается, что требуемый формат модуля html, а из
какого исходного текста и каким способом собирается этот html, более 
того, как именно размечен текст -- дело Сопрождающего. Нужно только, 
чтобы был движок, описанный в предшествующем абзаце, и чтобы 
html собирался из src.rpm автоматически. 

Реальная необходимость в стандартной разметке (для каких понятий в тексте
какие теги использовать) возникает только на стадии выпуска, потому
что если в разметке будет разнобой, то получится не выпуск, а 
свалка. Если, конечно, набор модулей в Сизифе мы уже считаем 
выпуском, то стандартизация нужна и здесь, но как будто бы это 
только сырьё для будущих выпусков. 

В общем, предлагаю требования к формату разработки перенести на 
уровень выпуска. (Тогда и каждый выпуск сможет предъявлять свои 
требования, ведь у каждого выпуска -- свои задачи. Одно дело -- журнал,
другое -- документация к дистрибутиву, с большой вероятности они 
потребуют по-разному размеченных документов.)

IMHO, будет очень полезной возможность выложить текст, к которому 
выставлены все правильные зависимости и пр., в виде модуля, чтобы народ 
мог его читать и править в BTS. Потому что если мы будем ждать, 
пока Сопровождающий изучит docbook или что-нибудь ещё, будет 
ждать и правка документа. Более того, ответственный редактор 
всё равно наверняка переправит разметку Сопровождающего перед 
выпуском. Единственное, что мы должны обеспечить способ
включать в модуль тексты, ориентированные на определённые выпуски. 

Прошу обсуждать предложенную позицию.

> 	Вопрос: как перенести процесс сборки зотя бы HTML-я в hasher?
> Чтобы сам документ и всё специфическое содержалось в src.rpm, hasher
> доставлял всё необходимое из числа пакетов Sisyphus и собирал rpm,
> состоящий из html-tree?

Если документ -- в стандартном DocBook, его сборка в html требует 
пакета docbook-styles-xsl и выполняется одной командой xsltproc 
с двумя параметрами: xsl-стиль и html-документ. Вот если нам 
при этом требуется получить не просто html, а такой html, в котором
есть какие-то специальные вставки (например, стандартная шапка или 
ссылка на cvs), тут нужно пробовать мудрить с xsl-стилями, много 
можно настроить просто параметрами сборки. 


-- 
Kirill Maslinsky
ALT Linux Documentation Team