Описание политики Debian (Документация) — Глава 6

1 Man страницы

Ты должен устанавливать man страницы в исходном nroff формате, в соответствующих /usr/share/man. Ты должен использовать только разделы с 1 по 9 (подробней смотри FHS). Ты не должен устанавливать переформатированные `cat страницы’.

Если man страница недоступна для какой-то программы, утилиты или функции и об этом сообщается как об ошибке в debian-bugs, то вместо этого нужно сделать символическую ссылку на undocumented(7) [не документировано] вместо запрашиваемой man страницы. Эту символическую ссылку можно создать из debian/rules так:

ln -s ../man7/undocumented.7.gz \

debian/tmp/usr/share/man/man[1-9]/требуемая_man_страница.[1-9].gz

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

Ты можешь жаловаться на отсутствие man страницы вышестоящим авторам, и сообщать об ошибке, как описывалось, в систему отслеживания ошибок Debian. Хотя Проект GNU в общем не рассматривает отсутствие man страницы как ошибку, мы все равно так делаем—если они говорят что не считают это ошибкой, ты всё равно должен оставить ошибку не рассмотренной в нашей системе отслеживания ошибок.

Man страницы должны устанавливаться сжатыми с помощью gzip -9.

Если какая-то man страница должна быть доступна через несколько имён, то для этого лучше использовать символическую ссылку, а не свойство .so, но не надо трогать соответствующие части вышестоящих исходников заменяя .so на символические ссылки—не делай этого, если это не трудно. Не создавай жёстких ссылок в каталогах man страниц, и не пользуйся устаревшими именами файлов в .so директивах. Имя файла в .so в man странице должно быть относительно основного дерева man страниц (обычно /usr/share/man).

2. Документы Info

Документы Info должны устанавливаться в /usr/share/info. Они должны быть сжаты с помощью gzip -9.

Твой пакет должен вызывать install-info для обновления файла Info dir, в пост-установочном сценарии:

install-info --quiet --section Development Development \

/usr/share/info/foobar.info

Хорошей идеей будет указывать раздел для местоположения своей программы; это выполняется с помощью ключа --section. Чтобы определить какой раздел использовать, ты должен посмотреть на /usr/share/info/dir своей системы и выбрать наиболее подходящий (или создать новый раздел, если ни один раздел не подходит). Заметим, что у флага --section есть два аргумента; первый является регулярным выражением которое равносильно (нечувствительное к регистру) существующему разделу, второй используется для создания нового.

Ты должен удалить записи в сценарии пред-удаления:

install-info --quiet --remove /usr/share/info/foobar.info

Если install-info не найдёт описываемую запись в Info файле, ты должен будешь указать другую. Подробней смотри install-info(8).

3. Дополнительная документация

Любая дополнительная документация, поставляемая с пакетом может устанавливаться по усмотрению сопровождающего пакета. Текстовая документация должна быть установлена в каталог /usr/share/doc/пакет, где пакет — имя пакета, и сжата с помощью gzip -9, если он большой.

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

Часто хорошей идеей будет помещать текстовые информационные файлы (READMEs, changelog и так далее), которые есть в исходном пакете, в /usr/share/doc/пакет в двоичный пакет. Однако, конечно, тебе не нужно устанавливать инструкции по сборке и установке пакета!

4. Доступ к документации

Составитель окончательной версии Debian помещает всю дополнительную документацию в /usr/doc/пакет. Чтобы облегчить переход на /usr/share/doc/пакет, каждый пакет должен сопровождаться символической ссылкой /usr/doc/пакет, которая указывает на новое местоположение своей документации в /usr/share/doc/пакет.

Символическая ссылка должна создаваться при установке пакета; она не должна содержаться в самом пакете из-за проблем с dpkg. Одним из приемлемых путей достигнуть этого будет, например, разместить в postinst пакета:

if [ "$1" = "configure" ]; then

             if [ -d /usr/doc -a ! -e /usr/doc/#PACKAGE# \

                 -a -d /usr/share/doc/#PACKAGE# ]; then

                     ln -sf ../share/doc/#PACKAGE# /usr/doc/#PACKAGE#

             fi

       fi

И в prerm пакета:

if [ \( "$1" = "upgrade" -o "$1" = "remove" \) \

            -a -L /usr/doc/#PACKAGE# ]; then

             rm -f /usr/doc/#PACKAGE#

       fi

5. Предпочтительные форматы документации

Объединение Debian документации осуществляется через HTML.

Если твой пакет имеет обширную документацию на языке разметки, который можно преобразовать в другие форматы, то ты должен, если возможно, распространять HTML версию в двоичном пакете, в каталоге /usr/share/doc/соответствующий пакет или его подкаталогах.

Другие форматы, такие как PostScript, могут поставляться по твоему усмотрению.

6. Информация об авторских правах

Каждый пакет должен сопровождаться дословной копией своих авторских прав и лицензией распространения в файле /usr/share/doc/<имя-пакета>/copyright. Этот файл должен быть или сжат или быть символической ссылкой.

Также, файл copyright должен разъяснять где можно получить вышестоящие исходники (если есть), и кратко пояснять какие изменения были сделаны в Debian версии пакета, по сравнению с первоначальной. Там должно быть имя первоначальных авторов пакета и сопровождающего(их) Debian, которые создавали пакет.

/usr/share/doc/<имя-пакета> может символической ссылкой на каталог в /usr/share/doc если только оба из двух пакетов создавались из одного источника и первый пакет имеет "Depends" связь на второй. Эти правила важны, т.к. авторские права должны выделяться механическим путём.

Пакеты, распространяемые под UCB BSD лицензией, Artistic лицензией, GNU GPL, и GNU LGPL, должны ссылаться на файлы /usr/share/common-licenses/BSD, /usr/share/common-licenses/Artistic, /usr/share/common-licenses/GPL, и /usr/share/common-licenses/LGPL.

Не используй файл copyright как обычный файл README. Если пакет имеет такой файл, то он должен устанавливаться в /usr/share/doc/пакет/README или README.Debian или другое подобное место.

7. Примеры

Любые примеры (настроек, исходных файлов, чего угодно) должны устанавливаться в каталог /usr/share/doc/пакет/examples. На эти файлы не должно быть ссылок из любой программы—они существуют только чтобы помочь системному администратору и пользователям в качестве документации.

Архитектуро-зависимые файлы примеров должны устанавливаться в каталог /usr/lib/пакет/examples, и файлы в /usr/share/doc/пакет/examples должны быть символическими ссылками на файлы в нём. Или последний каталог может быть символической ссылкой на первый.

8. Файлы changelog

Этот файл должен содержать копию файла debian/changelog дерева исходников Debian,и копию вышестоящего файла changelog, если есть. Файл debian/changelog должен быть установлен в /usr/share/doc/пакет в виде changelog.Debian.gz. Если вышестоящий файл changelog является простым текстом, он должен быть доступен как /usr/share/doc/пакет/changelog.gz. Если вышестоящий файл changelog в формате HTML, он должен быть доступен как /usr/share/doc/пакет/changelog.html.gz.

Версия простого текста changelog должна быть доступна как /usr/doc/пакет/changelog.gz (она может быть создана с помощью lynx -dump -nolist). Если вышестоящие changelog файлы ещё не удовлетворяют этим соглашениям об именах, то это нужно сделать или переименованием файлов или добавлением символических ссылок, по усмотрению разработчика пакета.

Оба файл должны быть сжаты с помощью gzip -9, т.к. они становятся больше со временем, даже если сначала они маленькие.

Если пакет имеет только один changelog, который используется и как Debian changelog и как вышестоящий, из-за одинакового вышестоящего сопровождающего, то этот changelog обычно устанавливается как /usr/share/doc/пакет/changelog.gz; если вышестоящие сопровождающие разные, но вышестоящего changelog нет, то Debian changelog должен называться changelog.Debian.gz.