The document discusses the documentation (POD) format used in Perl 5 and the proposed changes and new features of the POD format for Perl 6. Some key points include: - POD (Plain Old Documentation) was introduced in Perl 5 and supported by the perldoc tool for documenting Perl code and modules. - The POD format for Perl 6 proposes three main types of blocks - delimited blocks, paragraph blocks, and abbreviated blocks. Delimited blocks are bounded by begin/end tags with an identifier. - Perl 6 POD blocks can include configuration parameters for things like specifying data types, widths, or optional/required fields. - The Perl 6 POD format aims to address some limitations of the Perl 5

1. Ведение документации в perl6: POD, да не тот !
Александр Загацкий
17.05.2009

2. Немного истории
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
Ведение документации 2 / 42
в perl6: POD, да не тот !

3. Perldoc и POD
perl5 POD POD (Plain Old Documentation)
Synopsis 26:
<!--
Perldoc - легкий в использовании язык разметки
с простой, однозначной моделью документа.
Perldoc - поддерживает множество синтаксических диалектов,
которые преобразуются в стандартные объекты модели.
Стандартный диалект Perldoc - quot;Podquot;
-->
Perldoc Pod развитие ( эволюция ) perl5 POD
Ведение документации 3 / 42
в perl6: POD, да не тот !

4. Структурные различия
Как определяются блоки документации в perl5 ?
# c =директива
=...
= cut
#И заканчиваются =cut
=pod
=head1 Foo
Stuff
=cut
Ведение документации 4 / 42
в perl6: POD, да не тот !

5. Perldoc Pod
Каждый блок документации имеет свою длину.
=begin pod
=head1 Foo
Stuff
=end pod
(=cut не нужен. Поэтому нет такой директивы)
Структурные различия Ведение документации 5 / 42
в perl6: POD, да не тот !

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

7. Pod блоки в perl6
Основная составляющая Perldoc Pod - блок
3 типа:
Delimited blocks Разграниченные блоки
Paragraph blocks Блоки-параграфы
Abbreviated blocks Сокращенные блоки
Ведение документации 7 / 42
в perl6: POD, да не тот !

8. Разграниченные блоки
# =begin и =end
# BLOCK_TYPE - идентификатор
# в строке =begin - конфигурационная информация
=begin BLOCK_TYPE OPTIONAL CONFIG INFO
= OPTIONAL EXTRA CONFIG INFO
BLOCK CONTENTS
=end BLOCK_TYPE
Pod блоки в perl6 Ведение документации 8 / 42
в perl6: POD, да не тот !

9. Разграниченные блоки
Конфигурационные параметры представлены парной нота-
цией в стиле perl6 (S02)
Value is... Specify with Or with...
=============== ============= ============
Boolean (true) :key :key(1)
Boolean (false) :!key :key(0)
String :key<str> :key('str')
List :key<1 2 3> :key[1,2,3]
Hash :key{a=>1, b=>2}
Code :key{ sqrt($_) }
Pod блоки в perl6 Ведение документации 9 / 42
в perl6: POD, да не тот !

10. Разграниченные блоки. Примеры.
=begin table :caption<Table of Contents>
Constants 1
Subroutines 33
Everything else 57
=end table
=begin Name :required
= :width(50)
The applicant's full name
=end Name
=begin Contact :optional
The applicant's contact details
=end Contact
Pod блоки в perl6 Ведение документации 10 / 42
в perl6: POD, да не тот !

11. Разграниченные блоки. Фича.
=begin table :caption<Table of Contents>
Constants 1
Variables 10
Subroutines 33
Everything else 57
=end table
# * текст с отступами - не verbatim !
# только в =pod, =nested, =item, =code
# и семантических блоках (=SYNOPSIS,=VERSION )
# * Пустые строки после директив не обязателны .
# И если указаны - входят в состав содержимого блока
Pod блоки в perl6 Ведение документации 11 / 42
в perl6: POD, да не тот !

12. Блоки-параграфы
# Начинается с =for и продолжается до
# первой пустой строки
=for BLOCK_TYPE OPTIONAL CONFIG INFO
= OPTIONAL EXTRA CONFIG INFO
BLOCK DATA
Pod блоки в perl6 Ведение документации 12 / 42
в perl6: POD, да не тот !

13. Блоки-параграфы. Примеры.
=for table :caption<Table of Contents>
Constants 1
Variables 10
Subroutines 33
Everything else 57
=for Name :required
= :width(50)
The applicant's full name
=for Contact :optional
The applicant's contact details
Pod блоки в perl6 Ведение документации 13 / 42
в perl6: POD, да не тот !

14. Сокращенный блок
# Отсутствуют конфигурационные параметры.
=BLOCK_TYPE BLOCK DATA
MORE BLOCK DATA
Pod блоки в perl6 Ведение документации 14 / 42
в perl6: POD, да не тот !

15. Сокращенный блок. Примеры.
=table
Constants 1
Variables 10
Subroutines 33
Everything else 57
=Name The applicant's full name
=Contact The applicant's contact details
Pod блоки в perl6 Ведение документации 15 / 42
в perl6: POD, да не тот !

16. Три формы представле-
ния - результат одинаковый
# Сокращенный блок
=head1 Top Level Heading
# Блок-параграф
=for head1
Top Level Heading
# Разграниченный блок
=begin head1
Top Level Heading
=end head1
Pod блоки в perl6 Ведение документации 16 / 42
в perl6: POD, да не тот !

17. Стандартные конфигрурационные параметры
• :nested
• :numbered
• :like
• :allow
• :term
• :formatted
Ведение документации 17 / 42
в perl6: POD, да не тот !

18. :nested :numbered :like
:nested определяет блок как вложенный в пределах
его текущего контекста. Такие блоки выде-
ляются в выходном формате дополнитель-
ными отступами, выделением в виде рамок,
фоном или в свернутом виде.
:numbered данный блок имеет нумерацию. нумерация
заголовков и списки.
:like блок имеет такие же параметры форматиро-
вания как имя блока указанного в качестве
значения.
=config head2 :like<head1> :formatted<I>
Стандартные конфигрурационные пара- Ведение документации 18 / 42
метры в perl6: POD, да не тот !

19. :allow
Список кодов форматирования разрешенных в блоке =code
# Для кода:
=begin code :allow< B R >
sub demo {
B<say> 'Hello R<name>';
}
=end code
# в выходном результате будет выделено quot;sayquot;:
sub demo {
say 'Hello name';
}
Стандартные конфигрурационные пара- Ведение документации 19 / 42
метры в perl6: POD, да не тот !

20. :term
Эта опция определяет, что элемент списка - определение
термина.
# Definition lists:
=for item :term<MAD>
Affected with a high degree
of intellectual independence.
=for item :term<MEEKNESS>
Uncommon patience in planning a
revenge that is worth while.
=for item :term<MORAL>
Having the quality of general expediency.
Стандартные конфигрурационные пара- Ведение документации 20 / 42
метры в perl6: POD, да не тот !

21. :formatted
К сожержимому блока применяются указанные кода фор-
матирования
=begin para
B<I<
Warning: Dont immerse in water.
>>
=end para
# эквивалентно
=begin para :formatted<B I>
Warning: Dont immerse in water.
=end para
Стандартные конфигрурационные пара- Ведение документации 21 / 42
метры в perl6: POD, да не тот !

22. Особенные дополнения и новые блоки
=config предварительное конфигури-
рование
=item, =itemN уровни в списках
=table определение таблиц
=Named_blocks именованные блоки
=SYNOPSIS, =NAME ... семантические блоки
Ведение документации 22 / 42
в perl6: POD, да не тот !

23. Предварительное конфигурирование(=config)
Позволяет определить параметры, которые будут примене-
ны к указанному блоку.
=config BLOCK_TYPE CONFIG OPTIONS
= OPTIONAL EXTRA CONFIG OPTIONS
# Действие директивы ограничено границами текущего блока.
# Параметры указанные непосредственно в
# блоке имеют приоритет выше.
Особенные дополнения и новые блоки Ведение документации 23 / 42
в perl6: POD, да не тот !

24. Предварительное конфигурирование(=config)
#Определение форматирования заголовков
=config head1 :formatted<B U> :numbered
=config head2 :like<head1> :formatted<I>
=config head3 :formatted<U>
=config head4 :like<head3> :formatted<I>
Особенные дополнения и новые блоки Ведение документации 24 / 42
в perl6: POD, да не тот !

25. Уровни в списках
=item1 Animal
=item2 Vertebrate
=item2 Invertebrate
=item1 Phase
=item2 Solid
=item2 Chocolate
#Результат
* Animal
- Vertebrate
- Invertebrate
* Phase
- Solid
- Chocolate
Особенные дополнения и новые блоки Ведение документации 25 / 42
в perl6: POD, да не тот !

26. Таблицы (=table)
Особенные дополнения и новые блоки Ведение документации 26 / 42
в perl6: POD, да не тот !

27. Таблицы (=table) (продолжение)
Особенные дополнения и новые блоки Ведение документации 27 / 42
в perl6: POD, да не тот !

28. Именованные блоки
=begin Xhtml
<object type=quot;video/quicktimequot; data=quot;onion.movquot;>
=end Xhtml
=use - расширение типов блоков пользовательскими.
=use MODULE_NAME OPTIONAL CONFIG DATA
= OPTIONAL EXTRA CONFIG DATA
=use URI
Особенные дополнения и новые блоки Ведение документации 28 / 42
в perl6: POD, да не тот !

29. Именованные блоки (продолжение)
# Пример
=use Perldoc::Plugin::Image
= :Jpeg prefix=>'http://dev.perl.org'
=Image http://example.com/perl_logo_32x104.png
Идентификаторы, целиком состоящие из символов нижне-
го или верхнего регистра, зарезервированы
=begin head1
=begin SYNOPSIS
Особенные дополнения и новые блоки Ведение документации 29 / 42
в perl6: POD, да не тот !

30. Семантические блоки
Особенные дополнения и новые блоки Ведение документации 30 / 42
в perl6: POD, да не тот !

31. Семантические блоки.Пример.
# Использование блоков
=begin SYNOPSIS
use Perldoc::Parser
my Perldoc::Parser $parser .= new();
my $tree = $parser.parse($fh);
=end SYNOPSIS
# Можно использвать аналогичную запись
=head1 SYNOPSIS
=begin code
use Perldoc::Parser
my Perldoc::Parser $parser .= new();
my $tree = $parser.parse($fh);
=end code
Особенные дополнения и новые блоки Ведение документации 31 / 42
в perl6: POD, да не тот !

32. Коды форматирования
• V - verbatim текст
I/O коды
• T - terminal output
• K - keyboard input
Добавились уровни значимости
• U - минимально (подчеркнутый)
• I - важно (наклонный)
• B - основной уровень важности ( жирный )
Ведение документации 32 / 42
в perl6: POD, да не тот !

33. R - замещаемые данные
# R<> указывает, что содержимое является меткой шаблона,
# метасинтаксической переменной, которое должно быть
# заменено актуальным значением.
=for input
Name: R<your surname>
ID: R<your employee number>
Pass: R<your password>
Коды форматирования Ведение документации 33 / 42
в perl6: POD, да не тот !

34. D - определение
# D<> - укзывает, что содержащийся в нем текст - определение.
# Вводится термин объясняющий смежный текст.
A D<Formatting code|formatting codes;formatters>
provides a way to add inline mark-up to a
piece of text.
Коды форматирования Ведение документации 34 / 42
в perl6: POD, да не тот !

35. L - ссылка
# L<> появился перечень тем
# http: and https: file: mailto: man:
# doc: defn:
# isbn: and issn:
L<LAME library|http://www.mp3dev.org/mp3/>.
L<http://www.mp3dev.org/mp3/>)
# локально (без //):
L<http:tutorial/faq.html>
# ссылка на секцию,
Also see: L<man:bash()#Compound Commands>
Коды форматирования Ведение документации 35 / 42
в perl6: POD, да не тот !

36. L - ссылка (продолжение)
L<http://example.com/S04.html#The_for_statement>
L<doc:perlsyn#For Loops>
Коды форматирования Ведение документации 36 / 42
в perl6: POD, да не тот !

37. P - placement link
# P<> - включение содержимого другого документа
=COPYRIGHT
P<file:/shared/docs/std_copyright.pod>
# Преобразуется в
Copyright
This document is copyright (c)
MegaGigaTeraPetaCorp. All rights reserved.
Коды форматирования Ведение документации 37 / 42
в perl6: POD, да не тот !

38. N - note
# N<> - указывает, что содержимое - примечание.
Use a C<for> loop instead.N<The Perl Six C<for>
loop is far more powerful than its Perl5
predecessor.> Preferably with an
explicit iterator variable.
Коды форматирования Ведение документации 38 / 42
в perl6: POD, да не тот !

39. M - пользовательский код
# M<> - определенный пользоватлем форматирующий код
=use Perldoc::TT
=head1 Overview of the M<TT: $CLASSNAME > class
(version M<TT: $VERSION>)
M<TT: get_description($CLASSNAME) >
Коды форматирования Ведение документации 39 / 42
в perl6: POD, да не тот !

40. Реализация на perl5 (Domian Conway)
http://search.cpan.org/dist/Perl6-Perldoc/ (text и xhtml)
Ведение документации 40 / 42
в perl6: POD, да не тот !

41. Релизация на Rakudo (Martin Berends)
http://github.com/eric256/perl6-examples/tree/master
Format codes about 50% in text, man, xhtml, pod5 and pod6
emitters. =table and =use not even started.
Ведение документации 41 / 42
в perl6: POD, да не тот !

42. Вопросы ?
S26:Documentation http://perlcabal.org/syn/S26.html
PerlTimeline http://history.perl.org/
PerlTimeline.html
e-mail «zag@cpan.org»
home page, twitter http://zag.ru
http://twitter.com/zagru
Ведение документации 42 / 42
в perl6: POD, да не тот !