Yaleks: Новая: == Groff Создаем man-страницы == : ''Стоит вам закопаться в Linux поглубже, как вы принимаетесь чудить: например,...

2009-02-01T13:26:53Z

Новая: == Groff Создаем man-страницы == : ''Стоит вам закопаться в Linux поглубже, как вы принимаетесь чудить: например,...

Новая страница

== Groff Создаем man-страницы ==
: ''Стоит вам закопаться в Linux поглубже, как вы принимаетесь чудить: например, писать документацию для проектов с открытым исходным кодом. В этом нет ничего зазорного; '''Пол Хадсон''' очень одобряет такое занятие.''

Документация – вещь важная. Фактически, вся моя работа
посвящена документации и постоянной ее нехватке.
LinuxFormat – тоже вид документации, разбавленный обзорами программного обеспечения и мнениями авторов. Даже бизнес-модель Тима О’Рейли, главы известного в компьютерных кругах
издательства O’Reilly, построена на том простом принципе, что документация, поставляемая с компьютерными продуктами, недостаточно
хороша.

Тим в чем-то прав, ведь программисты ненавидят писать документацию. Некоторые даже не вставляют комментарии в свои исходные тексты, потому как выкатить недоступный пониманию код на
малораспространенном языке программирования времен золотого
детства Дональда Кнута – разве не весело? Миру коммерческого
программного обеспечения это жить не мешает: фирмы просто нанимают людей специально для написания документации, оставляя программистам то, что у них получается лучше всего (нет, не чтение
ЛОРа и Slashdot’а, а программирование, конечно).

Если вы читаете данные строки, значит, вы принадлежите к одному из двух типов людей. Первый тип называется «Программировать
Не Умею, Но Хочу Чем-нибудь Помочь» (ПНУНХЧП), второй – «Умею
Программировать, Но Хочу Выпендриваться» (УПНХВ).

Тип ПНУНХЧП сейчас составляет большую часть сообщества
Open Source. Еще несколько лет назад соотношение программистов
и пользователей в Linux было гораздо больше в пользу первых. Кое-кто даже любил сравнивать его с отношением сигнал/шум (пользователи, разумеется, считались «шумом»). Программы разрабатывались быстро, ошибки отлавливались сразу, жалобами практически
не донимали. Теперь же на Linux работают и те, кто не умеет писать
коды. Эти люди могут помочь созданием графики, содействием
новичкам и, конечно же, разработкой документации. Если вы один
из них, то добро пожаловать! Можете примкнуть к проекту «Missing
Man Pages Project» (http://www.netmeister.org/misc/m2p2) [русско-язычным пользователям рекомендуется присоединиться к проекту
по переводу man-страниц на русский язык – http://alexm.here.ru/manpages-ru/].

=== Man-страницы всех времен и народов ===
С другой стороны, мы имеем лиц типа УПНХВ, которые желают плыть
против течения. Они действительно умеют программировать и даже
любят писать о своих программах. Это люди опасны. Например, если
вы подумываете: «А не завести ли мне собственный open source-проект? Напишу программу не хуже, чем XYZ, да еще приложу кучу документации, и любой новичок в ней сразу разберется» – тогда, пожалуйста, дальше не читайте, плодить бессмысленные варианты я не намерен. Да, ваш выбор хорош, но лучше бы вы употребили свой писательский зуд на помощь в разработке документации к готовым проектам.

Если же вы и вправду решили помочь сообществу с документацией, будьте как дома – это руководство для вас.

=== План ===
{{Врезка
|Заголовок=MAN: ПУСТЬ РАБОТАЮТ ВСЕ МУСКУЛЫ
|Содержание=[[Изображение:Img 76 105 1.jpg|thumb|Ваша man-страница куда лучше смотрится в Konqueror, если вы хотите впечатлить своих друзей.]]
С точки зрения пользователя, команда man имеет
массу вариантов работы. Например, если вы
наберете man mycommand, отобразится первая
найденная страница о mycommand. Если же вы
набрали man 6 mycommand, то увидите страницу
об игре mycommand.

Часто ли вы пользуетесь командами whatis и
apropos? Команда whatis возвращает секцию NAME
(ИМЯ) из man-страницы с кратким описанием
указанной команды. Например, whatis gcc вернет
gcc(1), то есть нечто вроде “GNU project C and C++
compiler”. Информацию whatis берет из своего
кэша, который обновляется командой makewhatis
(скорее всего, она у вас запускается каждый день
через планировщик cron).

А вот команда apropos ищет строку, указанную
пользователем, во всех man-страницах. Например,
команда apropos ‘text editor’ выведет имена всех
программ, в описании которых присутствует строка
‘text editor’. Эта команда чрезвычайно полезна в
ситуации, когда вы позабыли точное имя искомой
программы.

Так как команда man – всего лишь комбинация
groff и less, неудивительно, что существуют более
удобные средства просмотра man-страниц.
Например, попробуйте ввести в командную строку
konqueror что-нибудь вроде man:/home/youruser/путь_к_вашим_man_страницам/qaziqargs.6.1. Это
намного приятнее чтения man’ов в обычном
терминале, не так ли?
|Ширина=400px}}
Одни пытаются превратить свинец в золото. Другие ищут Святой
Грааль. Мы же озадачимся гибридом этих двух занятий: создадим
man-страницу для классической компьютерной игры – Qaziqargs Of
Qargg [исковерканное название «Волшебник страны Оз»]. Скорее
всего эта игрушка у вас не установлена, да и в Google вряд ли найдется информация о ней. Но это не проблема, про все ключи ее
командной строки я вам расскажу.

Мы не собираемся работать с TeX, HTML, XML или SGML – данное
руководство посвящено man-страницам, и не будем отклоняться от темы.

Для создания man-страницы вам понадобится: Linux (да, а что?!),
утилиты man и groff и немного терпения. Скорее всего, три компонента у вас уже есть:<br />
а) в руках вы держите LinuxFormat;<br />
б) без команды man не обходится ни один дистрибутив;<br />
в) а если работает man, значит, groff тоже установлен.

Не хватить может только терпения, поскольку groff использует
экзотический текстовый формат, намного более древний, чем HTML
(бытует мнение, что Unix был придуман потому, что типографиям
требовалась система для работы с groff, – прим.ред.). На вид он старомоден, имеет странный синтаксис, злоупотребляет препроцессором… короче, он совершенно ужасен, но, надеюсь, вместе мы
сквозь него продеремся.

=== Гроффмейстер ===
groff – это последняя модификация программы, ранее называвшейся
ronoff (в которой были доступны лишь базовые средства форматирования). Затем был nroff (новый roff), потом troff, и наконец ditroff (устройство-независимый troff). С 1991-го года GNU-реализация ditroff
стала стабильной и получила название groff.

Такова семейная сага groff. Ее можно и не знать; главное – помнить,
что man-страницы пишутся в формате groff, который преобразовывается на лету для отображения на терминале. Полученные читабельные
страницы автоматически кэшируются в расчете на дальнейшее использование. Но мы-то будем иметь дело с внутренним форматом.

Man-страницы в Linux хранятся в виде groff-файлов, ради экономии места сжатых архиватором gzip. Например, в SUSE их директория /usr/share/man. Естественно, все они рассортированы по языкам и разделам. Нумерация разделов может показаться немного
нелогичной:
# Команды, доступные пользователю
# Системные вызовы ядра
# Библиотечные функции
# Файлы устройств и сетевые интерфейсы в /dev
# Форматы файлов и их описания
# Игры
# Макросы, окружения и другие куски информации
# Команды системного администрирования для использования пользователем root
# Описание X-Window
Есть еще несколько разделов, но они уже устарели и вряд ли вам
понадобятся. Полезно было бы запомнить эти номера, чтобы понимать различия между man 1 passwd и man 5 passwd. Первая загружает справку о команде passwd, а вторая – информацию о формате
файла /etc/passwd.

Все man-страницы в директории /usr/share/man отсортированы
по категориям: например, справка о команде passwd находится в
файле /usr/share/man/man1/passwd.1.gz, а информация о /etc/passwd – в /usr/share/man/man5/passwd.5.gz. Теперь давайте
посмотрим, на что похожа man-страница изнутри: zcat /usr/share/man/man5/passwd.5.gz. Да перестаньте брызгать слюной, скоро
вы все поймете.

=== Простейшая man-страница ===
[[Изображение:Img 76 106 1.png|thumb|groff: до ...]]
[[Изображение:Img 76 106 2.png|thumb|...и после. Как говорится, почувствуйте разницу!]]
Мы здесь не на почасовой оплате – не будем тянуть время, запустим
Emacs. Скорейший способ изучить groff – использовать ту же тактику,
что и при изучении HTML: хотя макросов устрашающе много, большинство из них, вероятнее всего, вам не понадобится.

Вот наша первая попытка создать man-страницу; сохраните ее
файл под именем qaziqargs.6.1 (в данном случае .1 – это номер
версии вашей страницы):
<source lang="text">.TH QAZIQARGS 1 «February 2006» «qaziqargs-1.0.556» «Qaziqargs of Qargg!»
.SH ИМЯ
qaziqargs – запустить игру Qaziqargs of Qargg
.SH КРАТ КОЕ СОДЕР ЖАНИЕ
.B qaziqargs
[
.B –cheat
.I mode
]
.I savegame
.SH ОПИСАНИЕ
Qaziqarggs of Qargg – ролевая игра
для больших кровожадных детишек.
.SH ОПЦИИ
.TP
.B --cheat
Здесь включается режим Бога:
.I режим
может быть равен 1 для неисчерпаемых боеприпасов,
2 для бессмертия или 3 для полного беспредела.
.TP
.I сохраненная_игра
Загрузка сохраненной игры из директории
.I $HOME/.qaziqargs
.SH АВТ ОР
Лестное для вас фото / имя (Вася Пингвинов, например)</source>
Здесь около 25 строк кода, man-страница и не должна быть больше, чтобы помещаться на экране. Есть несколько способов написания
groff-файлов, и мы выбрали простейший: каждый макрос («тэг») действует на текст, который следует за ним, закрывать макросы не требуется. В данном куске кода мы использовали всего пять разных макросов:
.TH, .SH, .B, .I и .TP. Макросов, конечно, намного больше, однако для
создания man-страниц этих хватит.

Макрос .TH задает заголовок страницы. Как и во многих других
макросах, вы можете задавать параметры, разделяя их пробелами. У
.TH параметры специфические: название исполняемого файла программы; раздел man; текст, отображаемый в середине нижнего
колонтитула; текст, отображаемый слева от нижнего колонтитула и
текст, отображаемый в центре заголовка. Здесь они заданы так: текст
в середине нижнего колонтитула – это дата последнего обновления
документации, слева – номер версии, а текст в середине заголовка –
название программы (это не имя исполняемого файла). Если в параметре содержится пробел, такой параметр нужно заключить в двойные кавычки.

Стандартный макрос .SH отвечает за заголовок секции. Во-первых, заголовок должен быть написан заглавными буквами – ИМЯ,
СИНТА КСИС, ОПИСАНИЕ, и т.д. Во-вторых, вы обязаны включать в
свои man-страницы секцию NAME (ИМЯ) программы и ее краткое
(желательно однострочное) описание. Эта секция используется утилитами whatis и apropos (их тоже надо знать).

В man-страницы также входят секции:
* AVAILABILITY (ДОСТУПНОСТЬ ) – ваша программа совместима только с Linux и FreeBSD или работает на всех Unix-системах?
* EXAMPLES (ПРИМЕРЫ) – примеры использования вашей программы
* HISTORY (ИСТОРИЯ) – включайте, если только она интересна или важна
* FILES (ФАЙЛЫ) – какие файлы (и директории) использует ваша программа
* BUGS (ОШИБКИ ) – опишите известные вам грешки, чтобы люди зря не рвали на себе волосы
* CAVEATS (ОСОБЕННОСТИ) – многие могут принять их за ошибки, но на самом деле все так и задумано
* SEE ALSO ( СМ. ТА КЖЕ ) – список man-страниц, которые могут помочь при чтении вашей документации
Макросы .B и .I преобразуют шрифт текста, следующий за ними,
в полужирный и курсив соответственно, однако на большинстве терминалов курсив отображается как подчеркивание. .B используется в
man-страницах для именованных параметров (например, -x или --help), а .I – для задаваемых пользователем (допустим, имен файлов). В приведенном коде присутствуют оба варианта.

Макрос .TP означает «термин/параграф» и используется для
описания опций: в первой строке находится имя опции (.B --cheat),
а далее идет ее объяснение.

Тут срабатывает автоматика: если термин (название) короче, чем
отступ по умолчанию, то объяснение начнется на той же строке, где и
термин. Ширина левого отступа по умолчанию равна семи символам
(обратите внимание, что этот отступ действует для всего текста, не
входящего в заголовок). Вы можете задать отступ .TP с помощью
числового параметра. Например, .TP 0 сотрет грань между параграфом и всем остальным текстом. Одинаковый для всех отступ задается один раз (в первом из .TP), он автоматически распространится на
последующие строки.

Теперь посмотрим, что у нас получилось. Выполните команду
man -l qaziqargs.6.1 (посередке – это строчное L). Ну что, ощущаете законную гордость? Или, наоборот, раздосадованы, что гора
родила мышь? Ответ пришлите открыткой.

=== Делайте больше! ===
{{Врезка
|Заголовок=ГРАФИЧЕСКОЕ РЕШЕНИЕ
|Содержание=[[Изображение:Img 76 197 1.jpg|thumb|Редактировать man-страницы в ManEdit проще, чем вручную, но… ну очень ненамного!]]
Допустим, вы прочитали наше руководство, но хотите поискать
еще более легких путей. Тогда попробуйте ManEdit. Это свободное
средство разработки man-страниц, некоторым образом
автоматизирующее создание документации (честно говоря, оно
недалеко ушло от «сделай сам», да еще требует библиотеку GTK 1.2
– мы все были уверены, что она давным-давно скончалась). Если
вам категорически несимпатична кухня Emacs, посетите http://wolfpack.twu.net/ManEdit.

Удивите друзей – выведите свою man-страницу через Konqueror.
Он добавляет симпатичный пользовательский интерфейс!
|Ширина=400px}}
Вы наверняка подумали «Хм, при написании man-страниц придется
соблюдать больше правил, чем при вождении машины». Честно говоря, вы правы, и мой ответ – «не нравится, не ешь». Если вы не уважаете правил, значит, создание man-страниц не для вас. Правила
обеспечивают унификацию документации и отлично работают вот уже
два десятилетия.

Прежде чем умчаться готовить свои man-страницы, разберитесь
еще с двумя специфическими макросами. Специфика их в том, что
они не занимаются форматированием. Первый – .\», означающий
начало комментария. Комментарии в groff имеют такой же смысл, как
в С или LaTeX: groff их игнорирует.

Включение комментариев в groff-исходник – весьма тонкий ход,
он позволяет отклонить пользовательские громы и молнии в пустоту:
чистосердечно сознайтесь в своих ошибках, и вас никто не обидит.
Например:
.\» Не уверен, что эта штука --baz вообще заработает.
Второй макрос – .so (строчными буквами). Это способ перебросить groff на другой файл, аналогично HTTP-перенаправлению.
Например, команда qaziqargs имеет параметр --create-server, а у
вас есть скрипт qaziqargs-create-server, который как раз вызывает
qaziqargs с нужным параметром --create-server. (Такой подход
использован, например, в игре Crack Attack.)

Вам, естественно, неохота держать две man-страницы для этих
команд – лучше обойтись ссылкой. Создайте основную страницу
qaziqargs.6, а в странице qaziqargs-create-server.6 пропишите
всего одну строку:
.so man6/qaziqargs.6
Обратите внимание, что файл находится в каталоге с man-страницами, а не у вас под руками в home: переадресация действует только
внутри системной директории. По умолчанию это /usr/share/man.

Сам я предпочитаю хранить man-страницы внутри домашнего
каталога, пока вожусь с отладкой, а для их загрузки набираю команду man –l. Как только качество страницы меня удовлетворяет, я сжимаю ее при помощи gzip (и вам советую), а потом уж устанавливаю в
/usr/share/man.

А теперь радуйтесь: настал конец мучениям! Хотя рассмотренный
код невелик, он иллюстрирует все необходимые макросы, с которыми man-страницы писать легко.

Конечно, создание документации предполагает не только написание man-страниц – есть множество других форматов, например, info,
со своими собственными правилами. Однако man-страницы являются в
Linux стандартом де-факто, а в некоторых дистрибутивах, скажем, Arch Linux и Crux, вся прочая документация из пакетов специально удаляется. Итак, за дело – документации никогда не бывает много.

{{Врезка|center|
|Заголовок=КАК СДЕЛАТЬ ХОРОШИЙ ДОКУМЕНТ
|Содержание=
; Сначала подготовьте черновик.: Используйте простые заметки вроде «здесь вставить пример использования опции --grak». Это поможет структурированию.
; Выберите предмет, в котором хорошо разбираетесь.: Никто не станет читать «Руководство по XYZ для чайников, написанное другим чайником» в надежде на революционные откровения – документацию должны создавать эксперты.
; Пишите кратко…: В книгах и журналах авторы могут растекаться мыслью по древу, но в технической документации это непозволительно. Не стоит разбавлять документацию водой.
; ...но исчерпывающе.: Что произойдет, если вместо строки передать программе число? А что, если число будет отрицательным? Какие коды ошибок возвращает ваша программа?
; Отвечайте на конкретные вопросы.: Есть ли способы устранения выявленных ошибок? Содержатся ли в примерах неочевидные вещи?
; Будьте проще.: Это техническая документация, старайтесь выразить мысли простыми словами. Не исключено, что документ возьмутся переводить на другой язык – пожалейте переводчиков и не мучайте их малоизвестными идиомами.
; Взгляните со стороны.: Помните, что точка зрения пользователей не всегда совпадает с вашей, создателя программы. Вы в восторге от того, как здорово ваша программа гракает глуббов, а пользователям на это глубоко наплевать.
; Никакого плагиата.: Плагиат – последнее дело, тем более в сообществе свободного программного обеспечения, и может вызвать проблемы с лицензиями.
; Оцените варианты.: Например, конвертируйте страницу в html с помощью man2html и оцените, как она выглядит в другом формате.
; Очепатки в курописи!: Обязательно проверьте орфографию текста. Для этого в Emacs по умолчанию есть ispell, а можно взять aspell. Неплохо также дать документ кому-нибудь на прочтение (а то и нескольким людям) и послушать их комментарии.
; Оставьте контактную информацию,: чтобы люди могли связаться с вами, если обнаружат у вас в тексте ошибки – например, ссылку на свою web-страницу или адрес электронной почты.
|Ширина=}}

[[Категория:Hardcore Linux]]
[[Категория:Пол Хадсон]]

LXF76:Hardcore Linux2 - История изменений

Yaleks: викификация

Yaleks: Новая: == Groff Создаем man-страницы == : ''Стоит вам закопаться в Linux поглубже, как вы принимаетесь чудить: например,...