LINUX MAN PAGE
Раздел 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 <schweikh@noc.dfn.de>
.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, где для них используется жирный шрифт. Т.е., вы должны использовать:
.I /usr/include/stdio.h
и
.B #include <stdio.h>
Специальные макросы, которые обычно записываются в верхнем регистре, выводятся жирным шрифтом:
.B MAXINT
В списке кодов ошибок: коды выводятся жирным шрифтом. Этот список обычно использует .TP (параграф):
.TP
.B EBADF
.I fd is not a valid file descriptor.
.TP
.B EINVAL
.I fd is unsuitable for reading
Любые ссылки на другие руководства (или на другие темы в данном руководстве) выводятся жирным шрифтом. Если дается номер раздела, то он выводится шрифтом roman:
.BR man (7)
Акронимы смотрятся лучше всего, когда набраны мелким шрифтом. Т.е., я рекомендую:
.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.