Создать свой man linux
Guido нравится Linux за ее гибкость и возможности, которые невозможно встретить ни в одной другой ОС.
Перевод на Русский:
Pukhlyakov Kirill
Создание man-страниц
Введение
Документация к программному обеспечению зачастую более важна, чем само программное обеспечение, конечно если оно не используется только автором. Даже если я пишу программу, которую собираюсь использовать только сам, я все равно пишу документацию, потому, что через несколько месяцев можно забыть как использовать приложение, а хорошо написанная документация поможет мне за несколько секунд вспомнить это.
Традиционные утилиты Linux обычно хорошо документированы. Если вы хотите узнать как работает программа — вам достаточно набрать man commandname
Преимущество man-страниц перед другими формами документации состоит в следующем
- Они доступны на любом терминале Linux в любой момент времени
- Их легко преобразовать в любой другой формат: HTML, PDF, Postscript, Text.
- 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-страницы несложный процесс. Существует специальный язык в котором макросы форматирования начинаются с «.». Перечислим наиболее важные:
.TH -> Заголовок man-страницы .SH -> Заголовок раздела .PP -> Новый параграф ." -> Комментарий .TP -> Новый абзац - начинается двумя строками ниже этого макроса
Синтаксис макроса .TH:
.TH [name of program] [section number] [center footer] [left footer] [center header]
Синтаксис макроса .SH:
.SH текст для заголовка
Макрос .PP используется для перевода строки.
Иногда полезно вставить фрагмент кода. Это делается следующим образом:
.nf _ваш_заранее_отформатированный_ _текст_располагается_здесь_____ .fi
Все макросы форматирования 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 другое.
Простая 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-страницы
nroff -man your_manpagefile.1 | less
groff -man -Tascii your_manpagefile.1 | less
nroff -man your_manpagefile.1 | col -b > xxxx.txt
groff -man -Tps your_manpagefile.1 > your_manpagefile.ps
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 display a short help text B use the given device instead of /dev/cdrom B 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)
Ссылки
Страница отзывов
2003-11-03, generated by lfparser version 2.43
How to make a man page for my shell script?
How do I create a man page for my shell script?
I couldn’t find a beginner approach on how to make man pages on Google. What is the easiest way to make my own Man page, based of a template, and install it with my script?
Yes, but is says that I need a specially formatted file and it doesn’t tell me how to format it :/ . Also I don’t understand how to install it.
5 Answers 5
I’d recommend you to use Grapse, an online man page editor, since you can see the results in real-time. I believe it’s really useful for beginners.
What about using pandoc. You can write document in markdown (or even html, latex) and can covert to html, pdf, word,man pages, epub, . This way you can write documentation in one format and convert/distribute in any format you like
C1sc0 there is an error in your answer.
to make your own man page, follow the steps below:
$ cd /usr/bin $ nano your_function 3- copy paste this template of man (maual) page and then personalize it depending on your project:
./" Manpage for your_fonction .TH man 1 "10 September 2017" "1.0" "your_fonction man page" .SH NAME your_fonction - do. .SH SYNOPSIS your_fonction [optionnal argument] [optionnal argument] .SH DESCRIPTION your_fonction is a function which . .SH OPTIONS your_fonction does not take any options .SH BUGS No known bugs. .SH AUTHOR written by your_name (your_website or your_github or whatever) .SH REPORTING BUGS you_github_repository/isssues for example 4- you have to choose in which directory man your file has to be, look at :
you see man1, man2. These are the categories:
(man1) 1 — Commands available to users
(man2) 2 — Unix and C system calls
(man3) 3 — C library routines for C programs
(man4) 4 — Special file names
(man5) 5 — File formats and conventions for files used by Unix
(man6) 6 — Games
(man7) 7 — Word processing packages
(man8) 8 — System administration commands and procedures
here for the example the destination will be man1, so:
6- make a copy with the good suffix:
$ cp your_function your_function.1 8- send it to the good directory, here for the example man1:
$ cp your_function.1.gz /usr/share/man/man1/ that’s done, you can test your beautiful man page !