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

                      17.05.2009
Немного истории
18 октября 1994       В списке анонса perl 5.000 прису-
                      твует поддержка POD


18 Oct...
Perldoc и POD
perl5 POD     POD (Plain Old Documentation)


Synopsis 26:
<!--
Perldoc - легкий в использовании язык размет...
Структурные различия
Как определяются блоки документации в perl5 ?


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

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

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


          =begin pod

          =head1 Foo

          S...
Основа perl5 POD - параграф
          3 типа:

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


           # =begin и =end
           # BLOCK_TYPE - идентификатор
           # в строке =begin - к...
Разграниченные блоки
           Конфигурационные параметры представлены парной нота-
           цией в стиле perl6 (S02)

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

           =begin table :caption<Table of Contents>
               Constants          1
  ...
Разграниченные блоки. Фича.
           =begin table :caption<Table of Contents>
               Constants          1
      ...
Блоки-параграфы


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


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

           =for table :caption<Table of Contents>
               Constants          1
         ...
Сокращенный блок


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


           =BLOCK_TYPE BLOCK DATA
           MOR...
Сокращенный блок. Примеры.


           =table
               Constants                         1
               Variables...
Три формы представле-
                    ния - результат одинаковый
           # Сокращенный блок

           =head1 Top ...
Стандартные конфигрурационные параметры
  •   :nested
  •   :numbered
  •   :like
  •   :allow
  •   :term
  •   :formatte...
:nested :numbered :like
          :nested               определяет блок как вложенный в пределах
                         ...
:allow
          Список кодов форматирования разрешенных в блоке =code

          # Для кода:

          =begin code :allo...
:term
          Эта опция определяет, что элемент списка - определение
          термина.

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


          =begin para
   ...
Особенные дополнения и новые блоки
=config                         предварительное конфигури-
                            ...
Предварительное конфигурирование(=config)
          Позволяет определить параметры, которые будут примене-
          ны к ...
Предварительное конфигурирование(=config)



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

          =config          ...
Уровни в списках
                =item1 Animal
                  =item2    Vertebrate
                  =item2    Inverteb...
Таблицы (=table)




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




Особенные дополнения и новые блоки   Ведение документации        27 / 42
              ...
Именованные блоки


          =begin Xhtml
          <object type=quot;video/quicktimequot; data=quot;onion.movquot;>
    ...
Именованные блоки (продолжение)


          # Пример

          =use Perldoc::Plugin::Image
          = :Jpeg prefix=>'htt...
Семантические блоки




Особенные дополнения и новые блоки   Ведение документации        30 / 42
                         ...
Семантические блоки.Пример.
          # Использование блоков
          =begin SYNOPSIS
             use Perldoc::Parser
  ...
Коды форматирования



• V - verbatim текст
I/O коды
• T - terminal output
• K - keyboard input
Добавились уровни значимос...
R - замещаемые данные

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

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

          #   L<> появился перечень тем
          #   http: and https: file: mailto: man:
          #   doc: d...
L - ссылка (продолжение)
          L<http://example.com/S04.html#The_for_statement>
          L<doc:perlsyn#For Loops>



...
P - placement link

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

          =COPYRIGHT
          P<file:/shar...
N - note

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

          Use a C<for> loop instead.N<The Perl Six C<...
M - пользовательский код

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

          =use Perldoc::TT

     ...
Реализация на perl5 (Domian Conway)
http://search.cpan.org/dist/Perl6-Perldoc/ (text и xhtml)




                        ...
Релизация на Rakudo (Martin Berends)
http://github.com/eric256/perl6-examples/tree/master
Format codes about 50% in text, ...
Вопросы ?




S26:Documentation         http://perlcabal.org/syn/S26.html
PerlTimeline              http://history.perl.or...
Upcoming SlideShare
Loading in...5
×

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

1,287

Published on

YAPC Russia 2009 "May Perl 2"

Published in: Technology
1 Comment
1 Like
Statistics
Notes
No Downloads
Views
Total Views
1,287
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
11
Comments
1
Likes
1
Embeds 0
No embeds

No notes for slide

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

  1. 1. Ведение документации в perl6: POD, да не тот ! Александр Загацкий 17.05.2009
  2. 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. 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. 4. Структурные различия Как определяются блоки документации в perl5 ? # c =директива =... = cut #И заканчиваются =cut =pod =head1 Foo Stuff =cut Ведение документации 4 / 42 в perl6: POD, да не тот !
  5. 5. Perldoc Pod Каждый блок документации имеет свою длину. =begin pod =head1 Foo Stuff =end pod (=cut не нужен. Поэтому нет такой директивы) Структурные различия Ведение документации 5 / 42 в perl6: POD, да не тот !
  6. 6. Основа perl5 POD - параграф 3 типа: Command Paragraph Строка начинающаяся с = Verbatim Paragraph Представление блоков кода первый символ - пробел или tab. Ordinary Paragraph Обычный текст. Никаких усло- вий по форматированию на парсер не возлагается. Граница - пустая строка Структурные различия Ведение документации 6 / 42 в perl6: POD, да не тот !
  7. 7. Pod блоки в perl6 Основная составляющая Perldoc Pod - блок 3 типа: Delimited blocks Разграниченные блоки Paragraph blocks Блоки-параграфы Abbreviated blocks Сокращенные блоки Ведение документации 7 / 42 в perl6: POD, да не тот !
  8. 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. 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. 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. 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. 12. Блоки-параграфы # Начинается с =for и продолжается до # первой пустой строки =for BLOCK_TYPE OPTIONAL CONFIG INFO = OPTIONAL EXTRA CONFIG INFO BLOCK DATA Pod блоки в perl6 Ведение документации 12 / 42 в perl6: POD, да не тот !
  13. 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. 14. Сокращенный блок # Отсутствуют конфигурационные параметры. =BLOCK_TYPE BLOCK DATA MORE BLOCK DATA Pod блоки в perl6 Ведение документации 14 / 42 в perl6: POD, да не тот !
  15. 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. 16. Три формы представле- ния - результат одинаковый # Сокращенный блок =head1 Top Level Heading # Блок-параграф =for head1 Top Level Heading # Разграниченный блок =begin head1 Top Level Heading =end head1 Pod блоки в perl6 Ведение документации 16 / 42 в perl6: POD, да не тот !
  17. 17. Стандартные конфигрурационные параметры • :nested • :numbered • :like • :allow • :term • :formatted Ведение документации 17 / 42 в perl6: POD, да не тот !
  18. 18. :nested :numbered :like :nested определяет блок как вложенный в пределах его текущего контекста. Такие блоки выде- ляются в выходном формате дополнитель- ными отступами, выделением в виде рамок, фоном или в свернутом виде. :numbered данный блок имеет нумерацию. нумерация заголовков и списки. :like блок имеет такие же параметры форматиро- вания как имя блока указанного в качестве значения. =config head2 :like<head1> :formatted<I> Стандартные конфигрурационные пара- Ведение документации 18 / 42 метры в perl6: POD, да не тот !
  19. 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. 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. 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. 22. Особенные дополнения и новые блоки =config предварительное конфигури- рование =item, =itemN уровни в списках =table определение таблиц =Named_blocks именованные блоки =SYNOPSIS, =NAME ... семантические блоки Ведение документации 22 / 42 в perl6: POD, да не тот !
  23. 23. Предварительное конфигурирование(=config) Позволяет определить параметры, которые будут примене- ны к указанному блоку. =config BLOCK_TYPE CONFIG OPTIONS = OPTIONAL EXTRA CONFIG OPTIONS # Действие директивы ограничено границами текущего блока. # Параметры указанные непосредственно в # блоке имеют приоритет выше. Особенные дополнения и новые блоки Ведение документации 23 / 42 в perl6: POD, да не тот !
  24. 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. 25. Уровни в списках =item1 Animal =item2 Vertebrate =item2 Invertebrate =item1 Phase =item2 Solid =item2 Chocolate #Результат * Animal - Vertebrate - Invertebrate * Phase - Solid - Chocolate Особенные дополнения и новые блоки Ведение документации 25 / 42 в perl6: POD, да не тот !
  26. 26. Таблицы (=table) Особенные дополнения и новые блоки Ведение документации 26 / 42 в perl6: POD, да не тот !
  27. 27. Таблицы (=table) (продолжение) Особенные дополнения и новые блоки Ведение документации 27 / 42 в perl6: POD, да не тот !
  28. 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. 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. Семантические блоки Особенные дополнения и новые блоки Ведение документации 30 / 42 в perl6: POD, да не тот !
  31. 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. 32. Коды форматирования • V - verbatim текст I/O коды • T - terminal output • K - keyboard input Добавились уровни значимости • U - минимально (подчеркнутый) • I - важно (наклонный) • B - основной уровень важности ( жирный ) Ведение документации 32 / 42 в perl6: POD, да не тот !
  33. 33. R - замещаемые данные # R<> указывает, что содержимое является меткой шаблона, # метасинтаксической переменной, которое должно быть # заменено актуальным значением. =for input Name: R<your surname> ID: R<your employee number> Pass: R<your password> Коды форматирования Ведение документации 33 / 42 в perl6: POD, да не тот !
  34. 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. 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. 36. L - ссылка (продолжение) L<http://example.com/S04.html#The_for_statement> L<doc:perlsyn#For Loops> Коды форматирования Ведение документации 36 / 42 в perl6: POD, да не тот !
  37. 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. 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. 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. 40. Реализация на perl5 (Domian Conway) http://search.cpan.org/dist/Perl6-Perldoc/ (text и xhtml) Ведение документации 40 / 42 в perl6: POD, да не тот !
  41. 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. 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, да не тот !
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×