Введение
Для чего мы написали эту программу
При разработке программ мы обычно храним код в системе контроля версий (например svn). Изменяется код, изменяется интерфейс, и конечно изменяется документация. Было бы удобно хранить описания или рабочие записки в виде текстовых файлов в том же репозитории, что и код. В таком случае мы всегда сможем иметь документацию, относящуюся к разным веткам и версиям нашего проекта. Именно это и было поводом написать Bulldoc.
Многие программы и системы имеют на своих сайтах актуальную документацию, однако ее нельзя скачать к себе на локальный компьютер в сколь либо удобном виде. Сюда же относятся и wiki-системы, которые удобно быстро поставить, но неудобно архивировать или раздавать в виде скачиваемого файла. Желание дать возможность пользователям скачивать документацию в удобном виде — статичном многостраничном html, html-все-в-одном файле, chm, а также дать возможность оставлять комментарии было вторым поводом написать Bulldoc.
Многие программисты ведут блоги. В блогах мы пишем много разного — от коротких сообщений, вроде «Как хочется пива» до статей в нескольких частях с прологом и эпилогом. Стараемся поддерживать рубрикацию наших записей с помощью тегов. Блог хорош тем, что туда можно выложить интересную мысль, которая еще не оформилась в виде полноценной статьи. Однако часто хочется объединить несколько постов в один, когда мысль оформится. Страшно подумать, но когда-нибудь из нашего блога могла бы получиться самая настоящая книжка. Эта мечта была третьим поводом написать Bulldoc
Как обычно, каждое из пожеланий уже где-то реализовано. Но нет всего вместе или это не очень удобно. Так, например, держать документацию в файлах позволяет Microsoft HTML Help Compiler. Из файлов документации мы можем собрать chm-файл для нужной нам ветки или версии программы, мы можем положить этот файл на сайт в раздел "Скачать". Но мы не можем вставить туда автоматическую подсветку синтаксиса, мы не можем положить эти файлы на сайт в виде html без active-x компонента. Мы не сможем добавить пользовательские комментарии. Формат Docbook тоже близок к желаемому, но XSLT трансформации сложны, подсветка синтаксиса — хоть и решаемая, но проблема.
Возможности программы
Рассказав о мотивации, приступим к тому, что получилось в реализации.
Исходные файлы
- Одна инсталляция программы обслуживает произвольное количество книг
- Формирование структуры книги с помощью файла в простом и популярном формате YAML
- Страницы, хранящиеся в папках в соответствии со структурой книги
- Содержимое страниц представляет собой html текст, который можно открыть прямо в браузере
- Текст страниц может содержать специальные тэги для ссылок на страницы из оглавления
- Текст страниц может содержать специальные тэги для подсветки синтаксиса
- Для вставки картинки достаточно положить ее рядом с файлом текста страницы, а в тексте вставить обычный тэг картинки с атрибутом src='myimage.jpg' или src='myimages/myimage.jpg'
Языковые настройки
Имеется возможность выбрать кодировку для заголовков html страниц и язык для системных сообщений и служебных пунктов меню (поддерживаются языки-кодировки: русский-windows1251, русский-utf8 и английский)
Возможности меню и навигация
- Системой для страницы формируется меню текущего уровня со ссылками на разделы выше по иерархии. Например для статьи Хобби/на открытом воздухе/рыбалка/блесны меню будет содержать соседние статьи (крючки, лески, удилища и т.д.), и ссылки на родительские разделы: "на главную", "хобби", "на открытом воздухе" и "рыбалка"
- Формируются ссылки "вперед" и "назад"
- Для начальной страницы раздела автоматически формируется оглавление, глубина уровней оглавления задается в настройках
- Начальная страница раздела кроме оглавления может содержать текст
- Имеется возможность с помощью специального тега назначить странице ключевые слова. На основе этих данных может быть автоматически сформирована страница "Предметный указатель".
Оформление
- Оформление задается шаблоном, в котором можно использовать готовые структуры меню и навигации
- Можно создать несколько тем оформления. Один и тот же контент может быть отображаем с помощью разных тем
- Можно задать пользовательский класс, для подсветки синтаксиса. Этот класс может обеспечивать работу с wiki или markdown разметкой вместо html в текстах страниц
Варианты использования
- Сайт на php-apache. Запустив сайт на локальной машине разработчика можно видеть результаты правок оформления и текста без сборки статичных файлов. Имеется возможность править текст и оглавление прямо в браузере.
- Статичный html. Страницы html, можно заархивировать, можно положить на сайт
- Статичный html одним файлом
- CHM-файл. Система готовит файлы проекта, которые можно скормить компилятору chm-файлов. Имеется возможность создать индекс ключевых слов для поиска.
- Интернет-сайт с комментариями пользователей (путем добавления в тему вызовов компонента Comments библиотеки js-kit.com)
- Книгу или документацию можно распространять через svn или pear-channel, таким образом пользователи смогут легко апдейтить свои книжки