Man-страницы — Полное руководство

Если у вас нет времени читать справочную страницу команды man, я просмотрел ее для вас.

Введение

Если вы используете командную строку в UNIX-подобных системах, вы, вероятно, знаете команду man. Это мощный инструмент для поиска документации по любой программе или библиотеке.

Но знаете ли вы, откуда берутся «справочные страницы», как они устроены, советы и рекомендации по их лучшему чтению и какие другие инструменты доступны, чтобы помочь вам?

Это руководство отправит вас в увлекательное путешествие по увлекательному миру справочных страниц.

Вы даже можете прочитать это руководство в виде справочной страницы в своей системе, выполнив следующую команду:

curl -o- https://gist.githubusercontent.com/sebastiancarlos/a7fb89f73b4617ccc2ea9445abf62f90/raw/8edec5fbd1019c4df0c13fc79d2cc514d7f60735/man-guide.1 | man -l -

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

Часть 1: Основы

1. Что такое «справочная страница»?

«Страница руководства» — это сокращение от «страница руководства». Man-страницы — это хорошо известная форма документации по программному обеспечению, обычно встречающаяся в UNIX-подобных операционных системах.

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

2. Как читать справочные страницы?

Вы можете прочитать справочные страницы, набрав команду man на своем терминале, а затем имя нужной «справочной страницы».

Например, введите man ls, чтобы прочитать справочную страницу для команды ls.

Примечание. Существует несколько реализаций команды man. Наиболее популярными являются man-db и mandoc. Оба они соответствуют спецификации POSIX. Мы рассмотрим все это подробнее позже.

3. Как организованы справочные страницы?

Виртуальное руководство обычно разбито на разделы. Каждый раздел содержит записи, описывающие определенную тему. Одна запись называется «справочной страницей».

Есть некоторые условности:

• Названия разделов обычно представляют собой цифры (1, 2, 3 и т. д.). Каждое число имеет определенное значение («1» — для исполняемых программ, «2» — для системных вызовов и т. д.)
• Каждая «справочная страница» обычно имеет известную структуру («Имя», «Синопсис», «Описание» и т. д.).
• Man-страницы обычно обозначаются своим именем, за которым следует его раздел в круглых скобках (например, ls(1) и null(4)).

4. Имеются ли справочные страницы для каждой программы?

Страницы руководства предназначены для документирования операционной системы и каждого программного обеспечения в ней. Таким образом, ожидается, что программное обеспечение, которое вы устанавливаете, добавит свои собственные справочные страницы.

Но с появлением Интернета и конкурирующих форм документации некоторые программы (и даже некоторые операционные системы) имеют основную документацию в другом месте. Некоторые вообще не предоставляют «справочные страницы»!

Тем не менее, man-страницы продолжают оставаться каноническим способом документирования программного обеспечения в UNIX, особенно когда оно «близко к железу» или доступно через командную строку.

5. Из чего на самом деле состоят справочные страницы?

Справочные страницы обычно пишутся на языке разметки «roff» — традиция, которая началась с первого издания руководства по UNIX.

Этот язык разметки универсален: мы можем использовать исходные файлы для создания справочных страниц в различных форматах — не только текста для терминала, но и PDF-файлов или веб-страниц. Мы объясним, как позже.

Некоторые авторы справочных страниц используют другие языки разметки, такие как Markdown или reStructuredText, для написания своей документации. Однако они обычно конвертируются в roff перед включением в окончательный файл справочной страницы.

6. Каковы разделы справочных страниц?

Общие разделы:

• 1 — исполняемые программы или команды оболочки (ls, grep, vim и т. д.)
• 2 — системные вызовы (функции, которые оборачивают операции, выполняемые ядром ОС.)
• 3 — вызовы библиотек (функции внутри библиотек. То есть функции, предназначенные для вызова другими программами, а не конечным пользователем. Обычно они определяются в терминах конкретного языка программирования, например C.)
• 4 — Специальные файлы (также известные как «устройства». Обычно это файлы, расположенные в /dev, которые обеспечивают доступ к устройствам через ядро. «Устройство» — это термин, используемый в основном для аппаратного обеспечения, принадлежащего системе. , например диски или принтеры. Существуют также «псевдоустройства», которые эмулируют поведение устройства в программном обеспечении, например /dev/null и /dev/random)
• 5 — Форматы файлов и файлы конфигурации (описывает различные удобочитаемые форматы файлов и файлы конфигурации, например /etc/passwd)
• 6 — Игры
• 7 — Разное (обзоры или описания различных тем, соглашений и протоколов, стандартов наборов символов, стандартного макета файловой системы и прочего прочего).
• 8 — Команды системного администрирования (команды, которые могут использоваться или обычно используются только суперпользователем, например, команды системного администрирования, демоны и команды, связанные с оборудованием).

Вы можете найти некоторые устаревшие разделы в дикой природе (9, o, n, l), но их не следует использовать.

Иногда к номеру раздела добавляются дополнительные символы. Например, Debian использует «1posix» для хранения «документации POSIX» для некоторых команд. Цель состоит в том, чтобы создать «пространство имен» или указать, что некоторые справочные страницы принадлежат конкретному проекту.

7. Какие разделы есть на странице руководства?

Обычные разделы:

ИМЯ

Этот раздел имеет стандартный формат, состоящий из имени программы или функции, за которым следует тире, за которым следует краткое однострочное описание. Например:

ls - list directory contents

ОБЗОР

Краткое описание интерфейса команды или функции.

СИНОПСИС обычно не содержит прозы. Он просто иллюстрирует команду или функцию таким образом, чтобы она соответствовала всем возможным вызовам.

В некоторых случаях рекомендуется проиллюстрировать несколько эксклюзивных вызовов вместо того, чтобы сжимать все возможности в один, как показано в разделе ОБЗОР файла man-db man(1).

К этому разделу применяются следующие соглашения:

• полужирный текст — введите точно так, как показано.
• курсивный текст — заменить соответствующим аргументом.
• [optional] — любые или все аргументы в пределах [] являются необязательными.
• это | that — вертикальные полосы (|) разделяют варианты
• аргумент… — Аргумент повторяемый

Точный рендеринг может варьироваться в зависимости от устройства вывода. Например, man обычно не может отображать курсив при работе в терминале и вместо этого обычно использует подчеркнутый или цветной текст.

ОПИСАНИЕ

Объяснение того, что делает программа, функция или формат. Он показывает, как он взаимодействует с файлами и стандартным вводом, и что он выдает при стандартном выводе или стандартной ошибке.

Следует опустить внутренние детали и детали реализации, если только они не важны для понимания интерфейса.

Он должен описывать только обычный случай — информация об опциях командной строки должна находиться в разделе OPTIONS.

ОКРУЖАЮЩАЯ СРЕДА

Список всех переменных среды, которые влияют на программу или функцию, и то, как они влияют на нее.

ФАЙЛЫ

Список файлов, которые использует программа или функция, таких как файлы конфигурации, файлы запуска и файлы, с которыми непосредственно работает программа.

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

Короче говоря, вы можете ожидать, что пути к файлам в этом разделе будут как фактическими, так и фактическими.

СТАНДАРТЫ

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

Если API не регулируется какими-либо стандартами, но обычно существует в других системах, это следует отметить. Здесь также следует отметить, является ли функция или команда специфичной для Linux или GNU. Если он доступен в BSD, это также следует отметить здесь.

ИСТОРИЯ

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

ПРИМЕЧАНИЯ

Разные заметки.

ПРЕДОСТЕРЕЖЕНИЯ

Предупреждения о типичном неправильном использовании пользователем, которое не является ошибкой или дефектом дизайна.

ОШИБКИ

Список ограничений или известных дефектов.

ПРИМЕРЫ

Один или несколько примеров, демонстрирующих использование этой функции, файла или команды.

Примечание. Инновационный проект в области справочных страниц, mankier.com, показывает раздел ПРИМЕРЫ сразу после раздела НАЗВАНИЕ. Этот автор поощряет эту нестандартную практику, особенно ввиду успеха примеров проектов документации, таких как страницы TLDR.

АВТОРЫ

Список авторов документации или программы.

Некоторые люди не одобряют этот раздел, поскольку он имеет тенденцию к беспорядку.

СМОТРИТЕ ТАКЖЕ

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

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

Учитывая распределенный, автономный характер проектов FOSS и их документации, иногда желательно, чтобы раздел SEE ALSO включал ссылки на справочные страницы, предоставленные другими проектами.

8. Дополнительные разделы для команд (Только в разделах 1 и 8)

Помимо общих разделов, упомянутых до сих пор, некоторые разделы являются эксклюзивными для команд:

ВАРИАНТЫ

Описание параметров командной строки, принимаемых программой, и того, как они изменяют ее поведение.

СТАТУС ВЫХОДА

Список возможных значений состояния выхода программы и условий, при которых эти значения возвращаются.

9. Дополнительные разделы для функций (Только в разделах 2 и 3)

Следующие разделы предназначены исключительно для функций:

БИБЛИОТЕКА

Библиотека, предоставляющая символ. Он показывает общее имя библиотеки и в скобках имя файла библиотеки.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

Список значений, которые библиотечная функция возвращает вызывающей стороне, и условия, при которых эти значения возвращаются.

ОШИБКИ

Список значений, которые могут быть помещены в errno в случае ошибки, вместе с информацией о причине ошибки. (errno — это переменная, содержащая номер последней ошибки, возникшей в системном вызове или библиотечной функции. Вы можете использовать команду errno для поиска значения номера ошибки или имени ошибки.)

АТРИБУТЫ

Сводка различных атрибутов функции. В основном связаны с памятью и потокобезопасностью.

ВЕРСИИ

Сводка систем, в которых API работает по-разному или где есть похожий API.

Часть 2: История справочных страниц

10. СТОК

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

Старейшим предком man-страниц является программа RUNOFF из легендарной операционной системы CTSS. Название RUNOFF происходит от идиоматического выражения run off, означающего распечатать или сделать ксерокопию. Это одна из первых программ форматирования текста (или набора текста).

RUNOFF была одной из пары программ TYPSET и RUNOFF, разработанных Джеромом Зальцером в 1964 году для форматирования его докторской диссертации. TYPSET использовался для создания и редактирования исходных текстовых файлов, содержащих текст на английском языке и некоторые управляющие слова для описания инструкций по форматированию (выравнивание, выравнивание и т. д.). RUNOFF напечатает отформатированный текст, исключая контрольные слова.

11. RUNOFF как язык разметки

Если идея файла, содержащего как естественные языки, так и определенные команды форматирования, очень похожа на «язык разметки», такой как HTML, LaTeX или Markdown, это потому, что так оно и есть. Фактически, RUNOFF и другие ранние программы форматирования текста являются прародителями языков разметки.

Слово «разметка» происходит от тысячелетнего искусства «разметки» рукописи, которое включает в себя добавление рукописных печатных инструкций на полях. Затем эти инструкции читает человек или система, которым поручено создание окончательной версии документа.

12. От RUNOFF к troff/groff

В конечном итоге RUNOFF был переписан как roff (1971) для UNIX. Примечательно, что roff использовался для форматирования первого издания руководства UNIX, которое имело структуру, аналогичную используемому сегодня макету справочной страницы.

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

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

GNU troff (groff) считается самым популярным вариантом troff в современных установках UNIX.

13. Первая «мужская» команда

Хотя в первой редакции UNIX не было специальной команды man. Вторая редакция через несколько месяцев представила его:

Эта команда «man» была сценарием оболочки, который ожидал название требуемой страницы руководства и, возможно, номер раздела.

Его задача заключалась в том, чтобы найти исходный файл для справочной страницы и передать его roff, который выполняет тяжелую работу по его обработке для отображения пользователю. (В те дни показ предполагал печать на бумаге.)

Не так много изменилось. В наши дни реализации команды «man» работают аналогичным образом.

Часть 3: POSIX

14. Спецификация «мужчина»

man — это одна из утилит, определенных POSIX, семейством стандартов, предназначенных для обеспечения совместимости между UNIX-подобными операционными системами.

И man-db, и mandoc соответствуют спецификации man POSIX».

Специалисты по POSIX подробно обсуждали, сколько или сколько должно требоваться от «человеческих» реализаций, чтобы быть совместимыми. В конце концов они остановились на минимализме: POSIX определяет простое использование без опций и с опцией -k плюс несколько переменных окружения.

15. Команда «man» без опций

При вызове man без опций (например, man name) POSIX говорит следующее:

«Если name является именем стандартной утилиты, man как минимум должен написать сообщение, описывающее синтаксис, используемый стандартной утилитой, ее параметры и операнды (аргументы) ».

Обратите внимание, что POSIX ничего не говорит ни о формате конечного сообщения, ни о разметке исходных файлов, ни о roff/groff — это считается деталью реализации. Вы можете пойти дальше и написать свою собственную POSIX-совместимую команду «man» в Markdown и COBOL, и никто не сможет вас остановить!

Действительно, mandoc — это реализация, которая вообще не вызывает groff, хотя и ожидает, что исходные файлы будут либо в макросах man, либо в mdoc, которые построены поверх языка roff.

16. Команда «man» с опцией «-k» или «по поводу»

При вызове man с параметром -k (man -k name) POSIX говорит, что man должен искать «имя» в «суммарной базе данных утилит», которая содержит «краткое описание назначения каждой утилиты», и должен записать все совпадающие результаты. .

Другими словами, man -k name должно быть эквивалентно grep -Ei ‘name’ summary-database (флаг -i означает нечувствительность к регистру, а флаг -E означает, что «имя» может быть регулярным выражением).

Это предполагает, что «суммарная база данных» представляет собой текстовый файл с одной записью в строке — POSIX говорит, что такая организация не требуется, это просто иллюстративный пример предполагаемого типа поиска. Действительно, старые реализации man имели такой же текстовый файл, но «man-db» использует настоящую базу данных.

Есть две важные детали о man -k, не упомянутые в POSIX:

• Реализации man обычно используют текст из раздела «Имя» страницы руководства в качестве записи в сводной базе данных.
• man -k эквивалентно команде apropos, которая предоставляется как «man-db», так и «mandoc».

17. Команда «man» с опцией «-f», или «whatis»

Хотя POSIX не определяет параметр -f (или эквивалентную команду whatis command), в нем говорится, что «параметр -f рассматривался, но из-за различий в реализации он не был включен в этот том POSIX.1–2017», поэтому, вероятно, быть включены в конце концов.

Фактические различия в реализации между man-db и mandoc тривиальны.

whatis name похож на apropos name, за исключением того, что man ищет «имя» только в именах справочных страниц, а не в полном описании. Если совпадение найдено, возвращаемое значение такое же, как в apropos.

Другими словами, man -f name должно быть эквивалентно grep -Ei ‘^name ’ summary-database (то же, что и раньше, но ищет строки, начинающиеся с «имя», за которым следует пробел).

18. Переменные окружения «человек»

POSIX также определяет следующие переменные окружения:

• LANG, LC_ALL, LC_CTYPE, LC_MESSAGES и NLSPATH: обычные переменные UNIX для интернационализации.
• PAGER: Команда фильтрации вывода для записи вывода в терминал. Вывод страницы должен передаваться через эту команду. По умолчанию это пейджер «больше» (пейджер POSIX), хотя в наши дни пейджер «меньше» почти повсеместно предпочтительнее.

Есть еще одна переменная среды, упомянутая, но не определенная в POSIX: MANPATH. И «man-db», и «mandoc» определяют его как последовательность имен каталогов, разделенных двоеточиями (точно так же, как PATH). Это один из способов переопределить корневой каталог по умолчанию, в котором в системе расположены исходные файлы справочной страницы. Но большинству пользователей не нужно устанавливать его.

На этом мы охватываем все, что POSIX может сказать о команде man. Теперь давайте перейдем к самой популярной реализации man: man-db.

Часть 3: Man-db

19. Регулярное использование команды «man».

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

Раздел, если он указан, указывает пользователю искать только в этом разделе. Действие по умолчанию — поиск во всех доступных разделах в порядке, определенном во время установки man-db, и отображение только первой найденной страницы.

Вот некоторые допустимые альтернативные варианты написания man 7 man:

• man man.7
• man 'man(7)'

20. Опция «-K», или «— глобально-уместно»

global-apropos ищет не только краткое описание (например, apropos), но и полный текст на всех страницах руководства.

Это грубый поиск, который, вероятно, займет некоторое время — если вы можете, вы должны указать раздел. Условия поиска могут быть простыми строками (по умолчанию) или регулярными выражениями, если используется опция --regex.

Обратите внимание, что при этом выполняется поиск «roff» источников справочных страниц, а не отображаемого текста, и поэтому могут быть ложные срабатывания из-за таких вещей, как комментарии в исходных файлах.

Также обратите внимание, что «global apropos» на самом деле попытается отобразить каждое найденное совпадение, поэтому, если вы ожидаете много результатов, вы можете также добавить флаг -w (который мы увидим позже), чтобы сделать его man стареющий.

21. Опция ‘-l’ или «режим локального файла»

В локальном режиме -l или --local-file , man форматирует и отображает локальные файлы руководств вместо поиска в коллекции страниц руководства системы.

Каждый аргумент страницы руководства будет интерпретироваться как исходный файл «roff».

Если в качестве аргумента передается -, ввод будет браться из stdin.

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

22. Опция «-w», или «-где»

Параметр -w (также --where, --path и --location) печатает расположение исходного roff-файла, а не отображает его.

23. Страницы-кошки и опция «-W» или «--where-cat».

При использовании современного man-db можно хранить отформатированные страницы руководства на диске, чтобы в будущем запросы не приходилось форматировать заново.

Эти предварительно отформатированные справочные страницы известны как «кошачьи страницы».

Хотя cat-страницы требуют несколько мегабайт дискового пространства, они существенно увеличивают скорость. Действительно, страницы с кошками могут загружаться в два-три раза быстрее!

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

Иерархия страниц cat создается в отдельной папке от иерархии страниц руководства — она отражает папки и имена файлов иерархии man. Короче говоря, это кеш.

Будут ли в вашей системе создаваться страницы с кошачьими страницами, зависит от нескольких факторов, в том числе от того, как был установлен man-db. Поэтому обязательно прочитайте его руководство (man-db-manual.{ps/txt}), его конфигурационный файл (/etc/man_db.conf) и, естественно, справочную страницу для man.

Вы обнаружите, что в большинстве систем по умолчанию кошачьи страницы создаются, только если вы попытаетесь запустить man с шириной столбца, установленной на 80 (это легко сделать с помощью переменной env MANWIDTH=80), что, в конце концов, прекрасно выглядит по умолчанию для любого экрана. размер!

Вам также может понадобиться вручную запустить команды mandb и catman, обычно от имени пользователя root, чтобы создать иерархию кошачьих страниц для всех ваших справочных страниц.

Вы можете проверить, существует ли страница с кошачьими страницами для данной справочной страницы, запустив man -W ls. То есть с флагом -W (также --where-cat или --location-cat). Он должен напечатать расположение страницы с котом для команды ls. Это прекрасно!

24. Опция «-L», или «— локаль»

Параметр -L или --locale позволяет указать используемый язык. Это переопределяет переменные env, которые мы видели раньше, такие как LC_MESSAGES и LANG.

Он ищет страницу на указанном языке и возвращается к английскому языку.

25. Опция «-M», или «-manpath»

Параметр -M или --manpath=path позволяет указать альтернативный путь для использования. Он переопределяет переменную env MANPATH, которую мы видели ранее, или настройки в вашем файле конфигурации (/etc/man_db.conf). Значение должно быть списком каталогов, разделенных двоеточием, как PATH.

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

Ваша система может иметь несколько иерархий справочных страниц одновременно, и когда вы запускаете man, вы выполняете поиск во всех них. Скорее всего, в вашей системе есть справочные страницы в нескольких иерархиях. Чтобы убедиться в этом, вы можете запустить команду manpath, которая выводит текущее значение manpath.

Параметр -M может быть полезен, если вы хотите свернуть свою собственную систему документации поверх команды man. Если вы просто хотите просмотреть справочные страницы из другого места, вы можете использовать опцию -l.

26. Параметры «— регулярное выражение», «— подстановочный знак» и «— только имена»

Параметр --regex позволяет вам видеть все страницы, любая часть имени или описания которых соответствует аргументу в виде регулярного выражения (аналогично команде apropos). Так как выбрать «лучшую» страницу при поиске по регулярному выражению невозможно, этот вариант подразумевает -a (--all).

Опция --wildcard показывает все страницы, любая часть имени или описания которых соответствует аргументу страницы с использованием подстановочных знаков в стиле оболочки (аналогично --apropos -wildcard). Как и --regex, это также подразумевает -a (--all).

Параметр --names-only при использовании с параметром --regex или --wildcard соответствует только именам страниц, но не описаниям страниц (так же, как whatis). Если ни опция --regex, ни опция --wildcard не используются, эта опция не действует, поскольку man по умолчанию выполняет поиск «только по именам».

27. Вариант «все», или «— все»

По умолчанию man завершает работу после отображения наиболее подходящей страницы руководства, которую находит. Чтобы заставить man отображать все соответствующие страницы руководства, используйте параметр -a или --all.

Теперь этот вариант немного неудобен, потому что он работает, показывая вам первое совпадение, а когда вы его закрываете, он спрашивает, хотите ли вы увидеть следующее. Лучшим вариантом может быть запуск man -a -w для одновременного отображения всех соответствующих файлов.

28. Опция «— без подстраниц»

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

Короче говоря, если у команды есть подкоманда (например, git diff), то по соглашению ее справочная страница будет иметь имя git-diff, но вы все равно можете получить к ней доступ, набрав man git diff. Параметр no-subpages отключает это поведение.

29. Опции «— пейджер» и «— подсказка»

Используя опцию -P или --pager, вы можете указать используемый пейджер вывода. По умолчанию man использует less. Этот параметр переопределяет переменные env MANPAGER и PAGER.

Параметр -r или --prompt полезен, когда в качестве пейджера используется последняя версия less. Подсказка по умолчанию, используемая man, показывает это в нижней части меньшего экрана: Manual page name(section) line x.

Мне очень нравится эта меньшая функция, она позволяет любому установить собственное приглашение. man хорошо использует это.

30. Варианты «— без переносов» и «— без выравнивания»

Параметр --no-hyphenation или --nh отключает автоматическую расстановку переносов на разрывах строк. Это полезно для поиска текста в пейджере less, не беспокоясь о возможном переносе слова поиска.

Вы заметили, что справочные страницы имеют полностью выровненный текст? В этом секрет его гладкости! Параметр --no-justification или --nj отключает полное выравнивание по ширине, оставляя текст выравниваемым только по левому краю. Это может быть полезно, когда вы хотите скопировать и вставить прямо из less.

31. Опция «-t» — вывод в PostScript и PDF

Использование опции -t или --troff переводит вас в «режим troff» groff, что означает, что вывод больше не нацелен на терминал («режим nroff»). По умолчанию он генерирует PostScript, язык, на котором построены PDF-файлы.

Чтобы преобразовать страницу руководства в PostScript, запустите man -t ls > ls.ps, а чтобы преобразовать ее в PDF, вы можете использовать man -T pdf ls > ls.pdf. Имейте в виду, что отформатированный PDF-файл направляется на стандартный вывод, поэтому вы можете использовать оператор (>) для создания файла.

Вывод в формате PDF обычно выглядит довольно хорошо, но он ограничен шрифтом Times New Roman с некоторыми жестко закодированными вещами. И некоторые справочные страницы в дикой природе могут отображаться неправильно, особенно если есть длинные таблицы или нетрадиционное форматирование.

32. Вывод в HTML — здесь будут драконы

Преобразование справочных страниц в HTML с использованием man -H обычно не рекомендуется с помощью man-db, поскольку результирующий вывод может быть низкого качества. Сложное форматирование часто преобразуется в изображения с низким разрешением, что не выглядит привлекательным или доступным.

Некоторые разработчики, создающие онлайн-страницы руководств, прибегают к созданию своих собственных конвертеров roff-to-HTML для создания более чистых и привлекательных выходных HTML-файлов.

Некоторые люди используют mandoc для преобразования HTML, что, на мой взгляд, создает лучший макет и, что более важно, не генерирует эти странные изображения с низким разрешением.

33. По поводу базы данных и скрипта инициализации

Man-db на самом деле называется так, потому что он использует реальную базу данных, обычно Berkeley DB, для хранения и обслуживания справочных страниц. Чтобы поддерживать эту базу данных в актуальном состоянии, у man-db есть сценарий инициализации, который запускает команду mandb. В зависимости от вашей системы и установки он может быть настроен на периодический запуск в systemd.

Запуск этого скрипта создает и обновляет индексы для базы данных, что позволяет использовать команды apropos и whatis. В разных режимах работы обновление базы данных может быть автоматическим или выполняться вручную с помощью mandb. Вы можете обратиться к руководству man-db (man-db-manual.{ps/txt}) для получения дополнительной информации.

Часть 4: Разное

34. Альтернативы справочной странице — tldr,cheat.sh, GNU Info

В дополнение к справочным страницам есть несколько альтернатив.

Tldr

Проект tldr предоставляет краткие и практические примеры инструментов командной строки. Страницы Tldr управляются сообществом и могут быть отличным дополнением к более подробным справочным страницам.

Вы можете вызвать их с помощью команды tldr. Например, tldr ls.

Существует несколько реализаций команды tldr. Классическая версия хороша, но лично я рекомендую версию на Rust, tealdeer, потому что она действительно очень быстрая.

Cheat.sh

Существует также cheat.sh, который объединяет несколько поставщиков шпаргалок, включая tldr, а также другие сервисы, такие как StackOverflow. Хотя это замечательный проект, этот автор предпочитает напрямую использовать tldr, который быстрее и в любом случае является крупнейшим проектом в своем роде.

Texinfo (информация GNU)

Проект GNU предоставляет альтернативу справочным страницам для своего программного обеспечения под названием «Texinfo». В то время как большая часть программного обеспечения GNU также предоставляет справочные страницы, документы Texinfo, как правило, более полны.

В файлах используется синтаксис набора текста «Texinfo». Они имеют древовидную структуру с узлами, которые могут быть связаны друг с другом. В отличие от man-страниц, они не содержат всей информации на одной странице, а разбросаны по разным узлам. Вы можете прочитать его через Emacs или с помощью автономной команды info.

Информация GNU немного причудлива. Если вам нужно прочитать документацию по программному обеспечению GNU, есть две альтернативы:

• Вместо этого прочитайте HTML-версию, размещенную на веб-сайте GNU.
• Направьте его на less (например, info groff | less). Таким образом, вы сможете прочитать все руководство за один раз, не заморачиваясь с навигацией по узлам дерева info.

Если вы хотите использовать простую информацию GNU, проверьте это руководство.

Другое

Другим источником документации по вашей системе является каталог /usr/share/doc. Он содержит файлы из многих установленных программных пакетов. Эти файлы обычно представляют собой обычный текст, PDF или HTML.

В наши дни вы можете также спросить ИИ, как что-то сделать на терминале. Это доступно, например, с Copilot for CLI.

35. Справочные страницы онлайн

Есть несколько хороших онлайновых справочных страниц. Некоторые из них связаны с операционными системами и дистрибутивами, например, Arch Man Pages.

Другие, такие как manned.org, содержат справочные страницы для разных версий ОС и также содержат исходные файлы roff.

Инновационные ресурсы, такие как ManKier, включают информацию tldr в качестве первого раздела страницы руководства, оглавление сбоку и внутренние гиперссылки.

Я также хотел бы отметить, что некоторые справочные страницы старой школы, такие как OpenBSD и Void Linux, на самом деле показывают вам родные теги roff, когда вы наводите курсор мыши!

36. Создание справочных страниц

Существуют различные способы создания справочных страниц, старый способ заключается в написании их в формате roff. Доступно несколько ресурсов, таких как Практические руководства по Unix: mdoc и Руководство по Groff.

Справочные страницы также можно создавать из других источников, таких как Markdown, с помощью таких инструментов, как pandoc и ronn из мира Ruby.

37. Проект «справочные страницы»

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

Недавно он был расширен за счет включения справочных страниц для других общих инструментов Linux, а не только для ядра.

Этот проект также содержит хорошее руководство для общих разделов справочных страниц на его man-pages(7).

38. Международный проект man-страниц

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

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

Заключительные мысли

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

Оставайтесь с нами во второй части, в которой мы рассмотрим создание справочных страниц с помощью Groff.

Спасибо за чтение! Если вам нравятся подобные юмористические истории о технологиях, и вы хотите поддержать меня, чтобы я продолжал писать вечно, подумайте о том, чтобы зарегистрироваться, чтобы стать участником Medium. Это 5 долларов в месяц, что дает вам неограниченный доступ к историям на Medium. Если вы зарегистрируетесь по моей ссылке, я получу небольшую комиссию. Вы также можете подписаться на меня в Medium и Twitter.