Введение
Язык разметки для документации Perl. Plain Old Documentation (pod) — это простой язык разметки, используемый для документирования языка программирования Perl, а также модулей и программ на Perl.
Plain Old Documentation (pod) is a lightweight markup language used to document the Perl programming language as well as Perl modules and programs.
Использование
Pod — это язык, используемый для большей части документации в мире Perl. Это включает в себя сам Perl, почти все общедоступные модули, множество скриптов, большинство проектной документации, множество статей на Perl.com и других веб-сайтах, связанных с Perl, а также виртуальную машину Parrot. Pod редко читают в исходном виде, хотя он разработан таким образом, чтобы быть читаемым без использования инструментов форматирования. Вместо этого его читают с помощью инструмента perldoc или преобразуют в страницы руководства Unix или веб-страницы HTML. Также возможно использовать Pod в других контекстах, отличных от Perl. Например, для добавления простой документации к скриптам bash, которые затем можно легко преобразовать в страницы руководства. Такие случаи использования полагаются на специфические для языка приемы, чтобы скрыть часть Pod, например (в bash) добавлением префикса :<<=cut к разделу POD, что работает путем вызова команды bash no op : с целым блоком Pod в качестве входных данных в формате here document. Чистые Pod-файлы обычно имеют расширение pod, но чаще всего Pod используется непосредственно в коде Perl, который обычно имеет расширения pl и pm. (Парсер интерпретатора Perl разработан для игнорирования Pod в коде Perl.) В файлах исходного кода документация обычно размещается после маркера END (который также помогает некоторым редакторам выделять синтаксис, отображая ее как комментарии). Pod можно легко преобразовать в другие форматы, например, в различные форматы Wiki, такие как: WikiWikiWeb, Kwiki, TWiki, UseModWiki, TiddlyWiki, Textile, MediaWiki, MoinMoin или Confluence, используя Pod::Simple::Wiki.
and the Parrot virtual machine. Pod is rarely read in the raw, although it is designed to be readable without the assistance of a formatting tool. Instead, it is read with the perldoc tool, or converted into Unix man pages or Web standard HTML pages. It is also possible to use pod in other contexts than Perl. For example, to add simple documentation to bash scripts, which can then be easily converted to man pages. Such uses rely on language specific hacks to hide the pod part(s), such as (in bash) prefixing the POD section with the line :<<=cut which works by calling bash's no op : command, with the whole block of Pod as a here document as input to it. Pure pod files usually have the extension pod, but pod is mostly used directly in Perl
code, which typically uses the pl and pm extensions. (The Perl
interpreter's parser is designed to ignore pod in Perl code.) In source code files, the documentation is generally placed after the END marker (which also helps syntax highlighting in some editors to display it as comments). Pod can easily be converted to other formats, for example some of the various Wiki formats like: WikiWikiWeb, Kwiki, TWiki, UseModWiki, TiddlyWiki, Textile, MediaWiki, MoinMoin or Confluence using Pod::Simple::Wiki.
Пример
Этот документ является синтаксически корректным подом, который также стремится соответствовать основным соглашениям об именовании разделов.
Подробности форматирования
Файлы Pod написаны в кодировке, совместимой с ASCII, такой как Latin 1 или UTF-8. Парсер Pod всегда предполагает, что анализируемый файл не начинается с директивы Pod; он игнорирует все строки до тех пор, пока не встретит директиву Pod. Директивы Pod должны находиться в начале строки и все начинаются со знака равенства. После этого парсер Pod будет считать все последующие строки как Pod, пока не встретит строку, состоящую из директивы "=cut". Любое содержимое после этого игнорируется до тех пор, пока парсер не встретит другую директиву Pod. Таким образом, Pod можно смешивать с исполняемым исходным кодом, если парсер языка умеет распознавать и игнорировать Pod. Содержимое Pod разделено на абзацы пустыми строками. Абзацы, начинающиеся с пробельных символов (табуляций или пробелов), считаются "дословными абзацами" и остаются полностью без форматирования; они используются для примеров кода, ASCII-арта и т.п. Абзацы, начинающиеся со знака равенства, называются "командными абзацами"; последовательность буквенно-цифровых символов, непосредственно следующая за знаком равенства, рассматривается как директива Pod, а остальная часть абзаца форматируется в соответствии с этой директивой. Некоторые директивы также влияют на последующие абзацы. Если абзац начинается не со знака равенства или пробельного символа, он считается "обычным абзацем". Как обычные абзацы, так и содержимое командных абзацев анализируются на предмет кодов форматирования. Форматирование в Pod очень простое; оно в основном ограничено полужирным, курсивом, подчеркиванием, моноширинным шрифтом и несколькими другими стилями. Также существует код для создания ссылок между документами Pod или на другой раздел в том же документе. Коды форматирования состоят либо из: одной заглавной буквы, за которой следует знак меньше (<), форматируемое содержимое и знак больше (>), например B<полужирный текст>, либо из одной заглавной буквы, двух или более знаков меньше (<<), пробела, форматируемого содержимого, другого пробела и такого же количества знаков больше, как использовалось ранее, например B<<полужирный текст>>. Эта форма часто используется для фрагментов кода, содержащих знак больше, который в противном случае завершил бы код форматирования. Команды в Pod включают четыре уровня заголовков, маркированные и нумерованные списки, а также команды для обозначения разделов, написанных на другом языке. Последняя функция позволяет использовать специальное форматирование для парсеров, которые ее поддерживают.
until it sees a pod directive. pod directives must come at the beginning of a line, and all begin with an equal sign. The pod parser will then assume that all following lines are pod, until it encounters a line consisting of the "=cut" directive. Any content following that is ignored until the parser encounters another pod directive. Thus, pod can be intermixed with executable source code if the language's parser knows how to recognize and ignore pod. Pod content is divided into paragraphs by empty lines. Paragraphs that begin with whitespace characters—tabs or spaces—are considered to be "verbatim paragraphs", and are left completely unformatted; these are used for sample code, ASCII art, etc. Paragraphs that begin with an equal sign are "command paragraphs"; the sequence of alphanumeric characters immediately following the equal sign is treated as a pod directive, and the rest of the paragraph is formatted according to that directive. Some directives also affect the following paragraphs. If a paragraph starts with something besides an equal sign or whitespace, it's considered an "ordinary paragraph". Both ordinary paragraphs and the contents of command paragraphs are parsed for formatting codes. Formatting in pod is very plain; it's mainly limited to bold, italic, underlined, monospaced, and a few other formats. There is also a code for linking between pod documents or to another section within the same document. Formatting codes consist of either:
A single uppercase letter, followed by a less than sign (<), the content to be formatted, and a greater than sign (>), e. g. B<bolded text>, or
A single uppercase letter, two or more less than signs (<<), a space, the content to be formatted, another space, and the same number of greater than signs as were used before, e. g. B<< bolded text >>. This form is often used for code snippets containing a greater than sign, which would otherwise end the formatting code. Commands in pod include four levels of headings, bulleted and numbered lists, and commands to mark sections as being in another language. The latter feature allows for special formatting to be given to parsers that support it.