NAME/НАИМЕНОВАНИЕ

perlpodstyle - Руководство по стилю Perl POD

DESCRIPTION (ОПИСАНИЕ)

Это общие рекомендации о том, как писать Perl POD документацию для скриптов и модулей, на основе общих принципов для написания хорошей страницы UNIX man (далее маны). Все эти руководящие принципы являются, конечно, не обязательными, но следование им сделает вашу документацию более последовательной по отношению к другой документации в системе.

Имя программы пишется жирным шрифтом (с использованием B<>) везде, где оно упоминается, как и все опции программы. Аргументы должны быть написаны курсивом(italics) (I<>). Имена функций традиционно пишутся курсивом; если вы пишете функцию, как function(), то Pod::Man позаботиться об этом за вас. Исходный код или команды должны быть в C<>. Ссылки на другие man страницы должны быть в форме manpage(section) или L<manpage(section)>, и Pod::Man будет автоматически форматировать их надлежащим образом. Вторая форма, с L<>, используется для запроса, когда POD форматтер делает ссылку на man страницу, если это возможно. Как исключение некоторые обычно опускают секцию , когда ссылаются на документацию модуля , поскольку не ясно, какой раздел документации использовать; используйте L<Module::Name> для модуля вместо ссылки.

Ссылки на другие программы или функции, как правило, в форме ссылки на ман (man) страницу так, что могут быть предоставлены перекрестные ссылки и тому подобное. Можно переусердствовать в этом, так что будьте осторожны, не загромождайте вашу документацию слишком большим количеством разметки. Ссылки на другие программы, которые не предоставляются как ман страницы должны быть заключены в B<>.

Основные заголовки должны быть написаны с помощью директивы =head1 и исторически написаны в довольно поразительном формате ВСЕ ВЕРХНЕМ РЕГИСТРЕ; это не является обязательным, но настоятельно рекомендуется там, чтобы у секции было последовательное наименование среди различных пакетов программного обеспечения. Незначительные заголовки могут быть включены с помощью =head2 и они, как правило, в смешанном регистре.

Стандартными разделами страницы руководства являются:

NAME (НАИМЕНОВАНИЕ)

Обязательная Секция; следует список с разделителями запятыми программ или функций, которые задокументированы на этой POD странице , такие как:

    foo, bar - programs to do something

Индексаторы страниц руководства часто очень разборчивы в формате этого раздела, поэтому не пишите ничего в нем кроме этой строки. Каждая программа или функция, задокументированная в этой POD странице должна быть перечислена, разделенная запятой и пробелом. Для модуля Perl просто дайте имя модуля. Один и только один тире должен разделять список программ или функции из описания. Не используйте разметку, такую как C<> или B<> где-либо в этой строке. Функции не должна писаться с () или тому подобное. Для описания идеально подходит одна строка, даже если ман-программа заменяет тире несколькими табуляторами.

SYNOPSIS (КРАТКИЙ СИНТАКСИС)

Короткий пример использования программ и функций. Этот раздел является обязательным для 3 раздела страницы. Для документации Perl модуля обычно удобнее иметь содержимое этой секции в виде короткого блока с типичными способами использования модуля.

DESCRIPTION (ОПИСАНИЕ)

Расширенное описание и обсуждение программы или функции, или тела документации ман-страницы документа (программы). Если этот раздел особенно длинен, то будет хорошей идеей, чтобы разбить его на подразделы с директивами =head2 такими, как:

    =head2 Normal Usage

    =head2 Advanced Features

    =head2 Writing Configuration Files

или то, что подходит для вашей документации.

Для модуля, как правило, документации интерфейсов обычно идет в виде списка с =item для каждого интерфейса. В зависимости от числа интерфейсов вы можете расположить документацию раздельно по секциям для METHODS (МЕТОДОВ), FUNCTIONS (ФУНКЦИЙ), CLASS METHODS (МЕТОДОВ КЛАССА), или INSTANCE METHODS (МЕТОДОВ ЭКЗЕМПЛЯРА КЛАССА) и сохранить раздел DESCRIPTION для небольшого описания.

OPTIONS (ПАРАМЕТРЫ)

Подробное описание каждого из параметров командной строки, которые принимает программа. Это описание должно быть отдельно от введения (description) , т.к. его могут использовать парсеры такие, как Pod::Usage. Обычно этот раздел представляется в виде списка, где каждый параметр находится в отдельном =item. Специфические строковые параметры должны быть заключены в B<>. Любые значения, которые принимает параметр должны быть заключены в I<>. Например, раздел для параметра --section=manext может быть показан, как:

    =item B<--section>=I<manext>

Синонимы параметров (например, короткие и длинные формы), разделенные запятой и пробелом на той же =item линии, или опционально в списке представлены, как их собственный элемент со ссылкой на каноническое имя. Например, --section также может быть записана как -s, выше, то будет:

    =item B<-s> I<manext>, B<--section>=I<manext>

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

RETURN VALUE (ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ)

То, что программа или функция возвращает, если выполнена успешно. Этот раздел может быть опущен для программ чьи коды точного выхода не важны, они возвращают 0 на успех и не нулевой ответ в случае провала как стандарт. Этот раздел всегда должен присутствовать для функций. Для модулей это может быть полезным для суммирования возвращаемых значений из интерфейса модуля, или это может больше полезно для обсуждения возвращаемых значений отдельно в документации каждой функции или метода, которыми обеспечивает модуль.

ERRORS (ОШИБКИ)

Исключения (exceptions), ошибки кодов возврата, статусы выхода (exit statuses) и параметры номеров ошибок (errno settings). Обычно используется для функции или документации модуля; документация программы вместо этого использует диагностики (DIAGNOSTICS). Общее эмпирическое правило, что ошибки, выводящиеся на STDOUT или STDERR и предназначенные для конечного пользователя документируются в диагностике (DIAGNOSTICS), а ошибки внутреннего (internal) вызова программы, предназначенные для других программистов описаны в ошибках(ERRORS). Когда документируемая функция устанавливает номер ошибки (errno), то полный список возможных номеров ошибок (errno) должен быть приведен здесь.

DIAGNOSTICS (ДИАГНОСТИКА)

Все возможные сообщения, которые программа может распечатать, и что они означают. Вы возможно, пожелает следовать тому же стилю документации, что и документация Perl; посмотрите perldiag(1) для получения более подробной информации (и посмотрите также исходный код (source) POD).

Если это возможно, просьба включите подробную информацию о то, что должен сделать пользователь для того, чтобы исправить ошибку; документирование ошибки как "входной буфер слишком маленький" ( "the input buffer is too small"), не сообщая пользователю, как увеличить размер входного буфера (input buffer) (или по крайней мере сказать им, что это невозможно) не очень полезно.

EXAMPLES (ПРИМЕРЫ)

Дайте несколько примеров использования программы или функции. Не скупитесь; пользователи часто находят это наиболее полезной частью документации. Примеры обычно предоставляются в виде подробных параграфов.

Не показывайте пример не объясняя, что он делает. Добавление короткого комментария, говорящего о том, что этот пример будет делать может увеличить значение этого примера безмерно(immensely).

ENVIRONMENT (ОКРУЖЕНИЕ)

Переменные среды, в которых работает программа обычно представлены в виде списка, используя =over, =item, и =back. Например:

    =over 6

    =item HOME

    Используется для определения домашнего каталога пользователя. F<.foorc> в этом
    каталоге читается для подробной конфигурации, если он существует.

    =back

Так как переменные среды, как правило, представлены прописными буквами, никакого дополнительного специального форматирования не нужно; они сами достаточно яркие.

FILES

Все файлы, используемые программой или функцией, обычно представлены в виде списка, и то, как он их используют. Имена файлов должны быть заключены в F<>. Это особенно важно для файлов документов, которые будут потенциально изменены.

CAVEATS (ПРЕДОСТЕРЕЖЕНИЯ)

Вещи, которые требуют особого внимания, иногда называются предупреждениями (WARNINGS).

BUGS (ОШИБКИ)

Вещи, которые ломаются или просто не работают правильно.

RESTRICTIONS (ОГРАНИЧЕНИЯ)

Ошибки, которые вы не планируете исправить. :-)

NOTES (ПРИМЕЧАНИЯ)

Прочие комментарии.

AUTHOR (АВТОР)

Кто написал это (используйте АВТОРЫ (AUTHORS) для несколько человек). Хорошей идеей будет включить ваш текущий адрес электронной почты (или некоторые адреса электронной почты, на которые должны быть отправлены отчеты об ошибках ) или некоторая другая контактная информация так, чтобы пользователи могли связаться с вами. Помните, документацию программы, как правило, читают дикие гораздо дольше, чем вы ожидаете и выбирайте метод контакта именно для них;).

HISTORY

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

COPYRIGHT AND LICENSE (АВТОРСКИЕ ПРАВА И ЛИЦЕНЗИЯ)

Для авторского права (For copyright)

    Copyright YEAR(s) YOUR NAME(s)

((C) не обязателен. Также не обязательно писать "all rights reserved".)

Для лицензирования самым простым способом является использование лицензии Perl:

    Эта библиотека является свободным программным обеспечением; вы можете распространять её и/или модифицировать
    на тех же условиях, что и сам Perl.

    This library is free software; you may redistribute it and/or modify
    it under the same terms as Perl itself.

Такая лицензия позволит использовать ваш модуль вместе с Perl. Обратите внимание, что данный пример лицензирования не является обязательным или требованием, вы конечно, свободны выбирать любую лицензию (any licensing).

SEE ALSO (СМОТРИТЕ ТАКЖЕ)

Другие ман-страницы (man pages), для проверки, такие как man(1), man(7), makewhatis(8), или catman(8). Обычно простой список ман-страниц, разделенных запятыми, или пункт, дающий работающие ссылки. Ссылки на ман-страницы, если они используют стандартную форму name(section), не должны быть заключены в L<> (хотя это рекомендуется).

Если пакет имеет список рассылки, то включая URL-адрес или инструкции о том, как на нее подписаться здесь.

Если пакет имеет веб-сайт, то его URL-адрес включают здесь.

Для документации объектно ориентированных библиотек или модулей может понадобиться использовать секции CONSTRUCTORS (КОНСТРУКТОРЫ) и METHODS (МЕТОДЫ), или CLASS METHODS (МЕТОДЫ КЛАССА) и INSTANCE METHODS (МЕТОДЫ ЭКЗЕМПЛЯРА КЛАССА) , для подробной документации частей библиотеки и сохраняя параграф DESCRIPTION (Описание) для небольшого обзора. Большим модулям с функциональным интерфейсом могут потребоваться использовать параграфы FUNCTIONS (ФУНКЦИИ) по аналогичным причинам. Некоторые люди используют OVERVIEW (Обзор) для суммарного описания, если оно достаточно большое.

Последовательность разделов варьируется, хотя NAME (НАИМЕНОВАНИЕ) всегда должно быть первой секцией (иначе вы сломаете систему ман-страниц) и NAME (НАИМЕНОВАНИЕ), SYNOPSIS(КРАТКИЙ ОБЗОР), DESCRIPTION (ОПИСАНИЕ), и OPTIONS (ОПЦИИ, ПАРАМЕТРЫ) обычно всегда располагаются в начале и в таком порядке, как они представлены. Обычно SEE ALSO (СМОТРИТЕ ТАКЖЕ), AUTHOR (АВТОР) и аналогичные материалы должны быть оставлены для окончания страницы. Некоторые системы также перемещают WARNINGS (ПРЕДУПРЕЖДЕНИЯ) и NOTES (ПРИМЕЧАНИЯ) в конец. Приведенный выше порядок должен быть разумным для большинства целей.

Некоторые системы используют CONFORMING TO (СООТВЕТСТВУЮТ ЭТОМУ), чтобы обратить внимание на соответствие стандартам и MT-LEVEL (УРОВЕНЬ МОНТИРОВАНИЯ) чтобы отметить одновременно безвредность для использования в многопоточных программах или обработчиками сигналов (signal handlers). Эти заголовки в первую очередь полезны при документировании частей библиотек C.

Наконец, общее замечание старайтесь не использовать чрезмерное количество разметки. Как описано здесь и в Pod::Man, вы можете спокойно оставить Perl переменные, имена функций, ссылки на ман-страницы и т.п. без всяких украшений, разметки и POD переводчики будут вычислять его для вас. Это делает возможным редактирование документации позднее гораздо легче. Обратите внимание, что многие существующие переводчики будут делать неправильные вещи с адресами электронной почты, завернутой в L<> , так что не делайте этого.

СМОТРИТЕ ТАКЖЕ (SEE ALSO)

Для получения дополнительной информации, которая может быть более точной для ваших конкретных система, см в зависимости от вашей системы нумерации руководств или man(5) или man(7).

Эта документация ведется в рамках распределения podlators. Текущая версия всегда доступна со своего веб-сайта на <http://www.eyrie.org/~eagle/software/podlators/>.

АВТОР (AUTHOR)

Русс Албери (Russ Allbery) <rra@stanford.edu>, значительная часть этой документации взята из документации оригинала pod2man реализованной Лари Воллом (Larry Wall) и Томом Кристиансеном (Tom Christiansen).

АВТОРСКИЕ ПРАВА И ЛИЦЕНЗИЯ (COPYRIGHT AND LICENSE)

Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010 Russ Allbery <rra@stanford.edu>.

Эта документация является свободным программным обеспечением; вы можете распространять её и/или модифицировать на тех же условиях, как и сам Perl.

This documentation is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

ПЕРЕВОДЧИКИ

• Николай Мишин <mi@ya.ru>