PerlManPages

Perl manpages

Ниже собраны письма, описывающие предлагаемый at@ (насколько понимаю) механизм работы с man-страницами в perl-пакетах, собранных и установленных в ALT Linux. По мере уточнения и понимания из них можно сделать документ с рекомендациями.

On Tue, Aug 16, 2005 at 12:12:42PM +0400, Konstantin A. Lepikhov wrote:
> т.е. можно приступать к убиванию секции man в perl- пакетах?

Да.  В своих пакетах я давно перестал паковать man3 страницы (т.е.
для модулей, вида Some::Module).

По части man1 страниц -- предлагаю не паковать man1 страницы для
специфических
перловых программ (например, pod2man или dprofpp), но паковать их для
"обычных" программ, написанных на перле (например, grepmail).

http://lists.altlinux.ru/pipermail/sisyphus/2005-August/067464.html

---

On Wed, Aug 17, 2005 at 08:25:45AM +0400, Alexey V. Novikov wrote:
> >This packages has two scripts:
> >1) /usr/sbin/perlman, capable of generating manual pages for all
> >perl modules and pod files under "core" and "vendor" directores;
> >2) /etc/cron.daily/perlman, a daily job that will generate/update
> >manual pages in /var/cache/perlman/man{1,3} and then will make  
> >symbolic links for them in /usr/local/man/man{1,3}.
> А может не надо их в         ^^^^^^^^^^?

Я над этим много думал.  man-страницы -- генерат.  Там выполняется  
большое количество перлового кода.  От рута пускать его нельзя.
Следовательно, напрямую ни в /usr, ни в /usr/local генерить ничего
нельзя.  Поэтому создаётся каталог /var/cache/perlman с правами 2775
root:man, а скрипт /usr/sbin/perlman пускается от псевдоюзера cacheman.

Далее, /usr/share должен быть полностью под контролем rpm.  Никакой
отсебятены туда лучше не ставить.  Поэтому линки на генерат я решил
ставить в /usr/local/man.  К счастью, поиск в этом каталоге работает "из
коробки".

$ grep /usr/local/man /etc/man.conf
MANPATH /usr/local/man
MANPATH_MAP     /usr/local/bin          /usr/local/man
MANPATH_MAP     /usr/local/sbin         /usr/local/man
$

http://lists.altlinux.ru/pipermail/sisyphus/2005-August/067483.html

---

On Wed, Aug 17, 2005 at 10:05:06AM +0400, Alexey Tourbin wrote:
> On Wed, Aug 17, 2005 at 09:42:12AM +0400, Alexey V. Novikov wrote:
> > >$ grep /usr/local/man /etc/man.conf
> > >MANPATH /usr/local/man
> > >MANPATH_MAP     /usr/local/bin          /usr/local/man
> > >MANPATH_MAP     /usr/local/sbin         /usr/local/man
> > >$
> > А если у меня /usr в read-only? Я что совсем без манов останусь?
> 
> А.  Я подумал, что предлагается ставить линки в /usr/share. :)
> Ну не знаю.  /usr/local иногда отдельным разделом бывает.
> Скрипт /etc/cron.daily/perlman помечен как %config.

Кстати, эти два скрипта имеют замечательную особенность: они
работают
в инкрементном режиме.  При первом запуске скрипты отрабатывают
несколько минут (на создании генерата), при последующих запусках --
несколько секунд.  То есть *если* в /usr/lib/perl5 ничего не изменилось,
*то* ни в /var/cache/perlman, ни в /usr/local/man также ничего меняться
не будет.

В этом состоит решение вашей проблемы: если вы только что поставили
или обновили перловые пакеты, то /usr у вас, очевидно, ещё смонтирован
в rw. Тогда можно вручную запустить /etc/cron.daily/perlman, он сделает
генерат и поставит симлинки в /usr/local/man.  После этого /usr можно
перемонтировать в ro.

http://lists.altlinux.ru/pipermail/sisyphus/2005-August/067491.html

Perl man3 pages

Alexey Tourbin <at@> in [sisyphus perl man3 pages] Ср Дек 1 19:06:12 MSK 2004

Есть предложение перестать паковать man3 страницы в перловых пакетах.
Обоснование: они идентичны pod документации, содержащейся в исходниках.

Если это будет сделано, то предлагается использовать следующие варианты
просмотра документации:

1) perldoc
Минус -- привыкшим к man придется "переучиваться".

2) написать обертку для man, в простейшем случае такую:

man()
{
	command man "$@" || perldoc "$@"
}

Минус -- для перловой документации man completion в zsh не будет
работать (но это несложно исправить).

3) написать скрипт, который сканирует дерево перловых исходников и
автоматически генерирует/обновляет man страницы по заданному пути (по
умолчанию -- наверное в /usr/local/man).  Минус -- этот скрипт придется
запускать вручную (время от времени или по мере необходимости).