Boroda aka Hamster (fantaseour) wrote,
Boroda aka Hamster
fantaseour

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 написали свой отображатель
Tags: development
Subscribe

  • (no subject)

    Я очень люблю конференции. Они зажигают в разработчике свечечку, которую он потом бережно несет в себе через весь год! Когда-то давно, я с завистью…

  • Bing Interview

    Сходил на интервью в Microsoft. Получил известную долю удовольствия. 5 интервью одно за другим. 4 технических, одно -- HR. Интервьюверы умны,…

  • таки Bing!

    Я таки устроил в своей жизни еще одну авантюру -- послал резюме в Microsoft, когда узнал, что в августе они приедут собеседовать желающих поехать в…

  • Post a new comment

    Error

    default userpic

    Your reply will be screened

    When you submit the form an invisible reCAPTCHA check will be performed.
    You must follow the Privacy Policy and Google Terms of use.
  • 2 comments