=encoding utf8

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

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


=head1 DESCRIPTION (ОПИСАНИЕ)

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

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

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

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

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

=over 4

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

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

    foo, bar - programs to do something

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

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

Короткий пример использования программ и функций. Этот раздел
является обязательным для 3 раздела страницы. Для документации Perl модуля
 обычно удобнее иметь содержимое этой секции в виде короткого блока
  с типичными способами использования модуля.
   
=item DESCRIPTION (ОПИСАНИЕ)

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

    =head2 Normal Usage

    =head2 Advanced Features

    =head2 Writing Configuration Files

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

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

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

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

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

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

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

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

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

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

=item ERRORS (ОШИБКИ)

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

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

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

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

=item EXAMPLES (ПРИМЕРЫ)

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

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

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

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

    =over 6

    =item HOME

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

    =back

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

=item FILES

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

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

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

=item BUGS (ОШИБКИ)

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

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

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

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

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

=item AUTHOR (АВТОР)

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

=item HISTORY

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

=item 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).

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

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

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

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

=back

Для документации объектно ориентированных библиотек или модулей может понадобиться использовать
 секции 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.

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

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

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

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

=head1 АВТОР (AUTHOR)

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

=head1 АВТОРСКИЕ ПРАВА И ЛИЦЕНЗИЯ (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.

=cut

=head1 ПЕРЕВОДЧИКИ
  
=over
  
=item * Николай Мишин C<< <mi@ya.ru> >>
 
=back
