Crazy Rebel: викификация, оформление, иллюстрация

2010-09-02T08:39:12Z

викификация, оформление, иллюстрация

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

==Происхождение ''man''==

: '''''Man''''' Небольшой экскурс в историю команды «''man''» и инструкция по чтению ''man''-страниц и созданию собственных.

Команда ''man'' гораздо старше ''info''. Это традиционный способ документирования утилит Linux, особенно тех, что работают из командной строки. Но вы когда-нибудь интересовались тем, как они устроены?

Каждая ''man''-страница принадлежит к одному из восьми разделов. Это разделение восходит ко временам, когда ''cat'' была еще котенком, хотя названия разделов с тех пор чуть изменились.

{{Врезка|Содержание=[[Изображение:LXF122_44_1.jpg|300px]] Стандартное расположение элементов на ''man''-странице упрощает навигацию, если вы разобрались, что вам надо.|Ширина=300px}}

В современных системах Linux это:
# Исполняемые программы или команды оболочки.
# Системные вызовы (функции, предоставленные ядром).
# Библиотечные вызовы (функции в библиотеках программ).
# Специальные файлы (обычно находятся в '''/dev''').
# Форматы файлов и соглашения (например, '''/etc/passwd'').
# Игры.
# Разное.
# Команды системного администрирования.

Номер раздела можно найти на первой строке самой ''man''-страницы в круглых скобках. Например, на экранном снимке ''man''-страницы команды ''odd'' (ниже) мы видим, что она принадлежит к первому разделу ''man''. Откройте ''man''-страницу ''fork'', и вы поймете, что это системный вызов (раздел 2). Команда ''getpwent'' относится к третьему разделу, ''fstab'' – к пятому, а ''fdisk'' – к восьмому.

Некоторые темы входят более чем в один раздел. Например, ''chmod'' – это и команда, и системный вызов. Просто ''man chmod'' покажет страницу из первого раздела. Если вам нужна страница системного вызова ''chmod'', нужно явно запросить ее из второго раздела, командой ''man 2 chmod''. Аналогично, ''man passwd'' покажет ''man''-страницу для команды ''passwd'' из первого раздела, а ''man 5 passwd'' покажет ''man''-страницу для формата файла паролей в разделе 5.

Man-страницы в моем руководстве по Unix редакции 6 (датированном 1973 годом) используют стандартный набор заголовков: заголовков: '''NAME''' (Название), '''SYNOPSYS''' (Краткий обзор), '''DESCRIPTION''' (Описание), '''FILES''' (Файлы), '''SEE ALSO''' (См. также), '''DIAGNOSTICS''' (Диагностика) и '''BUGS''' (Ошибки). Он сохранялся до man-страниц System V (около 1990 года), за исключением заголовка '''BUGS''', который в документации AT&t был удален или переименован в '''Caveats''' (предупреждения, пояснения) – видимо, из-за нежелания компании признать, что в их ПО бывают ошибки. На ''man''-странице может быть раздел с примерами ('''Examples'''). В руководстве GNU подход более либеральный: там можно найти
такие заголовки, как '''Overview''' (Общее представление), '''Environment '''(Среда), '''Author''' (Автор), '''Copyright''' (Авторские права) и '''Reporting Bugs''' (Как сообщить об ошибке?).

Секция '''SYNOPSIS''' – настоящее сердце ''man''-страницы. Здесь используется формальная запись, чтобы показать верный синтаксис команды, и нужно разбираться в его основных элементах:
* Квадратные скобки [как эти] означают необязательные элементы. Можно убрать их, и команда останется верной.
* Вертикальная черта означает «или». Так, [-i|-l] означает, что можно указать ключ '''-i''' или '''-l''', но не оба сразу.
* Многоточие (три точки …) означает, что предыдущий элемент можно повторить. Выделенный жирным шрифтом текст – это дословный текст команды, курсив (или подчеркнутый текст) нужно заменить подходящим аргументом.

Такая запись – на удивление мощное средство. Рассмотрим примеры:

ctags [-aBFtuvwx] [-f tagsfile] filename …

Это классический пример из руководства по SVR4. Во-первых, можно указать любое сочетание односимвольных опций из набора '''aBFtuvwx'''. Идея предварять их дефисом идет с незапамятных времен. (Кстати, интерпретирует эти аргументы сама команда, а не оболочка. Оболочка только считает '''-n''' обычной строкой аргумента.) Затем можно указать опцию '''-f''', за которой должно идти имя файла '''tagsfile'''. В конце указывается одно или несколько имен файлов. Имя файла не находится в квадратных скобках, поэтому оно обязательно – следует указать по меньшей мере одно.

Вот весьма эффектный пример использования вложенных квадратных скобок:

date [-u|--utc|--universal] [MMDDhhmm[[CC]YY][.ss]]

Во-первых, можно указать '''-u, --utc''' или '''--universal''' (все они означают одно и то же). Этот параметр необязателен. Потом можно указать дату и время. В этом случае нужно ввести как минимум '''MMDDhhmm''' (месяц, день, час, минуту). Потом можно (но не обязательно) указать год в виде двухразрядного числа ('''YY'''), который может предваряться или не предваряться двухразрядным числом века ('''CC'''). В конце можно (но не обязательно) указать секунды, предварив их точкой ('''.ss''').

===Большая Перезапись===

Большинство утилит командной строки в современных дистрибутивах Linux были переписаны Фондом свободного ПО (людьми из GNU). Во время этой Большой Перезаписи у команд появилось множество новых опций. Ребята из GNU также предложили «длинные» опции, состоящие из двух дефисов, за которыми следует слово. Например, у команды ''ls'' есть опция '''--directory''', эквивалентная обычной односимвольной опции '''-d'''. Однако у многих «длинных» опций нет однобуквенного эквивалента: например, '''--color''' и '''--group-directories-first''' команды ''ls''. Появление таких ключей стало неизбежным, потому что число параметров росло, и однобуквенных многим командам стало не хватать.

''Man''-страницы GNU также сделали популярной идею указывать в разделе '''SYNOPSYS''' не полный синтаксис команды, а только ее кратчайшее описание. Например, '''SYNOPSYS''' для команды ''ls'' выглядит так:

SYNOPSYS
ls [OPTION] … [FILE] …

Все опции описываются далее в разделе '''DESCRIPTION''' (описание). Конечно, такие ''man''-страницы были и до Linux, но скорее как исключение, чем правило. Ныне так выглядит большинство страниц.

===Где живут man-страницы?===

Сначала ''man''-страницы хранились в каталогах '''/usr/man/manx''' (где '''x''' – номер раздела), и больше нигде. Потом была добавлена переменная окружения '''MANPATH''', которая могла содержать списки каталогов для поиска. Это упрощало работу с набором локальных ''man''-страниц отдельно от системных. Сейчас для указания списка каталогов и «отображений '''manpath'''», которые связывают каталоги из переменной окружения '''PATH''' с каталогами, в которых должны находиться соответствующие страницы ''man'', применяется файл '''/etc/manpath.config'''. В нем также определяется порядок,
в котором будет производиться поиск в разделах ''man''-страниц.

Команда ''manpath'' показывает каталоги, где будет осуществляться поиск:

$manpath
/home/chris/man:/usr/local/man:/usr/local/share/man:/usr/share/man

''Man''-страницы в Linux также хранятся в сжатом виде: например, ''man''-страница для ''grep'' находится в файле '''grep.1.gz''' (где 1 – номер
раздела).

===Развернем свои собственные===

Сначала ''man''-страницы писали на древнем языке разметки. Как ни странно, пишут до сих пор! Изначально этот язык обрабатывался одной из двух программ
«выпуска» [runoff]: ''nroff'' генерировала вывод на экран терминала или простого символьного печатающего устройства, а ''troff'' – для популярного в те дни фотонаборного устройства. Эти команды были одним из первых примеров генерации разного вывода на основе одного и того же языка разметки и ранними предшественниками разметки на основе XML и преобразований XSL. Язык разметки остался, а для форматирования теперь используется команда ''groff'' (замена
GNU для ''nroff'' и ''troff'').

Язык разметки используется не в «сыром» виде, а через набор макропакетов. ''Мan''-страницы форматируются макропакетом «man». Остальные макропакеты используются для других задач. Я генерировал свои исследовательские отчеты в университете, подредактировав макрос ‘''mm''’, и даже целые книги (включая
классическую The C Programming Language) были написаны именно таким образом.

Давайте напишем ''man''-страницу для воображаемой (и довольно глупой) программы, которая перерабатывает ненужные биты. Она считывает один или несколько
указанных файлов и создает два выходных: в одном из них содержатся все нули из входных данных, в другом – все единицы. Вот исходный код для ''man''-страницы, использующий макрос «man»:

.TH br 1 “” “” “User Commands”
.SH NAME
br \- bit recycler
.SH SYNOPSIS
.B br
[ \-a | --append ] [ \-d | --delete-original ] [ -f \flbasename\fR ]
[\flFILE\fR...]
.SH DESCRIPTION
.B br
assists in the recycling of digital content by separating the
ones and zeros in the named \flFILE\fR(s) (or standard input if
none) into two separate files.
.SH OPTIONS
.TP
.B -a, --append
Append to the end of the output files, rather than starting
new ones
.TP
.B -d, --delete-original
Delete the input files after the bits have been recycled
.TP
.B -f
Use
.I basename
as the base name of the output files. The extensions.ones
and.zeros will be appended to form the output file names.
If none is specified, a basename of \*(lrecycled\*(rq is
assumed
.SH BUGS
.B br
does not recycle the bits of its own code segment when
done, which is wasteful

Этот пример не охватывает все возможности макроса форматирования, но демонстрирует основы использования заголовков и изменение шрифта. Чтобы узнать
все, прочтите ''man''-страницу ''groff_man''.

===Набегание опционности===

Я подсчитал число опций, описанных на ''man''-страницах 16 распространенных команд, и сравнил его в трех дистрибутивах Unix Linux.
В первом столбце ниже показаны результаты из руководства для шестой редакции Unix (около 1975 года). Второй столбец – из Руководства пользователя
для System V Release 4, датированного 1990 годом, а третий – из Ubuntu 9.04 2009 года. Частично я руководствовался собственным мнением насчет того,
что считать отдельной опцией, поэтому числа могут слегка плавать, но, думается, общее направление понятно!

{|class=wikitable border=1 cellpadding=5||-
! Команда
! 1975
! 1990
! 2009
|-
| сat
|0
|5
|12
|-
| cc
| 6
| 30
| >500
|-
| cmd
|2
|2
|7
|-
| cp
|0
|3
|28
|-
| date
|1
|2
|9
|-
| diff
|1
|15
|27
|-
| find
|15
|23
|80
|-
| grep
|4
|8
|46
|-
| ln
|0
|3
|13
|-
| ls
|10
|23
|58
|-
| mkdir
|0
|2
|6
|-
| mv
|0
|2
|12
|-
| ps
|4
|12
|84
|-
| rm
|2
|3
|11
|-
| sort
|6
|14
|23
|-
| wc
|0
|3
|8
|}

LXF122:DrBrown3 - История изменений

Crazy Rebel: викификация, оформление, иллюстрация