Ведение документации в perl6: POD, да не тот !

Ведение документации в perl6: POD, да не тот !

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

17.05.2009

Немного истории

Ведение документациив perl6: POD, да не тот !

2 / 42

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

Perldoc и POD


3 / 42

perl5 POD POD (Plain Old Documentation)

Synopsis 26:

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

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


4 / 42

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

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

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

=pod

=head1 Foo

Stuff

=cut

Perldoc Pod

Структурные различия Ведение документациив perl6: POD, да не тот !

5 / 42

Каждый блок документации имеет свою длину.

=begin pod

=head1 Foo

Stuff

=end pod

(=cut не нужен. Поэтому нет такой директивы)

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

Структурные различия Ведение документациив perl6: POD, да не тот !

6 / 42

3 типа:

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

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

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

Pod блоки в perl6


7 / 42

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

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

Разграниченные блоки

Pod блоки в perl6 Ведение документациив perl6: POD, да не тот !

8 / 42

# =begin и =end# BLOCK_TYPE - идентификатор# в строке =begin - конфигурационная информация

=begin BLOCK_TYPE OPTIONAL CONFIG INFO = OPTIONAL EXTRA CONFIG INFO BLOCK CONTENTS =end BLOCK_TYPE

Разграниченные блоки


9 / 42

Конфигурационные параметры представлены парной нота-цией в стиле 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($_) }

Разграниченные блоки. Примеры.


10 / 42

=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 :optionalThe applicant's contact details=end Contact

Разграниченные блоки. Фича.


11 / 42

=begin table :caption<Table of Contents> Constants 1 Variables 10 Subroutines 33 Everything else 57

=end table

# * текст с отступами - не verbatim !# только в =pod, =nested, =item, =code# и семантических блоках (=SYNOPSIS,=VERSION )

# * Пустые строки после директив не обязателны .# И если указаны - входят в состав содержимого блока

Блоки-параграфы


12 / 42

# Начинается с =for и продолжается до # первой пустой строки

=for BLOCK_TYPE OPTIONAL CONFIG INFO= OPTIONAL EXTRA CONFIG INFOBLOCK DATA

Блоки-параграфы. Примеры.


13 / 42

=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

Сокращенный блок


14 / 42

# Отсутствуют конфигурационные параметры.

=BLOCK_TYPE BLOCK DATAMORE BLOCK DATA

Сокращенный блок. Примеры.


15 / 42

=table Constants 1 Variables 10 Subroutines 33 Everything else 57

=Name The applicant's full name

=Contact The applicant's contact details

Три формы представле-ния - результат одинаковый


16 / 42

# Сокращенный блок

=head1 Top Level Heading

# Блок-параграф

=for head1Top Level Heading

# Разграниченный блок

=begin head1Top Level Heading=end head1

Стандартные конфигрурационные параметры


17 / 42

• :nested• :numbered• :like• :allow• :term• :formatted

:nested :numbered :like

Стандартные конфигрурационные пара-метры


18 / 42

:nested определяет блок как вложенный в пределахего текущего контекста. Такие блоки выде-ляются в выходном формате дополнитель-ными отступами, выделением в виде рамок,фоном или в свернутом виде.

:numbered данный блок имеет нумерацию. нумерациязаголовков и списки.

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

=config head2 :like<head1> :formatted<I>

:allow



19 / 42

Список кодов форматирования разрешенных в блоке =code

# Для кода:

=begin code :allow< B R >sub demo { B<say> 'Hello R<name>';}=end code

# в выходном результате будет выделено "say":

sub demo { say 'Hello name';}

:term



20 / 42

Эта опция определяет, что элемент списка - определениетермина.

# 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.

:formatted



21 / 42

К сожержимому блока применяются указанные кода фор-матирования

=begin paraB<I<Warning: Dont immerse in water.>>=end para# эквивалентно =begin para :formatted<B I>Warning: Dont immerse in water.=end para

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


22 / 42

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

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

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

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

23 / 42

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

=config BLOCK_TYPE CONFIG OPTIONS= OPTIONAL EXTRA CONFIG OPTIONS

# Действие директивы ограничено границами текущего блока.# Параметры указанные непосредственно в # блоке имеют приоритет выше.

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


24 / 42

#Определение форматирования заголовков

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

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


25 / 42

=item1 Animal =item2 Vertebrate =item2 Invertebrate

=item1 Phase =item2 Solid =item2 Chocolate#Результат

* Animal - Vertebrate - Invertebrate

* Phase - Solid - Chocolate

Таблицы (=table)


26 / 42

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


27 / 42

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


28 / 42

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

=use - расширение типов блоков пользовательскими.

=use MODULE_NAME OPTIONAL CONFIG DATA= OPTIONAL EXTRA CONFIG DATA

=use URI

Именованные блоки (продолжение)


29 / 42

# Пример

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

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

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

=begin head1=begin SYNOPSIS

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


30 / 42

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


31 / 42

# Использование блоков =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

Коды форматирования


32 / 42

• V - verbatim текстI/O коды

• T - terminal output• K - keyboard inputДобавились уровни значимости

• U - минимально (подчеркнутый)• I - важно (наклонный)• B - основной уровень важности ( жирный )

R - замещаемые данные

Коды форматирования Ведение документациив perl6: POD, да не тот !

33 / 42

# R<> указывает, что содержимое является меткой шаблона,# метасинтаксической переменной, которое должно быть# заменено актуальным значением.

=for input Name: R<your surname> ID: R<your employee number> Pass: R<your password>

D - определение


34 / 42

# D<> - укзывает, что содержащийся в нем текст - определение.# Вводится термин объясняющий смежный текст.

A D<Formatting code|formatting codes;formatters>provides a way to add inline mark-up to a piece of text.

L - ссылка


35 / 42

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

L - ссылка (продолжение)


36 / 42

L<http://example.com/S04.html#The_for_statement>L<doc:perlsyn#For Loops>

P - placement link


37 / 42

# P<> - включение содержимого другого документа

=COPYRIGHTP<file:/shared/docs/std_copyright.pod>

# Преобразуется в

Copyright

This document is copyright (c) MegaGigaTeraPetaCorp. All rights reserved.

N - note


38 / 42

# N<> - указывает, что содержимое - примечание.

Use a C<for> loop instead.N<The Perl Six C<for> loop is far more powerful than its Perl5predecessor.> Preferably with an explicit iterator variable.

M - пользовательский код


39 / 42

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

=use Perldoc::TT

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

M<TT: get_description($CLASSNAME) >

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


40 / 42

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

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


41 / 42

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

Вопросы ?


42 / 42

S26:Documentation http://perlcabal.org/syn/S26.htmlPerlTimeline http://history.perl.org/

PerlTimeline.htmle-mail «[email protected]»home page, twitter http://zag.ru

http://twitter.com/zagru

http://perlcabal.org/syn/S26.html

http://history.perl.org/PerlTimeline.html

http://history.perl.org/PerlTimeline.html

http://zag.ru

http://twitter.com/zagru

Technology

Ведение документации в perl6: POD, да не тот !