Формат документов в Куче
Документ в Кучу можно поместить в любом формате.
Многие свободные проекты документации принимают единый формат для своих документов, так что присоединение к проекту означает и принятие этого формата.
Для Кучи это не так: мы принимаем документы на хранение в любом формате, в котором их готовы предоставить авторы. Поскольку такой подход непривычен, часто возникают вопросы и недоумение, в этом случае стоит посмотреть обоснование нашего подхода.
Какой формат выбрать (если есть выбор)
Нередко один и тот же документ существует в нескольких форматах или у автора есть выбор, в каком формате писать -- ниже изложены основные рекомендации по выбору формата для Кучи.
Документ следует помещать в Кучу в исходном формате (т. е. в том, в котором его создал автор), если есть такая возможность. Преимущества очевидны: можно будет присылать автору патчи с исправлениями и дополнениями.
- Все форматы для Кучи равноправны, но не равноэффективны. Имеется несколько
поддерживаемых форматов, для которых реализована автоматическая конвертация в HTML и публикация онлайн и в RPM-пакете Sisyphus. Если у вас есть документ в неподдерживаемом формате, стоит его положить в Кучу и попросить в списке рассылки реализовать поддержку этого формата в Куче (или реализовать её самостоятельно). Если для вашего формата уже существует конвертер в HTML, то это задача по сложности от тривиальной до сравнительно простой.
- Документы в неподдерживаемых форматах всё равно имеет смысл помещать в Кучу, потому что, во-первых, см. п. 2., а во-вторых, если документ не поддаётся автоматической трансформации в HTML, он будет точно так же опубликован в Сети и в RPM-пакетах: будет создана титульная HTML-страница со ссылкой на документ
в исходном формате (в котором он попал в Кучу), и стандартные HTML-страницы со сведениями о документе, что позволяет интегрировать документ и в таком формате в общий пакет HTML-документации.