Документация к cl-libxml2

Решил немного улучшить ситуацию с документирование 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.

Что получилось можно посмотреть здесь.

Могучий, могучий XSLT :-)

Вот уже не первый год активно пишу на XSLT, а до сих пор регулярно обнаруживаю для себя новые возможности. Вот и сегодня, столкнулся с не вполне очевидной проблемой, пусть есть такой документ:

<data>
    <item-1>value-1</item-1>
    <item-5>value-5></item-5>
    <item-3>value-3</item-3>
    ....
    <item-n>value-n</item-n>
</data> 

Теперь надо в xslt получать значения этих узлов item-x по номеру (то бишь, по x). На первый взгляд показалось, что без dyn:evaluate из exslt не обойтись, правда такое решение на больших документах (ну там несколько тысяч таких записей), кроме того, ещё и тормозить будет заметно. Этот факт настолько меня растроил, что я тут же придумал решение:

<xsl:key name="item-by-number" match="/data/node()" use="substring(local-name(.), 6)">

и уже в самом коде можно так:

<xsl:value-of select="key('item-by-number', 3)">

Работает... к моему немалому удивлению и восторгу...