[docs] разница: модули и выпуски

[Artem Zolochevskiy]

hi all

Я уже не раз выступал против модульно-выпускной системы документации и 
описывал проблемные места. Но надо как-то жить. Что-то сейчас менять -- это 
большой простой по времени. Поэтому надо как-то доводить до ума то, что есть.

Весьма простой вопрос:
А чем отличаются "выпуски" от "модулей"?

Ответ кажется очевидным.
Что-то вроде:
Модули -- самодостаточные тексты на определённую тему (в них много текста).
Выпуски -- эть такие связующие документы для объединения модулей. В них крайне 
мало самостоятельного текста. В основном это ссылки на модули.

Но вот ответ на вопрос, чем они отличаются технически, не так очевиден.
Вот, как мне кажется, что надо помнить/завести как policy:
- Модули НЕ ИМЕЮТ ПРАВА содержить ссылки на другие модули. Ведь действительно, 
если модули самодостаточны, то они НЕ должны ссылаться на другие модули. 
Иначе (если они содержат ссылки на другие модули) они превращаются во что-то 
действительно странное. Это уже и не модули, но и не выпуски.

Отсюда вывод. Нам надо:
- или прекратить делать внутри модулей ссылки на другие модули
- или преобразовать такие модули в выпуски
- или как можно быстрее реализовать автоматическое выставление зависимостей у 
модулей, содержащих ссылки на други модули. В этом случае придётся дать более 
точное определение того, чем же отличаются выпуски от модулей. Ибо в этом 
случае техническая разница стирается.

По какому пути пойдём?

PS
Поясню из-за чего сыр-бор.
Приходится весьма нудно и долго проверять глазками/ручками всё ли в порядке с 
нашими ссылками/зависимостями. И раз или два это можно ещё сделать, но я 
понемногу просто теряю обзор из-зи обилия дистрибутивов (а соответсвенно 
и "выпусков").
Пример:
Выпуск docs-issue-distro имет ссылку на модуль docs-moduleA
Всё тут замечательно. При сборке docs-issue-distro пакет автоматически 
получает зависимость на docs-moduleA.
Всё резко ломается, если сам docs-moduleA имеет ссылку внутри себя на 
docs-moduleB. Как я уже сказал выше, модули наши НЕ имеет автоматики по 
выставленю зависимостей.
Вот тут то всё и ломается :( Решается "костылями" в виде ручного просмотра 
ВСЕХ ссылок в рамках выпуска и выставления имён нужных пакетов в 
docs-issue-distro в виде скрытых ссылок.
Всё это хозяйство крайне проблематично отслеживать :(

Ещё раз:
- или прекратить делать внутри модулей ссылки на другие модули
- или преобразовать такие модули в выпуски
- или как можно быстрее реализовать автоматическое выставление зависимостей у 
модулей, содержащих ссылки на други модули. В этом случае придётся дать более 
точное определение того, чем же отличаются выпуски от модулей. Ибо в этом 
случае техническая разница стирается.

-- 
Артём Золочевский