Решил немного улучшить ситуацию с документирование 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.
Что получилось можно посмотреть здесь.
Подписаться на:
Комментарии к сообщению (Atom)
The requested URL /svn/trunk/doc/xml/index.xml was not found on this server.
ОтветитьУдалить@gavenko
ОтветитьУдалитьНу, дык, сколько времени прошло, http://cl-libxml2.googlecode.com/svn/doc/index.html
Эх, мне идея держать доку в xml понравилась - хотел посмотеть как в браузере это выглядит.
ОтветитьУдалитьТем более на ограниченом публичном хостинге.
Да точно так же примерно она и выглядела, только теперь код лучше показывается ))
ОтветитьУдалитьВообщем, можно скачать какой-нибудь архив из https://github.com/archimag/cl-libxml2/downloads/ и посмотреть как это было в xml и как смотрелось в браузере.
Посмотрел https://github.com/archimag/cl-libxml2/zipball/version-0.3.2
ОтветитьУдалитьДак не полохо выглядело. xml оч. даже читабельный. А вот про текущий http://cl-libxml2.googlecode.com/svn/doc/quickstart.html такого не скажеш. Неужели руками писаный??
А github .xml так не сможет отдавать как google-code судя по https://github.com/github/markup#readme
Как оно выглядит сейчас можно посмотреть, например, здесь: https://github.com/archimag/cl-libxml2/blob/master/doc/install.rst
ОтветитьУдалитьДело в том, что с тех пор я написал cl-sphinx (аналог http://sphinx.pocoo.org/) и перешёл на неё для создания документации. Наиболее яркий пример использования это http://restas.lisper.ru/