Решил немного улучшить ситуацию с документирование
cl-libxml2. Встал вопрос: как документировать? Основное моё требование - возможность просматривать документацию on-line, без скачивания пакета. На хостинге проектов
Google Code (где, собственно, и базируется
cl-libxml2) для этих целей имеется в наличие wiki-движок, который меня, мягко говоря, не вдохновил. Доступа к другим ресурсам, на которых можно было бы опубликовать документацию, у меня нет. Немного поразмышляв, решил, что наилучший выход - воспользоваться возможностью http-доступа к репозиторию Subversion (который предоставляет
Google Code). Т.е. можно просто добавить документацию в формате html к исходному коду, выставить для этих файлов свойство svn:mime-type в "text/html" и опубликовать ссылку на эти файлы. На мой взгляд, это очень удобная возможностью Subversion.
Но откуда возьмутся html-файлы? В принципе, для меня совершенно не проблема писать документацию сразу в виде xhtml (часто приходиться слышать о трудности редактирования xml, но я использую
nxml-mode и считаю это исключительно лёгким занятием), но html не предоставляет вменяемых инструментов для "повторного использования" фрагментов разметки. Использование какой-либо системы публикации (типа
Emacs Muse) меня тоже не прельщает: необходимо сначала изменить исходник документации, потом сгенерить html и наконец закомитить все изменённые файлы - слишком сложная для меня процедура :-), тем более, что я хотел бы обновлять документации гораздо чаще, чем делать релизы.
В итоге, решил остановиться на решении, которое мне представляется наиболее "концептуальным" для данного проекта: написании документации в виде xml-файлов, которым, посредством инструкции обработки <?xml-stylesheet type="text/xsl"..., сопоставленно xls-преобразование (предоставляющее механизмы повторного использования элементов разметки), преобразующее xml-данные в html-разметку. Это даёт возможность писать документацию в xml, который можно сразу, без дополнительной генерации html, просматривать в браузере. В итоге, в репозиторий кладутся xml-файлы и таблицы стилей xsl и css.
Что получилось можно посмотреть
здесь.