Perl6 Pod Extend

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

11.10.2009

Copyright © 2009

История 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

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

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

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


Введение в Perldoc Pod

perl5 POD POD (Plain Old Documentation)

Synopsis 26:


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

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

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

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

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

Введение в Perldoc Pod Perl6::Pod:Создание расшире- 5 / 35

Основа perl5 POD - параграф
3 типа:
Command Paragraph Строка начинающаяся с =
Verbatim Paragraph Представление блоков кода
первый символ - пробел или
tab.
Ordinary Paragraph Обычный текст. Никаких усло-
вий по форматированию на
парсер не возлагается. Граница
- пустая строка


Pod блоки в perl6
Основная составляющая Perldoc Pod - блок
3 типа:
Delimited blocks Разграниченные блоки
Paragraph blocks Блоки-параграфы
Abbreviated blocks Сокращенные блоки


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

3 стиля для =table


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

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


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


=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

Уровни в списках
=item1 Animal
=item2 Vertebrate
=item2 Invertebrate

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

* Phase
- Solid
- Chocolate


Таблицы (=table)


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


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


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

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


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

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

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


Директива =use

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

=use MODULE_NAME OPTIONAL CONFIG DATA
= OPTIONAL EXTRA CONFIG DATA

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


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

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

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

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

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


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

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)

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


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.


3. Perl6::Pod

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


Работает

В наличии:
расширяемость создание форматтеров, имено-
ванных блоков, собственных
кодов форматирования
основная грамматика уровни заголовков, основные
типы списков,
xml,xhtml, docbook pod6docbook, pod6xhtml,
pod6xml

3. Perl6::Pod Perl6::Pod:Создание расшире- 24 / 35

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

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

=use Perldoc::Plugin::Image
=use Perldoc::TT

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

=use Perldoc::Plugin::Image Image
=use Perldoc::TT TT<>


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


Способы достижения результата
Надо:
• Особая обработка блока текстовой информации (вставки
кода xml в Pod)
• Создание этой презентации
Решение:
• Опредение именованного блока

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

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


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

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 { ... }


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

=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>


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

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 {}


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

=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


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

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


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

use Perl6::Pod;


Вопросы?

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 Extend

Recommandé

Recommandé

Contenu connexe

Similaire à Perl6 Pod Extend

Similaire à Perl6 Pod Extend (16)

Perl6 Pod Extend