Ведение документации в perl6: POD, да не тот !
Post on 18-Nov-2014
2189 Views
Preview:
DESCRIPTION
Transcript
Ведение документации в 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
Ведение документациив perl6: POD, да не тот !
3 / 42
perl5 POD POD (Plain Old Documentation)
Synopsis 26:<!--Perldoc - легкий в использовании язык разметкис простой, однозначной моделью документа.Perldoc - поддерживает множество синтаксических диалектов,которые преобразуются в стандартные объекты модели.Стандартный диалект Perldoc - "Pod"-->
Perldoc Pod развитие ( эволюция ) perl5 POD
Структурные различия
Ведение документациив perl6: 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
Ведение документациив perl6: POD, да не тот !
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
Разграниченные блоки
Pod блоки в perl6 Ведение документациив perl6: POD, да не тот !
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($_) }
Разграниченные блоки. Примеры.
Pod блоки в perl6 Ведение документациив perl6: POD, да не тот !
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
Разграниченные блоки. Фича.
Pod блоки в perl6 Ведение документациив perl6: POD, да не тот !
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 )
# * Пустые строки после директив не обязателны .# И если указаны - входят в состав содержимого блока
Блоки-параграфы
Pod блоки в perl6 Ведение документациив perl6: POD, да не тот !
12 / 42
# Начинается с =for и продолжается до # первой пустой строки
=for BLOCK_TYPE OPTIONAL CONFIG INFO= OPTIONAL EXTRA CONFIG INFOBLOCK DATA
Блоки-параграфы. Примеры.
Pod блоки в perl6 Ведение документациив perl6: POD, да не тот !
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
Сокращенный блок
Pod блоки в perl6 Ведение документациив perl6: POD, да не тот !
14 / 42
# Отсутствуют конфигурационные параметры.
=BLOCK_TYPE BLOCK DATAMORE BLOCK DATA
Сокращенный блок. Примеры.
Pod блоки в perl6 Ведение документациив perl6: POD, да не тот !
15 / 42
=table Constants 1 Variables 10 Subroutines 33 Everything else 57
=Name The applicant's full name
=Contact The applicant's contact details
Три формы представле-ния - результат одинаковый
Pod блоки в perl6 Ведение документациив perl6: POD, да не тот !
16 / 42
# Сокращенный блок
=head1 Top Level Heading
# Блок-параграф
=for head1Top Level Heading
# Разграниченный блок
=begin head1Top Level Heading=end head1
Стандартные конфигрурационные параметры
Ведение документациив perl6: POD, да не тот !
17 / 42
• :nested• :numbered• :like• :allow• :term• :formatted
:nested :numbered :like
Стандартные конфигрурационные пара-метры
Ведение документациив perl6: POD, да не тот !
18 / 42
:nested определяет блок как вложенный в пределахего текущего контекста. Такие блоки выде-ляются в выходном формате дополнитель-ными отступами, выделением в виде рамок,фоном или в свернутом виде.
:numbered данный блок имеет нумерацию. нумерациязаголовков и списки.
:like блок имеет такие же параметры форматиро-вания как имя блока указанного в качествезначения.
=config head2 :like<head1> :formatted<I>
:allow
Стандартные конфигрурационные пара-метры
Ведение документациив perl6: POD, да не тот !
19 / 42
Список кодов форматирования разрешенных в блоке =code
# Для кода:
=begin code :allow< B R >sub demo { B<say> 'Hello R<name>';}=end code
# в выходном результате будет выделено "say":
sub demo { say 'Hello name';}
:term
Стандартные конфигрурационные пара-метры
Ведение документациив perl6: POD, да не тот !
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
Стандартные конфигрурационные пара-метры
Ведение документациив perl6: POD, да не тот !
21 / 42
К сожержимому блока применяются указанные кода фор-матирования
=begin paraB<I<Warning: Dont immerse in water.>>=end para# эквивалентно =begin para :formatted<B I>Warning: Dont immerse in water.=end para
Особенные дополнения и новые блоки
Ведение документациив perl6: POD, да не тот !
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)
Особенные дополнения и новые блоки Ведение документациив perl6: POD, да не тот !
24 / 42
#Определение форматирования заголовков
=config head1 :formatted<B U> :numbered=config head2 :like<head1> :formatted<I>=config head3 :formatted<U>=config head4 :like<head3> :formatted<I>
Уровни в списках
Особенные дополнения и новые блоки Ведение документациив perl6: POD, да не тот !
25 / 42
=item1 Animal =item2 Vertebrate =item2 Invertebrate
=item1 Phase =item2 Solid =item2 Chocolate#Результат
* Animal - Vertebrate - Invertebrate
* Phase - Solid - Chocolate
Таблицы (=table)
Особенные дополнения и новые блоки Ведение документациив perl6: POD, да не тот !
26 / 42
Таблицы (=table) (продолжение)
Особенные дополнения и новые блоки Ведение документациив perl6: POD, да не тот !
27 / 42
Именованные блоки
Особенные дополнения и новые блоки Ведение документациив perl6: POD, да не тот !
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
Именованные блоки (продолжение)
Особенные дополнения и новые блоки Ведение документациив perl6: POD, да не тот !
29 / 42
# Пример
=use Perldoc::Plugin::Image = :Jpeg prefix=>'http://dev.perl.org'
=Image http://example.com/perl_logo_32x104.png
Идентификаторы, целиком состоящие из символов нижне-го или верхнего регистра, зарезервированы
=begin head1=begin SYNOPSIS
Семантические блоки
Особенные дополнения и новые блоки Ведение документациив perl6: POD, да не тот !
30 / 42
Семантические блоки.Пример.
Особенные дополнения и новые блоки Ведение документациив perl6: POD, да не тот !
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
Коды форматирования
Ведение документациив perl6: POD, да не тот !
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 - определение
Коды форматирования Ведение документациив perl6: POD, да не тот !
34 / 42
# D<> - укзывает, что содержащийся в нем текст - определение.# Вводится термин объясняющий смежный текст.
A D<Formatting code|formatting codes;formatters>provides a way to add inline mark-up to a piece of text.
L - ссылка
Коды форматирования Ведение документациив perl6: POD, да не тот !
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 - ссылка (продолжение)
Коды форматирования Ведение документациив perl6: POD, да не тот !
36 / 42
L<http://example.com/S04.html#The_for_statement>L<doc:perlsyn#For Loops>
P - placement link
Коды форматирования Ведение документациив perl6: POD, да не тот !
37 / 42
# P<> - включение содержимого другого документа
=COPYRIGHTP<file:/shared/docs/std_copyright.pod>
# Преобразуется в
Copyright
This document is copyright (c) MegaGigaTeraPetaCorp. All rights reserved.
N - note
Коды форматирования Ведение документациив perl6: POD, да не тот !
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 - пользовательский код
Коды форматирования Ведение документациив perl6: POD, да не тот !
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)
Ведение документациив perl6: POD, да не тот !
40 / 42
http://search.cpan.org/dist/Perl6-Perldoc/ (text и xhtml)
Релизация на Rakudo (Martin Berends)
Ведение документациив perl6: POD, да не тот !
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.
Вопросы ?
Ведение документациив perl6: POD, да не тот !
42 / 42
S26:Documentation http://perlcabal.org/syn/S26.htmlPerlTimeline http://history.perl.org/
PerlTimeline.htmle-mail «zag@cpan.org»home page, twitter http://zag.ru
http://twitter.com/zagru
top related