== Формат документов в Куче ==

Документ в Кучу можно поместить в '''любом формате'''.

Многие свободные проекты документации принимают единый формат для своих 
документов, так что присоединение к проекту означает и принятие этого
формата. 

Для Кучи это не так: мы принимаем документы на хранение в любом формате, 
в котором их готовы предоставить авторы. Поскольку такой подход непривычен, 
часто возникают вопросы и недоумение, в этом случае стоит посмотреть 
[:Docs/Babylon: обоснование] нашего подхода. 

=== Какой формат выбрать (если есть выбор) ===

Нередко один и тот же документ существует в нескольких форматах или у автора есть выбор, 
в каком формате писать -- ниже изложены основные рекомендации по выбору формата 
для Кучи.

  1. Документ следует помещать в Кучу в '''исходном формате''' (т. е. в том, в котором
  его создал автор), если есть такая возможность. Преимущества очевидны: можно будет 
  присылать автору патчи с исправлениями и дополнениями. 
  2. Все форматы для Кучи равноправны, но не равноэффективны. Имеется несколько 
  [:Heap/Formats/Supported: поддерживаемых форматов], для которых реализована
  автоматическая конвертация в HTML и публикация [http://heap.altlinux.ru/modules/ онлайн] и в
  [http://sisyphus.ru/team/docs/ RPM-пакете Sisyphus]. Если у вас есть документ в 
  неподдерживаемом формате, стоит его положить в Кучу и попросить [:Docs/Maillist: в списке рассылки] 
  [:Heap/Formats/AddNew: реализовать поддержку] этого формата в Куче (или реализовать её самостоятельно). 
  Если для вашего формата уже существует конвертер в HTML, то это задача по сложности от тривиальной до сравнительно
  простой.
  3. Документы в неподдерживаемых форматах всё равно имеет смысл помещать в Кучу, потому что, во-первых, 
  см. п. 2., а во-вторых, если документ не поддаётся автоматической трансформации в HTML, он будет точно 
  так же опубликован в Сети и в RPM-пакетах: будет создана титульная HTML-страница со ссылкой на документ
  в '''исходном формате''' (в котором он попал в Кучу), и стандартные HTML-страницы со сведениями о 
  документе, что позволяет интегрировать документ и в таком формате в общий пакет HTML-документации.