[docs] HeapCheck v.0

[Fr. Br. George]

On Tue, Feb 15, 2005 at 11:07:32AM +0300, Kirill Maslinsky wrote:
> Снова привет!
> 
> > [2all] Пора задуматься о Сопровождающих модули.
> Уже давно задумались. И даже пришло в голову несколько еретических 
> мыслей. 
> 
> > Вот сопровождающий взялся делать из документа модуль, то есть пакет в
> > Сизиф. Допустим, он преобразовал его в правильный DB. Что с этим DB
> > делать дальше? Надо понимать, что Сопровождающий не обязан иметь доступ
> > к devel:/cvs/docs, да и пользоваться CVSной, то есть рабочей (или
> > нерабочей:) веткой среды сборки ему не стоит.
> 
> Давайте для начала определим, что такое модуль и что от него требуется. 
> 
> Модуль -- это:
> 
> 1. Документ из Кучи, у которого есть Сопровождающий. 
> 
> 2. Документ, доступный для просмотра в формате html.
> 
> 3. Документ, снабжённый метаданными в стандартном виде: названием, сведениями
> об авторах, аннотацией, классификацией, ``мягкими'' зависимостями на
> документ(ы) в Куче и версии описываемого ПО, относящийся к определённому срезу
> Сизифа (текущий или один из преждезамороженных).
> 
> 4. Документ, для которого есть отдельный пункт в BTS (Bugzilla)
> 
> 5. Документ, позволяющий организовать навигацию по модулям без вмешательства
> в содержимое самих html-файлов модулей. 
> 
> 6. Документ, представленный в виде пакета в Сизифе. 
> 
	(6). Из чего сразу следует (4). Представляется, что, поскольку
электронную документацию мы привыкли оформлять в HTML, (2) является
разумнын требованием. Требования (3) тоже вытекают из (6), а также из
специфики понятия "документ".
	Что же касается (5), то, как мне кажется, это требование не к
модулю, а к выпуску. Единственное, что _внутри_ модуля может относиться
к навигации -- это структурные ("Next", "Prev", "Up", "Home") и
контекстные (SEE ALSO) ссылки. Структурные ссылки для модуля ничего не
значат, поэтому их реализацию надо отдать движку (то есть определять на
уровне выпуска). Контекстные ссылки можно делать в виде тех же самых
нестрогих зависимостей, только не на программы, а на другие пакеты с
документацией, которые при формировании HTML-я легко подставить.
Работающие контекстные ссылки _внутри_ модуля -- роскошь, доступная
далеко не всегда. когда-нибудь и до этого дойдём.

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

> Еретическая мысль: получается, что требуемый формат модуля html, а из
> какого исходного текста и каким способом собирается этот html, более 
> того, как именно размечен текст -- дело Сопрождающего. Нужно только, 
> чтобы был движок, описанный в предшествующем абзаце, и чтобы 
> html собирался из src.rpm автоматически. 
	Почему же еретическая? Нормальная мысль, если считать подготовку
документации в HTML основной задачей. А она такая и есть -- всё равно
желающий подготовить печатную документацию будет работать с src.rpm, а
не с rpm.
> Реальная необходимость в стандартной разметке (для каких понятий в тексте
> какие теги использовать) возникает только на стадии выпуска, потому
> что если в разметке будет разнобой, то получится не выпуск, а 
> свалка. Если, конечно, набор модулей в Сизифе мы уже считаем 
> выпуском, то стандартизация нужна и здесь, но как будто бы это 
> только сырьё для будущих выпусков. 
	Когда мы сделаем удобный (для 80%) движок, позволяющий сознавать
HTML редактированием SPEC-рыбы, большинство, возможно, перейдёт на него
(вместо того, чтобы изобретать граблесипеды самостоятельно). Но и тогда
никто не запрещает встраиваться в эту схему "руками". К тому же в
Сизиф-срезе документации (а организовать такую легче лёгкого --
просто утановил все ALD-пакеты, и всё!) будет хорошо видно, кто чем свой
HTML размечал, и Выпускающий может попинать Сопровождающего заранее.
	Другое дело, что печатной документации из src.rpm такого модуля
может не получиться.

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

> IMHO, будет очень полезной возможность выложить текст, к которому 
> выставлены все правильные зависимости и пр., в виде модуля, чтобы народ 
> мог его читать и править в BTS. Потому что если мы будем ждать, 
> пока Сопровождающий изучит docbook или что-нибудь ещё, будет 
> ждать и правка документа. Более того, ответственный редактор 
> всё равно наверняка переправит разметку Сопровождающего перед 
> выпуском. Единственное, что мы должны обеспечить способ
> включать в модуль тексты, ориентированные на определённые выпуски. 
	Если содержание модуля в одном выпуске не равно содержанию
модуля в другом -- это разные модули. Возможность их повторного
использования в третьем выпуске -- под огромным вопросом. Можно
предусмотреть в модуле структурную ссылку "Специфика выпуска" и
туда вставлять все необходимые комментарии. Сопровождающий не обязан
задумываться о _личных_ нуждах всех потенциальных Выпускающих. В
замороченных случаях (когда модуль наполовину не соответствует особо
извращённому выпуску) можно просто делать одноразовый fork (всё равно
такие одноразовые модули со специфичной для конкретного выпуска
информацией будут).

-- 
			George V Kouryachy (aka Fr. Br. George)
			mailto:george at altlinux_ru