Linux Lexicon — Анатомия справочной страницы

Man -страницы обычно разбиты на ряд разделов с подробным описанием и названием, использованием и предостережениями. Справочные страницы могут быть трудными для чтения, но они являются ценными ресурсами, которые можно использовать в крайнем случае, и для них даже не требуется Интернет.

ИМЯ
Во-первых, заголовок имени, и это подводит итог. Этот раздел включает в себя название утилиты, а также краткое описание.

СИНТАКСИС
Существуют разные степени удобочитаемости от справочной страницы к справочной странице, но одно можно сказать наверняка, самая трудная часть, как правило, это расшифровка сложного синопсиса. Существует несколько соглашений для указания требуемой части информации для любой данной команды. Эти соглашения состоят из различных скобок и круглых скобок, а также других форм обозначений. Все эти различные условности могут сбить с толку новичка и обескуражить опытного, но не разбирающегося в искусстве руководств человека. Ниже мы разобьем эту тарабарщину на удобоваримые правила.

Эти правила довольно просты, но они становятся более сложными и даже пугающими, когда используются в длинных определениях функций, особенно когда они вложены друг в друга. Итак, мы рассмотрим некоторые вложения ниже, чтобы построить то, что мы разбили.

tar {A|c|d|r|t|u|x}[GnSkUWOmpsMBiajJzZhPlRvwo] [ ARG …]

Команда tar имеет много опций. Мы видим имя команды tar выделенным жирным шрифтом, потому что оно должно быть набрано, как показано. Затем мы видим, что фигурные скобки открываются с параметрами, разделенными вертикальной чертой, что указывает на то, что мы ограничены ими и должны выбрать только один. Далее идут необязательные флаги, мы можем использовать любое количество, хотя они могут не работать вместе, дальнейшее чтение справочной страницы прольет свет на любые потенциальные конфликты параметров. И, наконец, у нас есть повторяющийся аргумент, в случае tar это для файлов, с которыми вы работаете.

su [опции] [-] [ пользователь [ аргумент …]]

Опять же, мы видим su жирным шрифтом, потому что это имя команды. Во-вторых, мы видим, что на самом деле никакие флаги не указаны, а только то, что они необязательны. В-третьих, указан единственный флаг, но он также является необязательным. Наконец, мы видим необязательный аргумент, который повторяется внутри необязательного аргумента. Теперь то, что раньше выглядело очень загадочно, обретает смысл.

whois [{-h|–host } HOST ] [{-p|–port} ПОРТ ] [-abBcdGHKlLmMrRx] [-g ИСТОЧНИК:ПЕРВЫЙ-ПОСЛЕДНИЙ ] [-i ATTR [, ATTR ]…] [-s ИСТОЧНИК [, ИСТОЧНИК ]…] [-T TYPE [, TYPE ]…] [–verbose] ОБЪЕКТ

Это особенно плотный. Скопируйте его в свой любимый текстовый редактор и добавьте туда несколько дополнительных пробелов, если это поможет вам его прочитать. Просканировав это, вы должны начать видеть пару шаблонов. Части хоста и порта используют одно и то же форматирование для короткой и полной формы параметра, за которым следует аргумент для этого параметра, хотя сами по себе они являются необязательными. Затем мы видим строку необязательных флагов. Следующая часть об источниках от первого до последнего — это синтаксис, ожидаемый от whois, который объясняется позже на справочной странице. Теперь мы видим эту тройку необязательных флагов, которые принимают либо один аргумент, либо необязательные повторяющиеся аргументы, это своего рода соединение соглашений, которое может быть очень трудно полностью понять поначалу. Наконец, есть подробная опция и объект (хост/домен).

И вот как читать синопсис справочной страницы. Есть еще несколько соглашений, но они слишком неясны, чтобы описывать их в этой статье.

ОПИСАНИЕ
Обычно здесь описывается предполагаемое использование программы или утилиты. Некоторые руководства под этим заголовком будут более подробными, чем другие.

ОПЦИИ
Помните все эти флаги и различные аргументы, которые могут быть необязательными или обязательными? Здесь они все объясняются. Обычно здесь содержится полезная информация, и часто именно здесь вы найдете соглашение <argument>, указывающее, что данный флаг требует соответствующего аргумента. Иногда вы обнаружите, что параметры будут в части описания, потому что нет жестких правил, определяющих справочные страницы, только соглашения и желание соответствовать стандартам.

ПРИМЕРЫ
Это одна из самых удобных частей, которая, к сожалению, не включена во все руководства. Вы также обнаружите, что объем информации и количество примеров значительно различаются, и не все примеры действительно помогают при использовании команды.

Кроме того, вы будете регулярно находить разделы для авторов, информации об авторских правах, сообщений об ошибках и см. также (кстати).

Помимо этого, есть формально определенные разделы справочных страниц, как определено ниже.

Многие команды не имеют руководств более чем в одном разделе, но для тех, которые есть, или для тех, которые могут иметь неоднозначное название, вы можете указать раздел, как в примере ниже.

Команды — не единственные вещи, для которых есть руководства, как вы можете видеть из доступных разделов. Системные вызовы, файлы конфигурации и специальные устройства также могут иметь соответствующую справочную страницу. Количество информации о типичной установке Linux только на справочных страницах поражает, и то же самое относится и к другим UNIX-подобным операционным системам с открытым исходным кодом.

Если вы обнаружите, что справочной страницы недостаточно, и вы по-прежнему не понимаете команду, всегда проверяйте ее в Интернете, потому что многие люди предлагают более подробные объяснения определенных инструментов, но кроме того, многие дистрибутивы имеют собственные справочные страницы для различных программных пакетов. Как только вы обнаружите, что вам удобно работать с программным обеспечением, но по-прежнему чувствуете, что руководства не хватает, вы всегда можете внести свой вклад, написав свое собственное и отправив его в соответствующий проект. Документация часто является частью программных проектов, которой чаще всего пренебрегают, поэтому, даже если вы не умеете писать код, вы можете писать руководства, статьи для Wiki и учебные пособия, чтобы помогать другим.

Теперь, когда вы знаете анатомию справочной страницы, у вас нет оправдания, кроме RTFM (и это чтение бесплатного руководства для тех из вас, кто младше 18 лет) ;)

Читайте также: Linux Lexicon: используйте команду Watch для запуска команды каждые X секунд