[LinuxFocus-icon]
<--  | Домой  | Карта  | Индекс  | Поиск
Новости | Архивы | Ссылки | Про LF
[an error occurred while processing this directive]
[Photo of the Author]
автор Guido Socher (homepage)

Об авторе:

Guido нравится Linux за ее гибкость и возможности, которые невозможно встретить ни в одной другой ОС.



Перевод на Русский:
Pukhlyakov Kirill <kirill(at)linuxfocus.org>

Содержание:

 

Создание man-страниц

man

Резюме:

Работа каждой программы запускаемой из UNIX shell'а описана в man-странице. В заметке мы рассмотрим процесс создания этих страниц.

_________________ _________________ _________________

 

Введение

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

Традиционные утилиты Linux обычно хорошо документированы. Если вы хотите узнать как работает программа - вам достаточно набрать man commandname

Преимущество man-страниц перед другими формами документации состоит в следующем

  1. Они доступны на любом терминале Linux в любой момент времени
  2. Их легко преобразовать в любой другой формат: HTML, PDF, Postscript, Text,...
  3. Man страницы можно смотреть не только в терминальном режиме, но и в приложениях, например в konqueror (просто наберите: man:commandname)
 

Разделы

Man-страницы собраны по разделам, примерно также как книги - по главам. Например есть две man-страницы для команды printf. Одна для библиотечной функции языка 'C' ( раздел 3 ), а другая - для команды shell'а ( раздел 1 ). 
> 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.

 

MANPATH

Программа man ищет документацию основываясь на значении переменной MANPATH. К сожалению многие дистрибутивы Linux некорректно инициализируют эту переменную. Обычно каталог /usr/lib/perl5/man, в котором находятся описания различных функций языка 'perl' не указан в этой переменной. Вы можете добавить этот каталог следующим образом: 
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" и посмотрите доступен ли теперь этот каталог.  

Форматирование

Создание man-страницы несложный процесс. Существует специальный язык в котором макросы форматирования начинаются с ".". Перечислим наиболее важные: 
.TH -> Заголовок man-страницы
.SH -> Заголовок раздела
.PP -> Новый параграф
."  -> Комментарий
.TP -> Новый абзац - начинается двумя строками ниже этого макроса


Синтаксис макроса .TH:
.TH [name of program] [section number] [center footer] [left footer] [center header]

Синтаксис макроса .SH:
.SH текст для заголовка


Макрос .PP используется для перевода строки.

Иногда полезно вставить фрагмент кода. Это делается следующим образом: 
.nf
_ваш_заранее_отформатированный_
_текст_располагается_здесь_____
.fi
Обратите внимание, что это макросы groff/nroff. Данная конструкция работает на многих Unix системах.

Все макросы форматирования man-страниц хорошо документированы на man'е groff_man(7) ( Здесь вы можете посмотреть html версию этой станицы ). В этой заметке я не буду объяснять эти макросы, советую вам самостоятельно изучить документацию, она достаточно подробная и содержит всю необходимую вам информацию.

 

Главы

Перед тем как создать нашу первую man-страницу рассмотрим главы из которых они состоят: 
NAME           раздел Name, содержит название функции или команды.
SYNOPSIS       использование.
DESCRIPTION    описание.
OPTIONS        параметры.
RETURN VALUES  возвращаемые значения.
ENVIRONMENT    описание переменных окружения.
FILES          ассоциированные файлы.
EXAMPLES       примеры.
DIAGNOSTICS    используется для раздела 4 ( устройства ).
ERRORS         ошибки и обработка сигналов.
SEE ALSO       ссылки.
STANDARDS      стандарты.
BUGS           предупреждения.
SECURITY CONSIDERATIONS
               вопросы безопасности, которые надо знать.
other          другое.
 

Простая man-страница

Создадим простую man-страницу. Наберите все это в вашем текстовом редакторе и сохраните как cdspeed.1. 
.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)
Здесь вы можете посмотреть эту страницу.  

Просмотр и форматирование man-страницы

Создавая man-страницу вы можете время от времени просматривать как она выглядит: 
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
 

Использование perl POD для создания man-страниц

Я знаю людей, которые считают странным простое редактирование man-страниц в текстовом редакторе. Они предпочитают генерировать их. В этом случае хорошим выбором является формат perl POD. Вы можете написать страницу, используя синтаксис POD, и затем выполнить следующую команду: 
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)
 

Ссылки

 

Страница отзывов

У каждой заметки есть страница отзывов. На этой странице вы можете оставить свой комментарий или просмотреть комментарии других читателей
 talkback page 
<--, перейти к начальной странице выпуска
Webpages maintained by the LinuxFocus Editor team
© Guido Socher, FDL
LinuxFocus.org 		Translation information:
en --> -- : Guido Socher (homepage)
en --> ru: Pukhlyakov Kirill <kirill(at)linuxfocus.org>

2003-11-03, generated by lfparser version 2.43