![[Photo of the Author]](../../common/images/Guido-S.gif)
original in en Guido Socher
en to ru Pukhlyakov Kirill
Guido нравится Linux за ее гибкость и возможности, которые невозможно встретить ни в одной другой ОС.
Традиционные утилиты Linux обычно хорошо документированы. Если вы хотите узнать как работает программа - вам достаточно набрать man commandname
Преимущество man-страниц перед другими формами документации состоит в следующем
> whichman -0 printf /usr/share/man/man1/printf.1.bz2 /usr/share/man/man3/printf.3.bz2Перечислим разделы:
Раздел 1 Пользовательские команды. 2 Системные вызовы, т.е. те, которые предоставляет ядро. 3 Подпрограммы ( библиотечные функции ). 4 Устройства ( файлы в каталоге /dev ). 5 Описания форматов файлов ( например /etc/passwd ). 6 Игры. 7 Разное. 8 Инструменты для системного администрирования (доступные только root'у ). 9 Другое. n Новая документация. l Локальная документация ( относится к данной системе ).Итак, вы набираете "man 1 printf" и читаете документацию для команды shell'а, набираете "man 3 printf" и видите документацию библиотечной функции языка 'C'. Набрав просто "man printf" вы увидите первую найденную страницу ( обычно это "printf" из раздела 1 ).
Проверить количество разделов, в которых находится интересующая вас
документация можно используя программу whichman ( вы можете загрузить ее
с моей домашней страницы )
или набрав "man:printf" в konqueror.
Bash: MANPATH="/usr/local/man:/usr/man:/usr/share/man:/usr/X11R6/man:/usr/lib/perl5/man" export MANPATH Tcsh: setenv MANPATH "/usr/local/man:/usr/man:/usr/share/man:/usr/X11R6/man:/usr/lib/perl5/man"После этого наберите "man Pod::Man" и посмотрите доступен ли теперь этот каталог.
.TH -> Заголовок man-страницы .SH -> Заголовок раздела .PP -> Новый параграф ." -> Комментарий .TP -> Новый абзац - начинается двумя строками ниже этого макроса
.nf _ваш_заранее_отформатированный_ _текст_располагается_здесь_____ .fiОбратите внимание, что это макросы groff/nroff. Данная конструкция работает на многих Unix системах.
Все макросы форматирования man-страниц хорошо документированы на man'е groff_man(7) ( Здесь вы можете посмотреть html версию этой станицы ). В этой заметке я не буду объяснять эти макросы, советую вам самостоятельно изучить документацию, она достаточно подробная и содержит всю необходимую вам информацию.
NAME раздел Name, содержит название функции или команды.
SYNOPSIS использование.
DESCRIPTION описание.
OPTIONS параметры.
RETURN VALUES возвращаемые значения.
ENVIRONMENT описание переменных окружения.
FILES ассоциированные файлы.
EXAMPLES примеры.
DIAGNOSTICS используется для раздела 4 ( устройства ).
ERRORS ошибки и обработка сигналов.
SEE ALSO ссылки.
STANDARDS стандарты.
BUGS предупреждения.
SECURITY CONSIDERATIONS
вопросы безопасности, которые надо знать.
other другое.
.TH cdspeed 1 "September 10, 2003" "version 0.3" "USER COMMANDS" .SH NAME cdspeed \- decrease the speed of you cdrom to get faster access time .SH SYNOPSIS .B cdspeed [\-h] [\-d device] \-s speed .SH DESCRIPTION Modern cdrom drives are too fast. It can take several seconds on a 60x speed cdrom drive to spin it up and read data from the drive. The result is that these drives are just a lot slower than a 8x or 24x drive. This is especially true if you are only occasionally (e.g every 5 seconds) reading a small file. This utility limits the speed and makes the drive more responsive when accessing small files. .PP cdspeed makes the drive also less noisy and is very useful if you want to listen to music on your computer. .SH OPTIONS .TP \-h display a short help text .TP \-d use the given device instead of /dev/cdrom .TP \-s set the speed. The argument is a integer. Zero means restore maximum speed. .SH EXAMPLES .TP Set the maximum speed to 8 speed cdrom: .B cdspeed \-s 8 .PP .TP Restore maximum speed: .B cdspeed \-s 0 .PP .SH EXIT STATUS cdspeed returns a zero exist status if it succeeds to change to set the maximum speed of the cdrom drive. Non zero is returned in case of failure. .SH AUTHOR Guido Socher (guido (at) linuxfocus.org) .SH SEE ALSO eject(1)Здесь вы можете посмотреть эту страницу.
nroff -man your_manpagefile.1 | lessили
groff -man -Tascii your_manpagefile.1 | lessДля преобразования man-страницы в формат обычного текста используйте следующую конструкцию:
nroff -man your_manpagefile.1 | col -b > xxxx.txtДля преобразования в формат Postscript ( для печати или дальнейшего преобразования в формат pdf ):
groff -man -Tps your_manpagefile.1 > your_manpagefile.psДля преобразования в формат html:
man2html your_manpagefile.1
pod2man your_manpagefile.pod > your_manpagefile.1Синтаксис языка для создания документов формата perl pod описан в man-странице perlpod. Созданная нами man-страница будет выглядеть в формате pod следующим образом, как показано ниже. Обратите внимание на пробелы и пустые строки когда будете создавать документацию в формате POD.
=head1 NAME
cdspeed - decrease the speed of you cdrom to get faster access time
=head1 SYNOPSIS
cdspeed [-h] [-d device] -s speed
=head1 DESCRIPTION
Modern cdrom drives are too fast. It can take several seconds on a 60x
speed cdrom drive to spin it up and read data from the drive. The result
is that these drives are just a lot slower than a 8x or 24x drive.
This is especially true if you are only occasionally (e.g every 5 seconds)
reading a small file. This utility limits the speed and makes the drive
more responsive when accessing small files.
cdspeed makes the drive also less noisy and is very useful
if you want to listen to music on your computer.
=head1 OPTIONS
B<-h> display a short help text
B<-d> use the given device instead of /dev/cdrom
B<-s> set the speed. The argument is a integer. Zero
means restore maximum speed.
=head1 EXAMPLES
Set the maximum speed to 8 speed cdrom:
cdspeed -s 8
Restore maximum speed:
cdspeed -s 0
=head1 EXIT STATUS
cdspeed returns a zero exist status if it succeeds to
change to set the maximum speed of the cdrom drive. Non
zero is returned in case of failure.
=head1 AUTHOR
Guido Socher
=head1 SEE ALSO
eject(1)