LINUX MAN-PAGE-HOWTO
Copyright 1995-2000 by Jens Schweikhardt, email: <[email protected]>
Перевод: Александр
Ермолаев, SWSoft Pte Ltd.
http://www.schweikhardt.net/
Информацию относительно условий копирования ищите
ниже.
Последнее обновление: Июль 2000. Щелкните здесь, чтобы просмотреть последнюю
версию этого документа. Исправления и комментарии приветствуются!
Этот HOWTO разъясняет вам, что вы должны иметь в виду, если вы собираетесь составить
страницы руководства (man pages), которые вы хотите сделать доступными по команде
man. В этом HOWTO, слово "руководство" понимается в качестве
страниц руководства.
Содержание
0) Некоторые мысли по поводу
документации
Почему мы пишем документации? Глупый вопрос.
Мы хотим, чтобы другим
было понятно, как использовать нашу программу, библиотечную функцию или что-то
еще, написанное или сделанное. Но написание документации - это еще не все. Необходимо,
чтобы:
- документация была доступна. Если она скрыта в
каком-то нестандартном
месте, то специальные программы не смогут найти ее - каким образом тогда ее
использовать?
- документация была точная и аккуратная. Нет ничего более раздражающего,
чем несогласованность документации и программы. Если это будет
иметь место, то пользователи
проклянут вас, будут слать гневные письма и выбросят вашу программу и
документацию, с твердым намерением никогда не устанавливать что-либо,
написанное вами.
Исторически заведено и всем известно, что документация доступна по команде man(1).
Этот HOWTO разъясняет, как вам написать руководство, которое будет
корректно обрабатываться
утилитами для просмотра документации. Наиболее известные из этих утилит - man(1),
xman(1x), apropos(1), makewhatis(8) и catman(8). Точность и аккуратность информации
зависит, конечно, только от вас. Но даже в этом отношении вы найдете некоторые
идеи, которые помогут избежать некоторых общих ошибок.
1) Как дать имя
руководству, и где его установить?
Вам необходимо знать точный механизм, как дать правильное имя
руководству
и где его правильно установить. Любое руководство должно
находиться
в определенном разделе, который обозначается определенным символом. Общие разделы
под Linux и их описания:
Раздел Описание
1 Пользовательские команды, с которых можно начать каждому.
2 Системные вызовы, т.е. функции обеспечиваемы е ядром.
3 Процедуры, т.е. библиотечные функции.
4 Устройства, т.е. специальные файлы в каталоге /dev.
5 Описания форматов файлов, напр. /etc/passwd.
6 Игры.
7 Разное, напр., макро пакеты, соглашения.
8 Утилиты для системного администрирования, которые могут быть запущены только под root.
9 Другое (специфичное для Linux) место для размещения документации по ядру.
n Новая документация, которая может быть перемещена в соответствующий раздел.
o Старая документация, которая может здесь хранится определенное время.
l Локальная документация, касающаяся именно этой системы.
Имя исходного файла руководства состоит из
имени команды, функции или файла,
дальше сиавится точка и имя раздела. Если вы пишете документацию по формату файла
'passwd', вы должны дать имя исходному файлу - 'passwd.5'. Здесь
пример
имени файла, совпадает с названием команды. Представим, что может существовать
библитечная функция 'passwd'. Секционирование - обычный способ разрешить
противоречия: Описание команды будет найдено в файле 'passwd.1', а описание
выдуманной библиотеки - в файле 'passwd.3'.
Иногда в конце имени файла добавляются дополнительные символы,
и имя файла выглядит, например, так: 'xterm.1x' или так 'wish.1tk'.
Это намеренно сделано для того, чтобы показать, что эта документация для программ
X Window program или для приложений Tk, соответственно. Некоторые программы
для просмотра страниц руководства могут использовать эту дополнительную информацию.
Например, xman будет использовать 'xterm(x)' и 'wish(tk)' в списке доступной
документации.
Пожалуйста, не используйте разделы n, o и l; согласно стандарту файловой системы
эти разделы не одобряются. Используйте номера разделов. Остерегайтесь совпадения
имен с существующими программами, функциями или именами файлов. Это конечно
плохая идея - написать редактор и назвать его ed, sed ("умный" ed)
или red (Rocky ed). Удостоверьтесь, что имя вашей программы уникально, тем самым
вы избежите того, что кто-то ненарочно
выполнит вашу программу или прочитает не
то руководство. Проверьте базу данных lsm программ перед тем, как
назвать свое творение.
Теперь мы знаем имя нашего файла. Следующее - мы должны решить, в какой
каталог установить программу (скажем, когда пользователь запустит команду
'make install' для вашего пакета) на Linux, все руководства устанавливаются
в каталоги, упомянутые в переменной MANPATH. Утилиты для работы с документациями
используют ее, как shell использует PATH для выполнения программ. Фактическиt,
MANPATH имеет тот же формат, что и PATH. Обе переменные содержат список каталогов,
разделенных двоеточием, ":" (с тем исключением, что MANPATH не содержит
пустых полей и относительных путей, и имеет только абсолютные пути). Если MANPATH
не установлена или не экспортируется, по умолчанию будет использоваться содержимое
каталога /usr/man. Для ускорения поиска в
каталогах, определенных в MANPATH (называемые
основными каталогами) содержат связку подкаталогов,
названных 'man<s>',
где <s> - замещает символ (указан выше в таблице). Не все разделы могут
быть представлены каталогом, потому что нет никаких причин хранить пустой каталог
'mano'. Однако могут быть каталоги, названые 'cat<s>', 'dvi<s>' и
'ps<s>', которые содержат документацию, готовую для печати или вывода
на экран. Об этом позже. Единственный файл, который должен быть в каталоге -
файл называемый 'whatis'. Цели и создание этого файла будет описано в параграфе
11). Самый безопасный способ иметь страницы руководства для раздела <s>
- установка их в правильном месте - в каталоге /usr/man/man<s>. Хороший
Makefile, однако, позволит пользователю выбрать основной каталог, в зависимости
от значения переменной MANDIR. Большинство пакетов могут быть настроены с опцией
--prefix=/what/ever. Страницы руководства будут устанавливаться в основной
каталог /what/ever/man. Постарайтесь обеспечить
возможность подобного выбора.
С появлением Linux
File System Standard (FS-Stnd), вещи стали более сложными. FS-Stnd 1.2 говорит,
что:
"Для поддержки страниц руководства,
написанных на разных языках, соответствующие условия должны быть созданы в самой структуре
/usr/man."
Это достигнуто благодаря тому, что были введены уровни каталогов, для различных языков. Цитата
из FS-Stnd 1.2:
"Названия каталогов для различных языков в /usr/man основаны на Приложении
E (POSIX 1003.1), по стандарту которого описывается строка идентификации для
языков. Строка <locale>: <language>[_<territory>][.<character-set>][,<version>]"
(Смотрите FS-Stnd для некоторых общих строк <locale>.) Согласно этим
принципам, наши страницы руководства
имеются в каталогах /usr/man/<locale>/man[1-9lno].
Форматированные версии должны быть в /usr/man/<locale>/cat[1-9lno], иначе
вы сможете обеспечить их только для единственного языка. ОДНАКО, я не рекомендую
прямо сейчас следовать этой структуре. FS-Stnd 1.2 также позволяет это
"Система, которая использует уникальный язык или кодовую страницу для
всех руководств может пропускать подстроку <locale> и хранить все руководства
в каталоге <mandir>. Например, система, в которой используется только
английские страницы руководства в ASCII коде, могут хранить страницы руководства
(каталоги man[1-9]) прямо в /usr/man. (Фактически это традиционное местоположение.)"
Я не думаю, что все утилиты (типа xman, tkman, info и многие другие, которые
читают руководство) могут справляться с новой структурой.
2) Как должно выглядеть отформатированное
руководство?
Позвольте мне привести вам пример. Ниже я объясню его подробнее. Если
вы читаете
этот документ, как простой текст вам не будут показаны различные шрифты (жирный
и наклонный). Пожалуйста, обратитесь к параграфу "Какие
существуют соглашения по шрифтам?" для дальнейших объяснений. Здесь
приведено руководство по гипотетической программе foo.
FOO(1) User Manuals FOO(1)
NAME
foo - frobnicate the bar library
SYNOPSIS
foo [-bar] [-c config-file ] file ...
DESCRIPTION
foo frobnicates the bar library by tweaking internal symbol
tables. By default it parses all baz segments and rearranges
them in reverse order by time for the xyzzy(1) linker to
find them. The symdef entry is then compressed using the WBG
(Whiz-Bang-Gizmo) algorithm. All files are processed in the
order specified.
OPTIONS
-b Do not write 'busy' to stdout while processing.
-c config-file
Use the alternate system wide config-file instead of
/etc/foo.conf. This overrides any FOOCONF environment
variable.
-a In addition to the baz segments, also parse the blurfl
headers.
-r Recursive mode. Operates as fast as lightning at the
expense of a megabyte of virtual memory.
FILES
/etc/foo.conf
The system wide configuration file. See foo(5) for fur-
ther details.
~/.foorc
Per user configuration file. See foo(5) for further
details.
ENVIRONMENT
FOOCONF
If non-null the full pathname for an alternate system
wide foo.conf. Overridden by the -c option.
DIAGNOSTICS
The following diagnostics may be issued on stderr:
Bad magic number.
The input file does not look like an archive file.
Old style baz segments.
foo can only handle new style baz segments. COBOL
object libraries are not supported in this version.
BUGS
The command name should have been chosen more carefully to
reflect its purpose.
AUTHOR
Jens Schweikhardt <[email protected]>
SEE ALSO
bar(1), foo(5), xyzzy(1)
Linux Last change: MARCH 1995 2
Здесь пойдут объяснения, как я и обещал.
Раздел NAME (НАЗВАНИЕ)
...является единственным обязательным полем. Руководства без раздела name также
бесполезны, как холодильник на северном полюсе. Этот раздел
имеет стандартизированный
формат, представляющий собой список программ или функции,
разделенных запятыми
и через тире идет короткое описание возможностей программы или функций. Посредством
makewhatis(8) содержимое раздела name попадет в файл базы данных whatis. Makewhatis
является причиной, почему должен существовать раздел name и почему мы должны
придерживаться описанного формата. В исходном тексте мы увидим следующее
.SH NAME foo \- frobnicate the bar library
\- имеет здесь значение. Обратная косая черта нужна, чтобы показать, что она
отлична от дефиса, который может появляться в названии команды или в строке
описания.
Раздел SYNOPSIS (СИНТАКСИС)
...предназначен, чтобы дать краткий обзор доступных опций программы. Для функций
он делит на части два списка: подключаемые файлы и прототипы функций, т.о. программист
знает число и типы параметров, а также тип возвращаемого значения.
Раздел DESCRIPTION (ОПИСАНИЕ)
...дает доступное объяснение возможностей программы или функций. Здесь вы выкладываете
все ваши знания. Приложите все ваши умения, для того, чтобы добиться восхищения
других, сделав этот раздел надежным и детальным источником информации. Объясните:
какие используются аргументы, формат файла, алгоритмы и т.п.
Раздел OPTIONS (ОПЦИИ)
...содержит описание для всех опций, которые влияют на работу программы. Вы
знали их, не так ли?
Раздел FILES (ФАЙЛЫ)
...список используемых программ и функций. Например, файлы настройки, автозагружаемые
файлы, файлы с которыми непосредственно работает программа. Лучше использовать
полные пути к этим файлам и заставить make изменить пути, если пользователь
предпочтет другое местоположение для программы: для groff по умолчанию заданный
префикс - /usr/local, т.о., они ссылаются на /usr/local/lib/groff/*. Однако,
если вы установите 'make prefix=/opt/gnu', тогда ссылка в руководстве изменится
на /opt/gnu/lib/groff/*
Раздел ENVIRONMENT (СРЕДА)
...список всех переменных окружения, которые влияют на вашу программу или функцию.
Обычно переменные содержат пути, имена файлов или опции по умолчанию.
Раздел DIAGNOSTICS (ДИАГНОСТИКА)
...должен дать описание большинству выдаваемых вашей программой сообщений об
ошибках и способы их исправления. Нет никакой необходимости объяснять сообщения о
системных ошибках (от perror(3)) или фатальные ошибки (от psignal(3)), поскольку
они могут появляться при работе любых программ.
Раздел BUGS (ОШИБКИ)
...в идеале его не должно быть. Если у вас хватит смелости, вы можете описать
здесь ограничения, известные неудобства в работе с программой, особенности,
которые другие могут расценивать их как ошибки. Если вы не так смелы, тогда переименуйте
ее в раздел TO DO ;-)
Раздел AUTHOR (АВТОР)
...хорош в том случае, когда вы хотите получать сообщения об ошибках в документации
или в программе.
Раздел SEE ALSO (СМ. ТАКЖЕ)
...список (в алфавитном порядке) руководств, которые могут быть связаны с вашим
руководством. Традиционно - это последний раздел.
Вы можете вставить свои разделы, если они действительно не соответствуют одному
из описанных разделов. Так как же точно выглядит руководство? Я ожидал этот
вопрос, здесь вы можете посмотреть источник:
.\" Process this file with
.\" groff -man -Tascii foo.1
.\"
.TH FOO 1 "MARCH 1995" Linux "User Manuals"
.SH NAME
foo \- frobnicate the bar library
.SH SYNOPSIS
.B foo [-bar] [-c
.I config-file
.B ]
.I file
.B ...
.SH DESCRIPTION
.B foo
frobnicates the bar library by tweaking internal
symbol tables. By default it parses all baz segments
and rearranges them in reverse order by time for the
.BR xyzzy (1)
linker to find them. The symdef entry is then compressed
using the WBG (Whiz-Bang-Gizmo) algorithm.
All files are processed in the order specified.
.SH OPTIONS
.IP -b
Do not write 'busy' to stdout while processing.
.IP "-c config-file"
Use the alternate system wide
.I config-file
instead of
.IR /etc/foo.conf .
This overrides any
.B FOOCONF
environment variable.
.IP -a
In addition to the baz segments, also parse the
blurfl headers.
.IP -r
Recursive mode. Operates as fast as lightning
at the expense of a megabyte of virtual memory.
.SH FILES
.I /etc/foo.conf
.RS
The system wide configuration file. See
.BR foo (5)
for further details.
.RE
.I ~/.foorc
.RS
Per user configuration file. See
.BR foo (5)
for further details.
.SH ENVIRONMENT
.IP FOOCONF
If non-null the full pathname for an alternate system wide
.IR foo.conf .
Overridden by the
.B -c
option.
.SH DIAGNOSTICS
The following diagnostics may be issued on stderr:
Bad magic number.
.RS
The input file does not look like an archive file.
.RE
Old style baz segments.
.RS
.B foo
can only handle new style baz segments. COBOL
object libraries are not supported in this version.
.SH BUGS
The command name should have been chosen more carefully
to reflect its purpose.
.SH AUTHOR
Jens Schweikhardt <[email protected]>
.SH "SEE ALSO"
.BR bar (1),
.BR foo (5),
.BR xyzzy (1)
3) Как задокументировать несколько программ/функций
на одной странице руководства?
Многие программы (grep, egrep) и функции (printf, fprintf, ...) описываются
в одном руководстве. Однако, эти страницы были бы почти бесполезны, если они
были доступны только под одним названием. Мы не вправе ожидать, что пользователь
помнит, что руководство по egrep - это фактически руководство по grep. Поэтому
необходимо иметь руководство доступное под различными именами. Есть несколько
способов достичь этого:
- иметь одинаковые копии для каждого имени.
- связать все руководства жесткими ссылками.
- использовать символьные ссылки на фактическое руководство.
- использовать механизм groff обеспеченный макросом '.so'.
Первый способ - трата дискового пространства. Второй способ не рекомендуется,
потому что интеллектуальные версии программы catman могут сохранять работу в
зависимости от типа и содержания файла. Жесткие ссылки препятствуют программе
catman. (цель catman состоит в том, чтобы отформатировать все руководства так,
чтобы они как можно быстрее отображались на экране.) Третья альтернатива имеет
небольшой недостаток: вы должны знать, что существуют файловые системы, которые
не поддерживаю символьные ссылки. В результате этого - Лучшая Вещь (TM) - использовать
механизм groff. Здесь скажу о том, как это сделать: Если вы хотите
видеть
страницы руководства доступными под именами 'foo' и 'bar' в разделе 1, тогда поместите
руководство в файл foo.1 и сделайте файл bar.1 такого типа:
.so man1/foo.1
Важно определить директивную часть 'man1/' также, как имя файла 'foo.1',
потому что
когда groff будет запущен браузером, он будет иметь базовым каталогом текущий
рабочий каталог (трк), а groff интерпретирует аргументы относительно трк.
4) Какой макропакет использовать?
Существует множество макропакетов, специально предназначенных для использования
при написании руководств. Обычно они находятся в каталоге макросов groff /usr/lib/groff/tmac.
Имена файлов tmac.<кое-что>, где <кое-что> - аргумент опции
-m для groff. Groff будет использовать tmac.<кое-что>, когда
он работает с опцией '-m <кое-что>'. Часто пробел между '-m'
и '<something>' опускается, и тогда может получиться 'groff -man',
когда мы форматируем руководства, используя макрос tmac.an. По этой
причине дано странное название 'tmac.an'. Кроме того, имеется другой популярный
макрос - tmac.doc, который сделан в калифорнийском университете Беркли
(UCB). Большинство руководств BSD используют его, и он, кажется, сделан (в UCB)
стандартным для документаций. Макрос tmac.doc более гибок, но, увы,
браузеры для руководств не используют его и всегда вызывают groff -man.
Например, все программы xman, я видел, требуют tmac.doc. Т.о.,
для вашей пользы: используйте tmac.an -- использование любого другого
макропакета нежелательно. tmac.andoc - псевдомакрос, который
просматривает источник и затем загружает либо tmac.an, либо tmac.doc.
Фактически, любой браузер руководств должен его использовать, но до сих пор не
все это делают, т.е., лучше использовать старый tmac.an. Если, так или
иначе, вы хотите использовать макрос tmac.doc, здесь имеется более
детальное описание, объясняющее, как им пользоваться: http://www.bsdi.com/bsdi-man.
На странице имеется форма для поиска. Введите mdoc.samples, и вам будет
найден mdoc.samples(7) - обучающий пример по написанию страниц руководства
для BSD.
Описание для troff (
Troff User's Manual), со всеми объясненными макросами,
доступно в html, PostScript
(ps, 760K) или в Portable
Document Format (pdf, 240K). AT&T Bell Labs сделали его общедоступным. Не
забудьте проверить домашнюю страницу W.
Richard Steven (известный по книге
Unix Network Programming, а также
по трилогии
TCP/IP Illustrated), который также имеет список ресурсов по
Troff Resources, включающий
tbl, eqn, pic и др.
5) Какие препроцессоры я могу использовать?
Groff идет, с минимум, тремя препроцессорами - tbl, eqn, и pic (на некоторых
системах они называются - gtbl, geqn и gpic). Их цель - транслировать макрокоманды
препроцессора и данные для troff. Tbl - табличный препроцессор, eqn - препроцессор
для выражений и pic - препроцессор изображений. Пожалуйста, обратитесь к руководству,
за более детальной информацией и описанием возможностей, которые они обеспечивают.
Чтобы обезопасить себя: не пишите руководства, требующие ЛЮБЫЕ препроцессоры.
Eqn будет вообще делать ужасный вывод для текстовых устройств, к сожалению,
в 99% случаев руководства просматриваются на таких устройствах. Например, XAllocColor.3x
использует несколько формул с экспонентами. Из-за характера таких устройств,
экспонента будет на той же самой строке, что и основание. N в квадрате - 'N2'.
Tbl необходимо избегать, потомучто все программы xman, которые я видел, сбоили
с ним. Xman 3.1.6 использует следующие команды для форматирования руководств,
напр. signal(7):
gtbl /usr/man/man7/signal.7 | geqn | gtbl | groff -Tascii -man /tmp/xmana01760
2> /dev/null
которые разворачивают источник, используя gtbl, gtbl выводит снова в gtbl.
В результате получается руководство без вашей таблицы. Я не знаю - это ошибка
или особенность, что gtbl подавляет свой собственный вывод или если бы xman был
бы "умнее", он не использовал бы gtbl дважды... Так или иначе, если
вы хотите иметь таблицу, форматируйте ее непосредственно в тексте и поместите
между строками .nf и .fi, чтобы к ней не применялось форматирование. У вас не
будет жирного шрифта или курсива при использовании этого способа, но он позволит
вам получить таблицу. Я должен все-таки увидеть руководство, использующее препроцессор
pic. Но я не хотел бы этого.
6) Как я должен распространять готовое руководство?
Позвольте мне собрать доводы за (+) и против (-) из нескольких отобранных возможностей:
- Только источник:
+ небольшой дистрибутивный пакет.
- недоступно на системах без groff.
- Несжатое и форматированное:
+ доступно даже на системах без groff.
- пользователь не может сгенерировать файлы dvi или postscript.
- трата дискового пространства.
- Сжатое и форматированное:
+ доступно даже на системах без groff.
- пользователь не может сгенерировать файлы dvi или postscript.
- который формат сжатия вы бы использовали? .Z? .z? .gz? Все из них?
- Источник и несжатый и форматированный:
+ доступно даже на системах без groff.
- большой дистрибутивный пакет.
- некоторые системы ожидают сжатые отформатированные руководства.
- избыточная информация для систем с groff.
IMHO лучше всего распространять только источник. Аргумент, что он не будет
доступен на системах без groff, не имеет значения. Более 500 руководств Linux
Documentation Project в виде исходных текстов. Руководства для XFree86 содержатся
в виде исходных текстов. Руководства от FSF идут только в виде источника. Фактически,
я редко видел дистрибутивы, распространяемые с отформатированными страницами
руководства. Если какой-то сисадмин заинтерисован в руководстве, то он сам установит
groff.
7) Какие существуют соглашения по шрифтам?
Прежде всего: не используйте напрямую операторы типа \fB \fP и т.п. Используйте
макросы, которые принимают аргументы. Таким способом вы избежите обычного сбоя:
забыть сменить типа шрифта в конце слова и при наличии других шрифтов продлевает
их использование до следующей смены шрифта. Поверьте мне, это случается чаще,
чем многие думают. Макрос tmac.an обеспечивает следующие типы шрифтов:
.B Жирный
.BI Жирный чередуется с наклонным
.BR Жирный чередуется с Roman
.I Наклонный
.IB Наклонный чередуется сжирным
.IR Наклонный чередуется с Roman
.RB Roman чередуется с жирным
.RI Roman чередуется с наклонным
.SM Малый (9/10 от нормального размера)
.SB Малый чередуется с жирным
X чередуется с Y, в этом случае, нечетные параметра набраны шрифтом X, а четный
- шрифтом Y. Например:
.BI "Arg 1 - жирный, " "Arg 2 - наклонный, " "и жирный,
" "и наклонный."
Двойные кавычки необходимы, чтобы включить пробелы в аргументы; без них не
будет пробелов между чередующимися шрифтами. Фактически, вам будут нужны только
макросы для чередующихся шрифтов для того, чтобы при смене шрифта не было незаполненого
пространства. Ниже описано то, как использовать различные шрифты: (часть взято
из man(7))
Хотя имеется множество разных соглашений для руководств в мире UNIX, существуют
сотни руководств для Linux определяющие наши стандарты: для функций, аргументы
всегда записаны наклонным шрифтом, даже в разделе SYNOPSIS, где остальная часть
функции выводится жирным шрифтом:
.BI "myfunction(int " argc ", char **" argv );
Имена файлов всегда выводятся наклонным шрифтом, исключая раздел SYNOPSIS,
где для них используется жирный шрифт. Т.е., вы должны использовать:
и
Специальные макросы, которые обычно записываются в верхнем регистре, выводятся
жирным шрифтом:
В списке кодов ошибок: коды выводятся жирным шрифтом. Этот список обычно использует
.TP (параграф):
Любые ссылки на другие руководства (или на другие темы в данном руководстве)
выводятся жирным шрифтом. Если дается номер раздела, то он выводится шрифтом
roman:
Акронимы смотрятся лучше всего, когда набраны мелким шрифтом. Т.е., я рекомендую:
.SM UNIX
.SM ASCII
.SM TAB
.SM NFS
.SM LALR(1)
8) Как мне сделать руководство безупречным?
Ниже даны некоторые правила, которые обеспечивают надежность, удобочитаемость
и "форматируемость" вашей документации.
- Сделайте проверку орфографии.
- Протестируйте ваше руководство: Выдает ли groff ошибки, когда форматирует
ваше руководство? Желательно иметь команду groff в коментариях. Выдает ли команда
man(1) ошибки, когда вы вызываете 'man ваша_программа'? Правильно ли выглядит
отформатированная страница? Работают ли xman(1x) и tkman(1tk) с вашим руководством?
XFree86 3.1 имеет xman 3.1.6 - X11R6, он будет пробовать использовать несжатое
руководство
gzip -c -d < %s > %s
zcat < %s > %s
- Способен ли makewhatis(8) извлекать описание из раздела NAME?
9) Как получить простое текстовое руководство,
без лишних элементов?
Взгляните на col(1), col способен отфильтровывать экранирующие
последовательности. Проверьте:
funnyprompt$ groff -t -e -mandoc -Tascii manpage.1 | col -bx > manpage.txt
Ключи -t и -e сообщают groff об использовании препроцессоров tbl и eqn. В этом
случае будет немного задерживаться вывод для страниц, которым не требуется такая
обработка. С другой стороны, отказ от использования -t, когда это требуется,
вредит: таблицы будут неправильно отформатированы. Вы можете даже выяснить, какая
команда необходима для форматирования страницы:
funnyprompt$ grog /usr/man/man7/signal.7 groff -t -man /usr/man/man7/signal.7
"Grog" замещает "GROff Guess", и делает то, что говорит
guess. В этой работе я привожу небольшой скрипт на perl, который удаляет верхние
и нижние колонтитулы. Сохраните его под именем strip-headers и выполните chmod
755.
#!/usr/bin/perl -wn
# обработка всего файла:
undef $/;
# удаление верхнего колонтитула:
s/^\n*.*\n+//;
# удаление нижнего колонтитула:
s/\n+.*\n+$/\n/g;
# удаление разрывов страниц:
s/\n\n+[^ \t].*\n\n+(\S+).*\1\n\n+/\n/g;
# сворачивание двух и более пустых строк в одну:
s/\n{3,}/\n\n/g;
# смотрите что осталось...
print;
Используйте скрипт в качестве первого фильтра после команды 'man', поскольку
он обрабатывает то, что выводится после groff. Например:
funnyprompt$ man bash | strip-headers | col -bx > bash.txt
10) Как получить руководство в формате PostScript?
funnyprompt$ groff -t -e -mandoc -Tps manpage.1 > manpage.ps
Отпечатайте или просмотрите это руководство, используя ваш любимый принтер/просмотрщик
PostScript. См. вопрос 9) для уточнения опций.
11) Как заставить работать 'apropos' и 'whatis'?
Предположим, что вы задались вопросом - какие компиляторы установлены на вашей
системе, и как они могут быть вызваны. Чтобы ответить на первый вопрос, выполните
команду:
funnyprompt$ apropos compiler
f77 (1) - Fortran 77 compiler
gcc (1) - GNU C and C++ compiler
pc (1) - Pascal compiler
Apropos и whatis используются, чтобы дать быстрый ответ, на который имеется
информация в руководствах. Обе программы отыскивают файлы, называемые 'whatis',
которые могут находиться в любом основном каталоге руководств. Прежде я говорил,
файлы whatis содержат строки в каждой из которых содержится запись для любой
страницы руководства из соответствующего каталога. Фактически, эта строка берется
из раздела NAME (буду точнее: все строки раздела соединены в одну строку, также
записано обозначение раздела в круглых скобках после имени руководства). Файлы
whatis созданы с помощью программы makewhatis(8). Имеются разные версии программы,
поэтому посмотрите руководства для уточнения доступных опций этой программы.
Для makewhatis, способного извлекать информацию из раздела NAME, важно, чтобы
вы правильно записывали информацию в этот раздел, твердо придерживаясь формата
этого раздела, описанного в вопросе 2). Существуют различия
между apropos и whatis. Apropos (эквивалентен man -k) занимается поиском
запроса в любой части строки, а whatis (man -f) ищет только целое слово.
Следовательно, 'whatis cc' сообщит есть ли руководство по cc и ничего
не скажет о gcc.
Исправления и комментарии приветствуются!
A) Copying conditions
Copyright 1995-2000 by Jens Schweikhardt <[email protected]>
Voice: ++49 7151 909516
Unless otherwise stated, Linux HOWTO documents are copyrighted by their
respective authors. Linux HOWTO documents may be reproduced and distributed
in whole or in part, in any medium physical or electronic, as long as this
copyright notice is retained on all copies. Commercial redistribution is
allowed and encouraged; however, the author would like to be notified of
any such distributions. All translations, derivative works, or aggregate
works incorporating any Linux HOWTO documents must be covered under this
copyright notice. That is, you may not produce a derivative work from a
HOWTO and impose additional restrictions on its distribution. Exceptions
to these rules may be granted under certain conditions; please contact
the Linux HOWTO coordinator at the address given below. In short, we wish
to promote dissemination of this information through as many channels as
possible. However, we do wish to retain copyright on the HOWTO documents,
and would like to be notified of any plans to redistribute the HOWTOs.
If you have questions, please contact the Linux HOWTO coordinator,
Tim Bynum, at
[email protected]
via email.
Авторские права
Авторские права на русский перевод этого
текста принадлежат © 2000 SWSoft Pte Ltd. Все права
зарезервированы.
Этот документ является частью проекта Linux
HOWTO.
Авторские права на документы Linux HOWTO
принадлежат их авторам, если явно не
указано иное. Документы Linux HOWTO, а также их
переводы, могут быть воспроизведены и
распространены полностью или частично на
любом носителе физическом или электронном,
при условии сохранения этой заметки об
авторских правах на всех копиях.
Коммерческое распространение разрешается
и поощряется; но так или иначе автор текста
и автор перевода желали бы знать о таких
дистрибутивах.
Все переводы и производные работы,
выполненные по документам Linux HOWTO должны
сопровождаться этой заметкой об авторских
правах. Это делается в целях предотвращения
случаев наложения дополнительных
ограничений на распространение документов
HOWTO. Исключения могут составить случаи
получения специального разрешения у
координатора Linux HOWTO с которым можно
связаться по адресу приведенному ниже.
Мы бы хотели распространить эту
информацию по всем возможным каналам. Но
при этом сохранить авторские права и быть
уведомленными о всех планах
распространения HOWTO. Если у вас возникли
вопросы, пожалуйста, обратитесь к
координатору проекта Linux HOWTO по электронной
почте: <[email protected]>,
или к координатору русского перевода Linux HOWTO
компании SWSoft Pte Ltd. по адресу <[email protected]>
