?

Log in

No account? Create an account
tech

PHP Docbook

Интересная новость — парсер-рендерер докбука теперь и на php.


PhD: The [PH]P based [D]ocbook renderer RC1 released

Обычно докбук собирался с помощью стилей XSLT и xml-xslt процессора (например SAXON от автора стандарта XSLT). Классические процессоры были на JAVA, но сейчас их довольно много разных, например вот эта библиотека на JavaScript. Беда в том, что в классическом виде XSLT подобен сферическому коню в вакууме — без возможности задания переменных параметров для трансформации использовать его сложно, поэтому процессоры дают какой-нибудь нестандартный способ добавить переменные.

Было время, когда я был болен идеей сделать все, что возможно на связке xml-xslt, ну уж логику представления точно. И я просто утонул в пучине совершенно неоправданной сложности, которую эта связка принесла в мои приложения. Дело в том, что идея XSLT хороша лишь до тех пор пока разметкой описываются простые преобразования. Но их в реальной жизни недостаточно, и вот тогда на XSLT начинают программировать и наступает полный мрак.

В этом смысле PHP процессор, штука правильная — преобразование описывается классом, в котором есть массив преобразования тегов и методы, необходимые для преобразования. Выглядит значительно понятнее и удобнее стиля XSLT. Я уж не говорю о подсветке синтаксиса, который в случае XSLT преобразования надо было добавлять изрядно напрягшись. Хотя опять же если мы используем php для вызова xslt преобразования, то подсветка возможна, причем достаточно просто.

Документация — это часть процесса разработки, поэтому писать документацию в тестовом процессоре неудобно, поскольку нужно хранить историю изменений, поэтому в текстовом процессоре пишут ообычно документацию для пользователя, которая не сильно меняется в отличие от API. Самое простое решение с версиями — это Wiki. Однако тут есть неудобство — хранить вики в svn неудобно, а документация должна хранится в svn, поскольку связана с циклами релизов. Получается, что текстовые файлы — самый идеальный способ писать и хранить документацию к разрабатываемой системе. Однако до сегодняшнего дня это было не очень удобно делать в DocBook.

Скачать
Или поставить прямо из PEAR: pear install http://doc.php.net/phd/PhD-0.1RC1.tgz

Ссылки:
DocBook
Doc Book: Документация на русском языке
DocBook XSL: The Complete Guide

Проект Symfony ведет свои документы в чем-то своем
Ребята из MZZ написали свой отображатель

Comments

Хм, но в Яндексе вроде бы справляются как-то.

Мне кажется, что беда программирования на XSLT в том, что он XML — слишком много шума получается.
Не я ж не говорю, что нельзя на нем писать -- можно конечно :) Но очень неудобно.