Bull Doc

Простой пример

Приготовления

Для нашего примера нам понадобятся:

1. Дистрибутив Bulldoc, см. раздел Установка
2. Какой-нибудь сайт на локальной машине, под управлением Apache
3. Договоримся, что файлы сайта лежат в /home/bulldoc, а сам сайт доступен по http://bulldoc. Располагать Bulldoc в корне сайта не обязательно, подойдет любая директория.

Распакуйте дистрибутив в /home/bulldoc

Примерный план книги

Наша книга будет очень простой. В ней будет "Предисловие". Раздел "Браузеры" и две страницы в нем: "Opera" и "Firefox". Называться будет "Снусмумрики в Интернете". Удобно будет сделать заготовку в текстовом редакторе такого содержания:

Снусмумрики в Сети
=======================

Предисловие
Браузеры
  Firefox
  Opera

Создаем новый проект

В командной строке из /home/bulldoc запускаем:

bulldoc -c snusmumrik

Эта команда создаст 2 папки:
/home/bulldoc/workshop/source/snusmumrik
/home/bulldoc/workshop/source/snusmumrik/pages

И два файла:
пустой /home/bulldoc/workshop/source/snusmumrik/toc.yml
и /home/bulldoc/workshop/source/snusmumrik/book_data.yml

Также в конец файла /home/bulldoc/workshop/source/bookshelf.yml, допишется строчка:

snusmumrik:

Отредактируйте файл /home/bulldoc/workshop/source/snusmumrik/book_data.yml, вписав туда название книги, и по желанию изменив другие параметры (Внимание! Файлы с yml разметкой используют пробелы, а не табуляцию!):

title: Снусмумрики в Сети
author: Юный Сказочник

copyright: Юный Сказочник, 2008
site: www.snusmumrik.ru

Создать книку можно было бы и через веб-интерфейс. На стартовой странице BullDoc, т.е. на книжной полке нажмите ссылку "Создать книгу". В форме заполните только поле keyword и поля данных книги внизу. Нажмите "Сохранить" и книга готова. Но было полезно ознакомиться со структурой файлов, поэтому мы воспользовались командной строкой и текстовым редактором.

Система может уже распознать нашу пустую книгу. Зайдите браузером по адресу http://bulldoc, в списке доступных книг появилась и наша. Перейдите по ссылке и увидите страницу книги. Пока на ней ничего нет. Сейчас мы этим займемся.

Файл структуры

Наполните файл структуры /home/bulldoc/workshop/source/snusmumrik/toc.yml вот так (можете воспользоваться веб-интерфейсом, для этого нажмите в верхнем меню ссылку "правка TOC"):

introduction.html: Введение
browsers:
  type: chapter
  title: Бродилки
  topics:
    firefox.html: Firefox
    opera.html: Opera

Посмотрите книгу в бруазере http://bulldoc/snusmumrik. Появились оглавление, навигация, меню и вместо содержимого страниц скупая фраза "Наполняется". Переходим к страницам.

Контент

Создайте файл /home/bulldoc/workshop/source/snusmumrik/introduction.html. Впишите туда такое содержимое:

Попробуйте посмотреть что получилось: http://bulldoc/snusmumrik/introduction.html

Создайте файлы про браузеры и наполните их (можете воспользоваться веб-интерфейсом, для этого зайдите на страницу через оглавление и нажмите ссылку "правка"):

Пройдитесь по страницам, посмотрите, что получилось.

Положите вот этот логотип в /home/bulldoc/workshop/source/snusmumrik/browsers/firefox.png и отредактируйте /home/bulldoc/workshop/source/snusmumrik/browsers/firefox.html добавив в начало файла

<img src='firefox.png'>

Посмотрите, что получилось.

Отредактируйте /home/bulldoc/workshop/source/snusmumrik/introduction.html, заменив название Opera на

<bdc:link page='browsers/opera.html' />

Посмотрите результат.

Добавьте в текст любой страницы код PHP:

<bdc:php> 
function _yamlizeArray($array,$indent) {
    if (is_array($array)) {
      $string = '';
      foreach ($array as $key => $value) {
        $string .= $this->_yamlize($key,$value,$indent);
      }
      return $string;
    } else {
      return false;
    }
  }
</bdc:php>  

Должна появиться подсветка.

Предметный указатель

Добавьте в файл структуры /home/bulldoc/workshop/source/snusmumrik/toc.yml страницу предметного указателя (также можно воспользоваться веб-интерфейсом, нажав сверху на ссылку "Правка TOC"):

introduction.html: Введение
browsers:
  type: chapter
  title: Бродилки
  topics:
    firefox.html: Firefox
    opera.html: Opera
topic_index.html: {type: index, title: Предметный указатель}

Зайдите на страницу предметного указателя, — он уже не пуст!

Добавим изображение обложки

Сохраните эту картинку, как /home/bulldoc/workshop/source/snusmumrik/pages/cover.png. Зайдите браузером на начальную страницу книги (http://bulldoc/snusmumrik), нажмите "правка" и впишите такое содержимое:

<img src='cover.png' style='display: block'>
<h2>Оглавление</h2>

Посмотрите, – появилась картинка. Более того и на книжной полке наша книга теперь с обложкой.

Экспорт в статику

Осталось построить статический набор html-файлов. В консоли наберите

cd /home/bulldoc bulldoc snusmumrik

Посмотрите, что получилось в папке /home/bulldoc/workshop/output/snusmumrik