perl6 pod extend

Perl6::Pod:Создание расширенийдля нового диалекта Pod

Александр Загацкий

11.10.2009

Copyright © 2009

История Pod

Perl6::Pod:Создание расшире-ний для нового диалекта Pod

2 / 35

18 октября 1994 В списке анонса perl 5.000 прису-твует поддержка POD

18 October 1994:It was a complete rewrite of Perl. A few of the features and pitfalls are: ... * The documentation is much more extensive and perldoc along with pod is introduced. ..

9 апреля 2005 S26: cпецификация формата Podдля perl6

25 Apr 2007 Последняя модификация

История Pod (продолжение)


3 / 35

August 16, 2009 S26 - The Next Generation. Списокдополнений.

автор спецификаций Damian Conway

Введение в Perldoc Pod


4 / 35

perl5 POD POD (Plain Old Documentation)

Synopsis 26:

Perldoc Pod развитие ( эволюция ) perl5 POD

Структурные различия

Введение в Perldoc Pod Perl6::Pod:Создание расшире-ний для нового диалекта Pod

5 / 35

Как определяются блоки документации в perl5 ?

# c =директива =...

= cut #И заканчиваются =cut

Основа perl5 POD - параграф


6 / 35

3 типа:

Command Paragraph Строка начинающаяся с =Verbatim Paragraph Представление блоков кода

первый символ - пробел илиtab.

Ordinary Paragraph Обычный текст. Никаких усло-вий по форматированию напарсер не возлагается. Граница- пустая строка

Pod блоки в perl6


7 / 35

Основная составляющая Perldoc Pod - блок3 типа:

Delimited blocks Разграниченные блокиParagraph blocks Блоки-параграфыAbbreviated blocks Сокращенные блоки

Определение таблицы


8 / 35

3 стиля для =table

Параметры блоков


9 / 35

Конфигурационные параметры представлены парной нота-цией в стиле perl6 (S02)

=for Image :title('3 стиля для =table') = :align('center') :!border src/3block_datapng.png

Особенные дополнения и новые блоки


10 / 35

=config, :like предварительное конфигури-рование и параметр :like

=item, =itemN уровни в списках=table определение таблиц=SYNOPSIS, =NAME ... семантические блоки=Named_blocks, M<> именованные блоки, расши-

рение кодов форматирования

=config и :like

Особенные дополнения и новые блоки Perl6::Pod:Создание расшире-ний для нового диалекта Pod

11 / 35

Предварительное конфигурирование

=config head1 :formatted<B U> :numbered =config head2 :like<head1> :formatted<I> =config head3 :formatted<U> =config head4 :like<head3> :formatted<I> =config C<> :allow<E I>

:like - блок имеет такие же параметры форматирования какимя блока указанного в качестве значения.

=for para :like<head4> some text

Уровни в списках


12 / 35

=item1 Animal =item2 Vertebrate =item2 Invertebrate

=item1 Phase =item2 Solid =item2 Chocolate #Результат * Animal - Vertebrate - Invertebrate

* Phase - Solid - Chocolate

Таблицы (=table)


13 / 35

Таблицы (=table) (продолжение)


14 / 35

Семантические блоки


15 / 35

DESCRIPTION этой презентации


16 / 35

=for DESCRIPTION = :title<Perl6::Pod:Создание расширений для нового диалекта Pod> = :pubdate('11.10.2009') = :author('Александр Загацкий')

Именованные блоки, расши-рение кодов форматирования


17 / 35

Именованные - блоки, определяемые пользователем

=begin Xhtml <object type="video/quicktime" data="onion.mov"> =end Xhtml

Директива =use


18 / 35

=use - определение именованных блоков

=use MODULE_NAME OPTIONAL CONFIG DATA = OPTIONAL EXTRA CONFIG DATA

Идентификаторы, целиком состоящие из символов нижне-го или верхнего регистра, зарезервированы.

Определение именованных блоков


19 / 35

Опишем блок Image:

=use Perldoc::Plugin::Image = :Jpeg prefix=>'http://dev.perl.org'

Использвание:

=Image http://example.com/perl_logo_32x104.png

Дополнительные коды форматирования


20 / 35

M<> - определенный пользователем форматирующий код

=use Perldoc::TT

=head1 Overview of the M<TT: $CLASSNAME > class (version M<TT: $VERSION>)

M<TT: get_description($CLASSNAME) >

1.Реализация на perl5 (Domian Conway)


21 / 35

http://search.cpan.org/dist/Perl6-Perldoc/ (text и xhtml)

2.Реaлизация на Rakudo (Martin Berends)


22 / 35

http://github.com/eric256/perl6-examples/tree/master/binFormat codes about 50% in text, man, xhtml, pod5 and pod6emitters. =table and =use not even started.

3. Perl6::Pod


23 / 35

Предстоит для реализации:

• атрибуты форматирования (:like, :format, :allow, :nested)• вложенность списков• включение содержимого другого документа• замещаемые данные• 40% кодов форматирования• таблицы

Работает

3. Perl6::Pod Perl6::Pod:Создание расшире-ний для нового диалекта Pod

24 / 35

В наличии:

расширяемость создание форматтеров, имено-ванных блоков, собственныхкодов форматирования

основная грамматика уровни заголовков, основныетипы списков,

xml,xhtml, docbook pod6docbook, pod6xhtml,pod6xml

Предложения для Synopsis


25 / 35

Четкое определение именованных блоков. Вместо:

=use Perldoc::Plugin::Image = :Jpeg prefix=>'http://dev.perl.org' =use Perldoc::TT

использовать:

=use Perldoc::Plugin::Image Image = :Jpeg prefix=>'http://dev.perl.org' =use Perldoc::TT TT<>

Событийная основа Perl6::Pod


26 / 35

Событийная основа Perl6::Pod


27 / 35

Способы достижения результата


28 / 35

Надо:

• Особая обработка блока текстовой информации (вставкикода xml в Pod)

• Создание этой презентацииРешение:

• Опредение именованного блока

=use Perl6::Pod::Block::format format

• Создание собственного форматера

Именованный блок


29 / 35

package Perl6::Pod::Block::format; use base 'Perl6::Pod::Block';

sub to_xhtml { my $self = shift; my $parser = shift; exists $self->get_attr->{xhtml} ? shift @_ : '';

}

sub to_xml { ... }

sub to_docbook { ... }

Варианты использования блока


30 / 35

=for format :xml <root><test/></root>

=for format :xhtml <div><br/></div>

=for format :docbook <title>Test chapter</title> <para>This is a test para</para>

Схема форматера


31 / 35

package Perl6::Pod::To::Slides; #В основе DocBook use base 'Perl6::Pod::To::DocBook'; sub export_block_slide { my ( $self, $el, @p ) = @_; my $foil = $self->out_parser->mk_element('foil'); $foil->add_content( $self->make_title_for_element($el), $self->_make_events(@p) ); return $foil; } sub export_block_DESCRIPTION { ... } sub export_code_L {}

Шаблон презентации


32 / 35

=begin pod

=for DESCRIPTION = :title<MyTitle> :pubdate('17.10.2009') = :author('First LastName')

=begin slide :title('first slide') Some text =item One =item two =end slide

=end pod

Подключение форматера


33 / 35

pod6docbook -doctype=slides \ -f Perl6::Pod::To::Slides \ test.pod > test.xml

С чего начать ?


34 / 35

use Perl6::Pod;

Вопросы?


35 / 35

S26 Documentation http://perlcabal.org/syn/S26.htmlPerl6-Pod http://search.cpan.org/dist/Perl6-

Pod/home page, mail http://zag.ru, zag(at)cpan.org

perl6 pod extend

Technology