Обычная старая документация - Plain Old Documentation

Обычная старая документация (стручок) это облегченный язык разметки используется для документирования Perl язык программирования.

Дизайн

Pod разработан как простой, чистый язык с достаточным синтаксисом, чтобы быть полезным. Он намеренно не включает механизмы для шрифтов, изображений, цветов или таблиц. Некоторые из его целей:

  • Легко разбирать
  • Легко конвертировать в другие форматы, например XML, TeX или же Markdown
  • Легко включить образец кода
  • Легко читать без форматировщика подов (то есть в форме исходного кода)
  • Легко написать

Расширенная версия модуля, которая поддерживает таблицы и сноски, называется PseudoPOD, использовалась O'Reilly & Associates выпустить несколько книг по Perl, в первую очередь Программирование на Perl к Ларри Уолл, Том Кристиансен, и Джон Орвант.

Pod позволяет легко писать страницы руководства, которые хорошо подходят для документов, ориентированных на пользователя. Напротив, другие системы документации, такие как Python Строка документации или Java Javadoc Хотя они могут использоваться для пользовательской документации, они предназначены для облегчения создания ориентированной на разработчиков документации по исходному коду для проекта программного обеспечения.

Использовать

Pod - это язык, используемый для большинства документация в мире Perl. Сюда входит и сам Perl, почти все публично выпущенные модули, много скрипты, большинство проектных документов, много статей по Perl.com и других веб-сайтов, связанных с Perl, и Виртуальная машина Parrot.

Pod редко читается в исходном виде, хотя он разработан таким образом, чтобы его можно было читать без помощи инструмента форматирования. Вместо этого он читается с perldoc или преобразованный в Unix страницы руководства или веб-стандартные HTML-страницы.

Также возможно использовать pod в других контекстах, кроме Perl. Например, чтобы добавить простую документацию в сценарии bash, которые затем можно легко преобразовать в справочные страницы.[1] Такое использование полагается на специфичные для языка хаки для скрытия части (частей) модуля, например (в bash) префикс раздела POD строкой : << = вырезать который работает, вызывая bash безоперационный : команда, со всем блоком Pod как здесь документ как вход к нему.

Чистые файлы pod обычно имеют расширение .pod, но pod в основном используется непосредственно в Perlcode, который обычно использует .pl и .вечера расширения. (Perlустный переводчик с парсер предназначен для игнорирования pod в коде Perl.) В файлах исходного кода документация обычно помещается после __КОНЕЦ__ маркер (который также помогает подсветка синтаксиса в некоторых редакторах для отображения в виде комментариев).

Pod можно легко преобразовать в другие форматы, например в некоторые из различных Вики такие форматы, как: WikiWikiWeb, Kwiki, TWiki, UseModWiki, TiddlyWiki, Текстиль, MediaWiki, МойнМойн или же Слияние используя Pod :: Simple :: Wiki.

Пример

Этот документ является синтаксически правильным модулем, который также пытается следовать основным соглашениям об именах разделов.[2]

Исходный код
= head1 ИМЯMy :: Module - Пример модуля= head1 ОБЗОР    используйте My :: Module;    мой $ object = My :: Module-> new ();    напечатать $ object-> as_string;= head1 ОПИСАНИЕЭтот модуль на самом деле не существует, онбыл сделан с единственной цельюдемонстрируя, как работает POD.= head2 Методы= более 12= элемент C <новый>Возвращает новый объект My :: Module.= элемент C Возвращает строковое представлениепредмет. Это в основном для отладкицелей.= назад= head1 ЛИЦЕНЗИЯЭто выпущено под Artistic Лицензия. См. L .= head1 АВТОРДжурд - L = head1 СМОТРИ ТАКЖЕL , L = вырезать

Детали форматирования

Pod-файлы записываются в ASCII -совместимый кодирование, Такие как Latin-1 или же UTF-8. Парсер pod всегда предполагает, что файл, который он анализирует, не начинается с pod; он игнорирует все строки, пока не увидит директиву pod. директивы pod должны стоять в начале строки и начинаться со знака равенства. Затем синтаксический анализатор модуля будет считать, что все последующие строки являются модулями, пока не встретит строку, состоящую из директивы «= cut». Любое последующее содержимое, которое игнорируется, пока синтаксический анализатор не обнаружит другую директиву модуля. Таким образом, pod может смешиваться с исполняемым исходным кодом, если синтаксический анализатор языка знает, как распознавать и игнорировать pod.

Содержимое пода разделено на абзацы пустыми строками. Пункты, начинающиеся с пробел символы - табуляции или пробелы - считаются «дословными абзацами» и остаются полностью неотформатированными; они используются для примера кода, ASCII искусство и т. д. Абзацы, начинающиеся со знака равенства, являются «параграфами команд»; последовательность буквенно-цифровых символов, следующая сразу за знаком равенства, рассматривается как директива модуля, а остальная часть абзаца форматируется в соответствии с этой директивой. Некоторые директивы также влияют на следующие параграфы. Если абзац начинается с чего-то кроме знака равенства или пробела, он считается «обычным абзацем».

Как обычные абзацы, так и содержимое абзацев команд анализируются на наличие кодов форматирования. Форматирование в pod очень простое; в основном он ограничен полужирным шрифтом, курсивом, подчеркиванием, моноширинным шрифтом и несколькими другими форматами. Также существует код для связи между документами модуля или другим разделом в том же документе. Коды форматирования состоят из:

  • Одна заглавная буква, за которой следует знак «меньше» (<), форматируемое содержимое и знак «больше» (>), например B <жирный текст>, или же
  • Одна заглавная буква, два или более знаков "меньше чем" (<<), пробел, форматируемое содержимое, еще один пробел и такое же количество знаков "больше чем", которые использовались ранее, например B << жирный текст >>. Эта форма часто используется для фрагментов кода, содержащих знак «больше», иначе код форматирования завершился бы.

Команды в модуле включают четыре уровня заголовков, маркированные и нумерованные списки, а также команды для пометки разделов как написанных на другом языке. Последняя функция позволяет использовать специальное форматирование для парсеров, которые его поддерживают.

Смотрите также

Рекомендации

  • Уолл, Ларри; Кристиансен, Том; И Орвант, Джон (2000). Программирование на Perl (3-е изд.). Севастополь: O'Reilly & Associates. ISBN  0-596-00027-8.
  • Глава 15 «Работа с модулем» в Фой, Брайан Ди (2007). Освоение Perl. Севастополь: O'Reilly Media. ISBN  0-596-52724-1.
  • Раздел 5.2, «Встраивание документации в сценарии оболочки», в Альбинге, Карл; Vossen, JP; И Кэмерон Ньюхэм. (2007). Поваренная книга bash: решения и примеры для пользователей bash; O'Reilly & Associates. ISBN  0-596-52678-4.
  1. ^ Встраивание документации POD в сценарий оболочки (получено 10 января 2011 г.)
  2. ^ Джурд. "перлподтут".

внешняя ссылка