Проста стара документація

Проста стара документація ( англ. Plain old documentation , Скорочено pod; близьке за змістом до оригінального російській висловом - "Стара добра документація") - простий мова розмітки, застосовуваний для документування мови програмування Перл.


1. Пристрій

Pod розроблений як простий і ясний мову з мінімально необхідним корисним синтаксисом. З нього навмисно виключені механізми для опису шрифтів, зображень, квітів або таблиць. Хоча Pod не так виразний, як язики зразок XML або LaTeX, автори навмисне пожертвували виразністю заради простоти і зручності [1]. Основними цілями розробки pod є:

  • Простота розбору
  • Простота перетворення в інші формати і мови, наприклад у HTML або TeX
  • Простота включення прикладів з кодом
  • Простота читання у вихідній формі, тобто без обробки програмами форматування
  • Простота написання (інакше програмісти не стануть писати документацію!)

Принцип роботи цього формату викладений на man-сторінці perlpod, а деякі pod-транслятори описані на man-сторінках pod2man, pod2html і pod2text. Хоча автори руководоства perlpod відзначають, що можливостей pod швидше за все недостатньо для написання на ньому книг [2], фактично є книги, написані в розширеній версії pod. Ця розширена версія включає в себе можливості для форматування таблиць і підрядкових приміток і використовувалася іздтельством O'Reilly & Associates для виробництва декількох книг про Перл (найбільш відома з них це Програмування на Perl [1] Ларрі Уолла, Тома Крістіансена і Джона Орванта). Ще одна розширена версія pod, звана mod, використовувалася при написанні книги en: Higher-Order Perl Марка Джейсона Домінус.


2. Використання вбудованої в програму POD-документації

Прочитати вбудовану в програму POD-документацію в відформатованому вигляді можна за допомогою поставляється утиліти перегляду:

 %  perldoc program_with_pod  %  perldoc perlpod 

Крім того, POD-документацію дуже зручно читати при перегляді вихідного коду модуля.

Опис в форматі POD можна перетворити в web-сторінку поставляється в комплекті з perl утилітою:

 %  pod2html  - Outfile  = Program.html program_with_pod 

Для перетворення документації у звичайний текстовий формат, можна використовувати:

 pod2text filename.pm  >  filename.txt 

3. Приклад коду

POD-документація додано в кінець файлу:

 #! / Usr / local / bin / perl  hello  (  )  ;  sub  hello  {  print  "Hello, world!  \ N  "  ;  }  __END__  # Порожній рядок обов'язкове  = Head1 NAME # Ім'я програми або модуля = head1 SYNOPSIS # Одна рядок, що описує, що робить модуль або програма = head1 DESCRIPTION # Масив документації = head1 AUTHOR # Хто ви такий = head1 BUGS # Що зроблено неправильно = head1 SEA ALSO # Додаткова інформація 

Примітки

  1. 1 2 Ларрі Уолл, Том Крістіансен, Джон Орвант Програмування на Perl = Programming Perl. - "Символ-Плюс", 2010. - С. 686-703. - ISBN 5-93286-020-0
  2. "The Pod format is not necessarily sufficient for writing a book" - perldoc.perl.org / perlpod.html
Перегляд цього шаблону Мови розмітки документів
Офісних документів Compound Document Format OOXML (SpreadsheetML, PresentationML, WordprocessingML) ODF UOF
Загальновідомі HTML XHTML MathML JSON RTF TeX LaTeX
Менш відомі CML C-HTML ConTeXt Crossmark DITA DocBook eLML EAD Enriched text FHTML GML GuideML HDML HyTime HyperTeX IPF FictionBook LilyPond LinuxDoc Lout MIF MAML Markdown MEI MusicXML OMDoc OpenMath POD RTML RTML RFT S1000D TEI Texinfo troff Вікі-текст WML WapTV XAML YAML Z Format