Язык разметки для документирования языка Perl
Обычная старая документация (pod ) - это облегченный язык разметки используется для документирования языка программирования Perl.
Содержание
- 1 Дизайн
- 2 Использование
- 3 Пример
- 4 Подробности форматирования
- 5 См. Также
- 6 Ссылки
- 7 Внешние ссылки
Дизайн
Pod разработан как простой, чистый язык с достаточным синтаксисом, чтобы быть полезным. Он намеренно не включает механизмы для шрифтов, изображений, цветов или таблиц. Некоторые из его целей:
- Простота синтаксического анализа
- Простота преобразования в другие форматы, такие как XML, TeX или Markdown
- Легко включить образец кода
- Легко читать без форматтера модуля (т.е. в форме исходного кода)
- Легко писать в
Расширенная версия модуля, поддерживающая таблицы и сноски под названием PseudoPOD был использован O'Reilly Associates для создания нескольких книг по Perl, в первую очередь Programming Perl от Ларри Уолла, Tom Christiansen и Джон Орвант.
Pod позволяет легко писать справочные страницы, которые хорошо подходят для документов, ориентированных на пользователя. Напротив, другие системы документации, такие как Python Docstring или Java Javadoc, хотя их можно использовать для пользовательской документации, предназначены для облегчения создания ориентированной на разработчиков документации по исходному коду для программный проект.
Используйте
Pod - это язык, используемый для большей части документации в мире Perl. Сюда входит сам Perl, почти все публично выпущенные модули, множество скриптов, большинство проектных документов, множество статей на Perl.com и других связанных с Perl веб-сайтах, и Pod виртуальной машины Parrot.
редко читается в исходном виде, хотя он разработан для чтения без помощи инструмента форматирования. Вместо этого он читается с помощью инструмента perldoc или конвертируется в страницы руководства Unix или веб-страницы HTML.
Также возможно использовать pod в других контекстах, кроме Perl. Например, чтобы добавить простую документацию к сценариям bash, которые затем можно легко преобразовать в страницы руководства. Такое использование полагается на специфичные для языка хаки для скрытия части (ей) модуля, например (в bash) префикс раздела POD строкой :<<=cut, которая работает путем вызова команды bash no-op :с весь блок Pod в виде здесь документ в качестве входных данных.
Чистые файлы pod обычно имеют расширение .pod, но pod в основном используется непосредственно в коде Perl, который обычно использует .plи .pmрасширений. (Парсер интерпретатора Perl разработан для игнорирования pod в коде Perl.) В файлах исходного кода документация обычно помещается после маркера __END__( что также помогает выделять синтаксис в некоторых редакторах для отображения его в виде комментариев).
Pod можно легко преобразовать в другие форматы, например в некоторые из различных форматов Wiki, например: WikiWikiWeb, TWiki, UseModWiki, TiddlyWiki, Textile, MediaWiki, MoinMoin или Confluence с использованием Pod :: Simple: : Wiki.
Пример
Этот документ является синтаксически правильным модулем, который также пытается следовать основным соглашениям об именах разделов.
Исходный код
= head1 NAME My :: Module - An пример module = head1 ОБЗОР use My :: Module; мой $ object = My :: Module->new (); напечатать $ object->as_string; = head1 ОПИСАНИЕ На самом деле этого модуля не существует, он был создан с единственной целью продемонстрировать, как работает POD. = head2 Methods = over 12 = item C Возвращает новый объект My :: Module. = item C Возвращает строковое представление объекта. Это в основном для целей отладки. = back = head1 ЛИЦЕНЗИЯ Это выпущено под Художественной лицензией. См. L . = head1 AUTHOR Juerd - L = head1 СМОТРИ ТАКЖЕ L , L = cut
Подробности форматирования
Файлы Pod записываются в ASCII -совместимом кодировка, например Latin-1 или UTF-8. Парсер pod всегда предполагает, что файл, который он анализирует, не начинается с pod; он игнорирует все строки, пока не увидит директиву pod. директивы pod должны стоять в начале строки и начинаться со знака равенства. Затем синтаксический анализатор модуля будет считать, что все последующие строки являются модулями, пока не встретит строку, состоящую из директивы «= cut». Любой следующий контент игнорируется, пока синтаксический анализатор не обнаружит другую директиву модуля. Таким образом, pod может смешиваться с исполняемым исходным кодом, если синтаксический анализатор языка знает, как распознавать и игнорировать pod.
Содержимое пакета разделено на абзацы пустыми строками. Абзацы, начинающиеся с пробелов символов - табуляции или пробелы - считаются «дословными абзацами» и остаются полностью неформатированными; они используются для примера кода, ASCII art и т. д. Абзацы, начинающиеся со знака равенства, являются «абзацами команд»; последовательность буквенно-цифровых символов, следующая сразу за знаком равенства, рассматривается как директива модуля, а остальная часть абзаца форматируется в соответствии с этой директивой. Некоторые директивы также влияют на следующие параграфы. Если абзац начинается с чего-то помимо знака равенства или пробела, он считается «обычным абзацем».
Как обычные абзацы, так и содержимое абзацев команд анализируются на коды форматирования. Форматирование в pod очень простое; в основном он ограничен полужирным шрифтом, курсивом, подчеркиванием, моноширинным шрифтом и несколькими другими форматами. Также существует код для связи между документами модуля или другим разделом в том же документе. Коды форматирования состоят либо из:
- одной заглавной буквы, за которой следует знак «меньше» (<), the content to be formatted, and a greater-than sign (>), например
Bили - Одна заглавная буква, два или более знаков «меньше» (<<), 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>>. Эта форма часто используется для фрагментов кода, содержащих знак «больше», иначе код форматирования закончился бы..
Команды в модуле включают четыре уровня заголовков, маркированные и нумерованные списки, а также команды для пометки разделов как написанных на другом языке. Последняя функция позволяет назначать специальное форматирование синтаксическим анализаторам, которые его поддерживают.
См. Также
Ссылки
- Уолл, Ларри; Кристиансен, Том; Орвант, Джон (2000). Программирование на Perl (3-е изд.). Севастополь: O'Reilly Associates. ISBN 0-596-00027-8.
- Глава 15, «Работа с Pod», в Фой, Брайан d (2007). Освоение Perl. Севастополь: O'Reilly Media. ISBN 0-596-52724-1.
- Раздел 5.2, " Встраивание документации в сценарии оболочки ", в Albing, Carl; Vossen, JP; Cameron Newham. (2007). Поваренная книга bash: решения и примеры f или bash пользователей; O'Reilly Associates. ISBN 0-596-52678-4.
Внешние ссылки
