«WriteAt»: my opensource startup on Perl 6 Pod

The «WriteAt» is a free and opensource suite for book writers. It helps making and preparing books for publishing and printing. «WriteAt» uses pod6 as markup language.

"Compared to POD, Perl 6's Pod is much more uniform, somewhat more compact, and considerably more expressive." (S26)

The typical «WriteAt» book template looks like this:

  =TITLE MyBook
  =SUBTITLE My first free book
  =AUTHOR Alex Green
  =DESCRIPTION  Short description of the book
  =begin CHANGES
  Aug 18th 2010(v0.2)[zag]   preface
  
  May 27th 2010(v0.1)[zag]   Initial version
  =end CHANGES
  =CHAPTER Intro
  
  D<Pod> is an easy-to-use markup language with a simple, consistent
  object model underlying the document. Pod can be used for writing language
  documentation, documenting programs and modules, as well as for
  other types of document composition.

As you see it is simple. Because pod6 is extensible, it is possible to split big files into parts:

 =Include src/preface.pod6
 =Include src/basics.pod6

or insert images:

    =Image berries.png

A real book sample, a free book "Everything about Perl 6", can be downloaded from https://github.com/zag/ru-perl6-book.

The current version of «WriteAt» is 0.02. It supports exporting pod6 books to HTML. «WriteAt» is located at https://github.com/zag/writeat and the CPAN distribution is available from here: http://search.cpan.org/perldoc?WriteAt, also available at launchpad.net : https://launchpad.net/~zahatski/+archive/ppa.

How to install «WriteAt» ?

Under Ubuntu:

        sudo add-apt-repository ppa:zahatski/ppa
        sudo apt-get install writeat

Make book

         git clone https://github.com/zag/writeat-tmpl-firstbook.git
         cd writeat-tmpl-firstbook
         make

Reports of bugs, including inaccuracies in the documentation are always welcome.

Новшества в очередной версии «WriteAt»

Вышла вторая версия пакета для создания и публикации книг и документации «WriteAt» [1]. В новой версии произошли следующие изменения:

pod6 по-русски

Ключевые СЕМАНТИЧЕСКИЕ блоки можно писать по-русски! Вот как теперь выглядит шапка книги:

 =begin ИЗМЕНЕНИЯ
 18 июля  2012(v0.1)[i]   первая версия
 =end ИЗМЕНЕНИЯ
         
 =ЗАГОЛОВОК Моя книга
 =ПОДЗАГОЛОВОК Шаблон книги
 =ОПИСАНИЕ Шаблон для новой книги с примерами.
 =АВТОР Вася Пупкин
 =ГЛАВА Приветствую

 Это первая глава в моей книге.

Это пока пробный эксперимент. Коды форматирования и стандартные блоки pod6 остаются оригинальными, как описано в спецификации [2]. Возможность описывать заголовок книги по-русски может оказаться полезным.

Шаблоны книг

Для быстрого старта, подготовлены шаблоны книг:

writeat-tmpl-firstbook

Команда получения шаблона книги:

    git clone https://github.com/zag/writeat-tmpl-firstbook.git
    
writeat-tmpl-firstbook-ru

Команда получения шаблона книги «по-русски»:

    git clone https://github.com/zag/writeat-tmpl-firstbook-ru.git
    

После создания рабочей копии репозитория достаточно выполнить команду make (или gmake) внутри нее. В результате будет созданы пару вариантов книги в формате HTML и index.html файл для публикации.

На данный момент поддерживается операционная система «Ubuntu». В других операционных системах возможны ошибки. Главным образом они могут быть связаны с отсутствием требуемых программ.

Для установки «WriteAt» в «Ubuntu» достаточно выполнить следующие команды:

    sudo add-apt-repository ppa:zahatski/ppa
    sudo apt-get install writeat

В результате будет установлен сам пакет «WriteAt» и все необходимые программы (если возникнут ошибки - сообщите мне по почте).

Что такое «WriteAt»?

Если вкратце: «WriteAt» - бесплатный и открытый инструмент для создания и публикации книг и документации. Более подробно данный проект описан ранее [3]. На данный момент поддерживается только HTML формат.

Исходные тексты «WriteAt» открыты [4]. Очень будут кстати патчи, исправления и замечания о встреченных при создании книг ошибках!

NOTES

1. Библиотека «WriteAt» на CPAN. http://search.cpan.org/dist/WriteAt/

2. Спецификация на язык разметки pod6. https://raw.github.com/perl6/specs/master/S26-documentation.pod

3. Доступные книги для читателей и писателей. /a4JC1

4. Исходные тексты «WriteAt». https://github.com/zag/writeat

По итогам lvee 2012

В начале июня под Гродно прошла конференция lvee 2012 [1], посвященная свободному ПО. Конференция проходила на турбазе рядом с озером в сосновом лесу. Поэтому она оказалась полезна со всех сторон :-).

Writeat

В этом году я рассказывал [2] про свой открытый проект «Writeat» [3], который упрощает написание книг и документации, а так же помогает подготовить их к публикации. Вот некоторые вопросы, которые были заданы мне после выступления:

Почему был выбран pod6, а не LaTex или другой формат ?

Pod6 - язык разметки, который разработан для документирования программного кода языка Perl 6 (хотя сам язык Perl 6 еще не вышел). Pod6 лаконичен, прост и самое важное - расширяем. Именно это его свойство, позволяет мне использовать pod6 везде.

Я использую pod6 для написания статей в блог, создания презентаций [4], ведения технической документации [5], а так же для создания книг [6]. Предыдущий мой опыт работы с «Microsoft Word» и с такими форматами, как HTML, LaTex, docbook, POD я забыл, словно кошмарный сон.

Некоторое время назад я реализовал этот формат и с тех пор совершенствую свою реализацию pod6 [7].

Избавит ли «Wtriteat» авторов от необходимости изучения технических особенностей публикации ( при публикации в Интернет) ?

На данный момент «Wtriteat» - это программа, которая позволяет получить книги в формате HTML. Их достаточно просто скопировать на хостинг, чтобы опубликовать.

Наряду с программой, есть сайт проекта - writeat.com, на котором книги могут быть опубликованы. Сейчас публикация происходит автоматически из git репозиториев. Например, исходные тексты книги "Все o Perl 6" расположены в публичном репозитории по адресу http://github.com/zag/ru-perl6-book и публикуются по адресу http://writeat.com/zag/perl6-book/.

Поддержку публикации из git репозиториев я реализовал в первую очередь для своих задач и подобный способ рассчитан на разработчиков, которые чаще остальных используют git.

Вообще, хороший повод подумать, каким образом сделать публикацию книг более простым способом.

Конференция Lvee 2012

фотографии с lvee 2012

В конференции радует тот факт, что присутствуют доклады и выступления, отличные от администрирования и программирования. Например: использование свободного ПО в дизайне, музыке и образовании. Это делает конференцию более интересной широкому кругу участников.

Неожиданно для себя пообщался с представителями издательства и получил несколько ценных советов!

NOTES

1. Восьмая международная конференция разработчиков и пользователей свободного программного обеспечения. http://lvee.org

2. Презентация Writeat. http://www.slideshare.net/zagru/writeat

3. Доступные книги для читателей и писателей. /a4JC1

4. Create presentations in Perl 6 Pod. /a4DU1

5. Техническое задание в формате Perl 6 Pod. /a4G61

6. Perl 6 Pod: Книги в формате Pod. /a4CL1

7. Обновление Perl6::Pod. /a4JB2

Жизнь без шаблонов

Я хотел бы поделиться впечатлениями после довольно продолжительного времени разработки без шаблонизаторов на бэкенде. История началась с отказа от Template::Toolkit на серверной стороне и переноса представления на сторону веб клиента [1]. Вместе с представлением туда переместились и шаблоны, сохранив за собой право быть использованными и на серверной стороне [2], но это отдельная тема. Сейчас, по истечении некоторого времени, очевидны стали следующие моменты.

Упростилась разработка бэкенда

На данный момент, по сути, серверная строна представляет собой API с авторизацией для доступа к данным, а форматы вывода: JSON, JSONP и XML. Ниже я приведу пример кода, который определяет требуемый формат вывода и форматирует результаты. Код написан для «WebDAO» [3], но общий смысл, я постараюсь передать в комментариях:

package MyApp;
use WebDAO;
use base 'WebDAO::Engine';
use JSON;
use XML::Simple;

# пример метода 
# он отображается на url /Test
 sub Test {
    { 
        1 => 2,
        error => 0 
    }
 }

# этот метод обрабатывает http запросы
 sub _traverse_  {
    my $self = shift;
    my ( $src, $res ) = $self->SUPER::_traverse_( @_ );
    # $src - объект обработавший запрос
    # $res - результат вызова метода
    if ( ref($res) eq 'HASH' ) {
        my $r = $self->response();

        # $r->wantformat возвращает true если
        # присутствует параметр format=xml или 
        # путь заканчивается на .xml
        # например: http://example.com/api/get1&format=xml, 
        # http://example.com/api/get1.xml

        if ($r->wantformat('xml') ) { #xml

            $r->content_type('appliction/xml;charset=UTF-8');
            $r->print(XMLout( $res ))

        } else {  # default 'json' 

            $r->content_type('text/javascript;charset=UTF-8');
            # параметр pretty => 1 для форматированного JSON
	    $r->print(to_json($res, {utf8 => 1, pretty => 1}))
        }
        $r->flush;
        $r->_destroy;
        $r->set_empty();
        return (undef, $r) ;  #return empty response
    }
    return ( $src, $res );
 }
1;

Данный код позволяет писать простые методы:

 sub Test {
    { 
        1 => 2,
        error => 0 
    }
 }

Достаточно вернуть в качестве ответа ссылку на хэш и преобразование к требуемому формату будет выполнено автоматически.

Следующим и, пожалуй, наиболее эффектным последствием отказа от шаблонизаторов на бэкенде стала возможность разрабатывать без веб сервера и браузера. Текстовые форматы JSON и XML хорошо читаются без дополнительных программ и хорошо воспринимаются при отображении в консоли.

Поэтому увидеть результат запроса просто:

   wd_shell -M MyApp /Test

Результат:

  {
   "1" : 2,
   "error" : 0
  }

Тоже с параметрами:

   wd_shell -M MyApp '/Test?format=xml'

Результат:

    <opt 1="2" error="0" />

Таким образом значительно упрощается среда разработки и время необходимое для развертывания окружения.

«Кесарю кесарево» [4]

Шаблоны были неким общим «местом встречи» фронтенд и бэкенд разработчиков. Файлы шаблонов редактировали одни и вторые. С одной стороны, серверсайд программисты проникались чувством прекрасного посредством копипасты кусков html и css, а с другой стороны – дизайнеры и javascript разработчики, вынуждены были знать дополнительный серверный язык шаблонов ( и быть в некоторой зависимости от принятых правил деплоя ).

На данный момент единственным связующим фронтенд и бэкенд разарботку является API, который структурирован, может быть формализован и документирован. Это делает разработку динамичнее благодаря отсутствию общих точек, где возможны «блокировки», и определяет четкие границы ответственности.

Итог

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

К тому же, этот API может стать хорошим стартом для создания публичного API сервиса.

NOTES

1. Perl 5 модули, которые я использую реже и реже. /b48j1

2. Plosurin: Perl реализация Closure Templates. /a4Fr1

3. Платформа WebDAO для разработки web приложений на Perl 5. http://webdao.sourceforge.net/

4. Кесарю кесарево. http://ru.wikipedia.org/wiki/Кесарю кесарево

Perl6::Pod reworked

Recently i was reimplement Perl6::Pod to simplify it. First i move to new syntax parser wich build using Regexp::Grammars. And then rewrite export scripts: pod6docbook and pod6xhtml.

During the rewrite of Perl6::Pod using Regexp::Grammars, I experienced a lot of fun. Just look at the text of pod6 grammars [1]. At the end i have the following simple apis for use pod6.

API for use pod6 in app

For convert pod6 to xhtml use:

        use Perl6::Pod::Test; 
        my $html = Perl6::Pod::Test::parse_to_xhtml($pod);

API for hackers

Pod6 Grammars can be inherited. You could debug it step-by-step.

 use Regexp::Grammars;
    use Perl6::Pod::Grammars;
    use Data::Dumper;

    my $r =  qr{
       <extends: Perl6::Pod::Grammar::Blocks>
       <debug:step>
        \A <File> \Z
    }xms;
    my $tree ;
    if ( $src =~ $r  ) {
     print Dumper( $/{File} );
    }
    else {
        return undef;
    }

How to install Perl6::Pod ?

Under Ubuntu:

        sudo add-apt-repository ppa:zahatski/ppa    
        sudo apt-get install libperl6-pod-perl

or from CPAN [2].

Perl6::Pod hosted on github.com [3]. Reports of bugs are always welcome.