2. История Pod
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 Последняя модификация
Perl6::Pod:Создание расшире- 2 / 35
ний для нового диалекта Pod
3. История Pod (продолжение)
August 16, 2009 S26 - The Next Generation. Список
дополнений.
автор спецификаций Damian Conway
Perl6::Pod:Создание расшире- 3 / 35
ний для нового диалекта Pod
4. Введение в Perldoc Pod
perl5 POD POD (Plain Old Documentation)
Synopsis 26:
<!--
Perldoc - легкий в использовании язык разметки
с простой, однозначной моделью документа.
Perldoc - поддерживает множество синтаксических диалектов,
которые преобразуются в стандартные объекты модели.
Стандартный диалект Perldoc - "Pod"
-->
Perldoc Pod развитие ( эволюция ) perl5 POD
Perl6::Pod:Создание расшире- 4 / 35
ний для нового диалекта Pod
5. Структурные различия
Как определяются блоки документации в perl5 ?
# c =директива
=...
= cut
#И заканчиваются =cut
Введение в Perldoc Pod Perl6::Pod:Создание расшире- 5 / 35
ний для нового диалекта Pod
6. Основа perl5 POD - параграф
3 типа:
Command Paragraph Строка начинающаяся с =
Verbatim Paragraph Представление блоков кода
первый символ - пробел или
tab.
Ordinary Paragraph Обычный текст. Никаких усло-
вий по форматированию на
парсер не возлагается. Граница
- пустая строка
Введение в Perldoc Pod Perl6::Pod:Создание расшире- 6 / 35
ний для нового диалекта Pod
7. Pod блоки в perl6
Основная составляющая Perldoc Pod - блок
3 типа:
Delimited blocks Разграниченные блоки
Paragraph blocks Блоки-параграфы
Abbreviated blocks Сокращенные блоки
Введение в Perldoc Pod Perl6::Pod:Создание расшире- 7 / 35
ний для нового диалекта Pod
8. Определение таблицы
3 стиля для =table
Введение в Perldoc Pod Perl6::Pod:Создание расшире- 8 / 35
ний для нового диалекта Pod
9. Параметры блоков
Конфигурационные параметры представлены парной нота-
цией в стиле perl6 (S02)
=for Image :title('3 стиля для =table')
= :align('center') :!border
src/3block_datapng.png
Введение в Perldoc Pod Perl6::Pod:Создание расшире- 9 / 35
ний для нового диалекта Pod
10. Особенные дополнения и новые блоки
=config, :like предварительное конфигури-
рование и параметр :like
=item, =itemN уровни в списках
=table определение таблиц
=SYNOPSIS, =NAME ... семантические блоки
=Named_blocks, M<> именованные блоки, расши-
рение кодов форматирования
Perl6::Pod:Создание расшире- 10 / 35
ний для нового диалекта Pod
11. =config и :like
Предварительное конфигурирование
=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
Особенные дополнения и новые блоки Perl6::Pod:Создание расшире- 11 / 35
ний для нового диалекта Pod
12. Уровни в списках
=item1 Animal
=item2 Vertebrate
=item2 Invertebrate
=item1 Phase
=item2 Solid
=item2 Chocolate
#Результат
* Animal
- Vertebrate
- Invertebrate
* Phase
- Solid
- Chocolate
Особенные дополнения и новые блоки Perl6::Pod:Создание расшире- 12 / 35
ний для нового диалекта Pod
16. DESCRIPTION этой презентации
=for DESCRIPTION
= :title<Perl6::Pod:Создание расширений для нового диалекта Pod>
= :pubdate('11.10.2009')
= :author('Александр Загацкий')
Особенные дополнения и новые блоки Perl6::Pod:Создание расшире- 16 / 35
ний для нового диалекта Pod
17. Именованные блоки, расши-
рение кодов форматирования
Именованные - блоки, определяемые пользователем
=begin Xhtml
<object type="video/quicktime" data="onion.mov">
=end Xhtml
Особенные дополнения и новые блоки Perl6::Pod:Создание расшире- 17 / 35
ний для нового диалекта Pod
18. Директива =use
=use - определение именованных блоков
=use MODULE_NAME OPTIONAL CONFIG DATA
= OPTIONAL EXTRA CONFIG DATA
Идентификаторы, целиком состоящие из символов нижне-
го или верхнего регистра, зарезервированы.
Особенные дополнения и новые блоки Perl6::Pod:Создание расшире- 18 / 35
ний для нового диалекта Pod
19. Определение именованных блоков
Опишем блок Image:
=use Perldoc::Plugin::Image
= :Jpeg prefix=>'http://dev.perl.org'
Использвание:
=Image http://example.com/perl_logo_32x104.png
Особенные дополнения и новые блоки Perl6::Pod:Создание расшире- 19 / 35
ний для нового диалекта Pod
20. Дополнительные коды форматирования
M<> - определенный пользователем форматирующий код
=use Perldoc::TT
=head1 Overview of the M<TT: $CLASSNAME > class
(version M<TT: $VERSION>)
M<TT: get_description($CLASSNAME) >
Особенные дополнения и новые блоки Perl6::Pod:Создание расшире- 20 / 35
ний для нового диалекта Pod
21. 1.Реализация на perl5 (Domian Conway)
http://search.cpan.org/dist/Perl6-Perldoc/ (text и xhtml)
Perl6::Pod:Создание расшире- 21 / 35
ний для нового диалекта Pod
22. 2.Реaлизация на Rakudo (Martin Berends)
http://github.com/eric256/perl6-examples/tree/master/bin
Format codes about 50% in text, man, xhtml, pod5 and pod6
emitters. =table and =use not even started.
Perl6::Pod:Создание расшире- 22 / 35
ний для нового диалекта Pod
23. 3. Perl6::Pod
Предстоит для реализации:
• атрибуты форматирования (:like, :format, :allow, :nested)
• вложенность списков
• включение содержимого другого документа
• замещаемые данные
• 40% кодов форматирования
• таблицы
Perl6::Pod:Создание расшире- 23 / 35
ний для нового диалекта Pod
24. Работает
В наличии:
расширяемость создание форматтеров, имено-
ванных блоков, собственных
кодов форматирования
основная грамматика уровни заголовков, основные
типы списков,
xml,xhtml, docbook pod6docbook, pod6xhtml,
pod6xml
3. Perl6::Pod Perl6::Pod:Создание расшире- 24 / 35
ний для нового диалекта Pod
25. Предложения для Synopsis
Четкое определение именованных блоков. Вместо:
=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<>
3. Perl6::Pod Perl6::Pod:Создание расшире- 25 / 35
ний для нового диалекта Pod
28. Способы достижения результата
Надо:
• Особая обработка блока текстовой информации (вставки
кода xml в Pod)
• Создание этой презентации
Решение:
• Опредение именованного блока
=use Perl6::Pod::Block::format format
• Создание собственного форматера
3. Perl6::Pod Perl6::Pod:Создание расшире- 28 / 35
ний для нового диалекта Pod
29. Именованный блок
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 { ... }
3. Perl6::Pod Perl6::Pod:Создание расшире- 29 / 35
ний для нового диалекта Pod
30. Варианты использования блока
=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>
3. Perl6::Pod Perl6::Pod:Создание расшире- 30 / 35
ний для нового диалекта Pod
31. Схема форматера
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 {}
3. Perl6::Pod Perl6::Pod:Создание расшире- 31 / 35
ний для нового диалекта Pod
32. Шаблон презентации
=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
3. Perl6::Pod Perl6::Pod:Создание расшире- 32 / 35
ний для нового диалекта Pod
33. Подключение форматера
pod6docbook -doctype=slides
-f Perl6::Pod::To::Slides
test.pod > test.xml
3. Perl6::Pod Perl6::Pod:Создание расшире- 33 / 35
ний для нового диалекта Pod
34. С чего начать ?
use Perl6::Pod;
Perl6::Pod:Создание расшире- 34 / 35
ний для нового диалекта Pod
35. Вопросы?
S26 Documentation http://perlcabal.org/syn/S26.html
Perl6-Pod http://search.cpan.org/dist/Perl6-
Pod/
home page, mail http://zag.ru, zag(at)cpan.org
Perl6::Pod:Создание расшире- 35 / 35
ний для нового диалекта Pod