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

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

Немного истории 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, да не тот !

Perldoc и POD perl5 POD POD (Plain Old Documentation) Synopsis 26:  Perldoc Pod развитие ( эволюция ) perl5 POD Ведение документации 3 / 42 в perl6: POD, да не тот !

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

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

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

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

Разграниченные блоки # =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, да не тот !

Разграниченные блоки Конфигурационные параметры представлены парной нота- цией в стиле 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, да не тот !

Разграниченные блоки. Примеры. =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, да не тот !

Разграниченные блоки. Фича. =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, да не тот !

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

Блоки-параграфы. Примеры. =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, да не тот !

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

Сокращенный блок. Примеры. =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, да не тот !

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

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

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

: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, да не тот !

: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, да не тот !

: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, да не тот !

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

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

Предварительное конфигурирование(=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, да не тот !

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

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

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

Именованные блоки =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, да не тот !

Именованные блоки (продолжение) # Пример =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 / 42 в perl6: POD, да не тот !

Семантические блоки.Пример. # Использование блоков =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, да не тот !

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

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

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, да не тот !

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, да не тот !

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

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, да не тот !

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, да не тот !

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, да не тот !

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

Релизация на 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, да не тот !

Вопросы ? 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, да не тот !

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

by mayperl on May 18, 2009

Accessibility

Categories

Tags

Upload Details

Usage Rights

1 Embed 1

Statistics

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