Linux страницы руководства

Время на прочтение
8 мин

Количество просмотров 32K

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

Навигация по основам Linux от основателя Gentoo:

Часть I: 1, 2, 3, 4

Часть II: 1, 2, 3, 4, 5

Часть III

1. Документация (вступление)
2. Модель прав доступа
3. Управление аккаунтами
4. Настройка окружения (итоги и ссылки)

Предисловие

Об этом руководстве

Встречайте «Администрирование для продолжающих», третье из четырех пособий, созданных для подготовки к экзамену «Linux Professional Institute’s 101» (2-ая редакция). Данная часть идеальна для тех, кто хочет улучшить свои знания фундаментальных основ администрирования Linux. Мы охватим ряд тем, включая системную и интернет документацию, модель прав доступа в Linux, управление аккаунтами пользователей и настройку окружения входа в систему.

Если вы новичок в Linux, рекомендуем начать с Частей 1 и 2. Для некоторых большая часть информации, изложенной в самоучителе, будет новой, но более опытные пользователи могут использовать его для того, чтобы отточить свои навыки администрирования Linux.

В конце серии этих руководств (всего их восемь, подготавливающих к экзаменам LPI 101 и 102) у вас будут все знания, необходимые для того, чтобы стать системным администратором Linux систем, а так-же вы будете готовы к получению сертификата LPIC уровня 1 от института Linux Professional.

Системная и сетевая документация

Типы системной документации в Linux

Существует три основных источника документации в Linux системах: страницы руководств (маны), info-страницы и поставляемая с приложениями документация в /usr/share/doc. В этом разделе мы рассмотрим каждый из этих источников, перед тем, как обращаться во внешний мир за дополнительной информацией.

Страницы руководств

Страницы руководств, или “man (от англ. manual — руководство) страницы”, ман-страницы, далее просто маны — это классическая форма справочной документации UNIX и Linux. В идеале, вы можете найти ман для любой команды, конфигурационного файла или библиотеки. Однако, на практике, Linux это бесплатное программное обеспечение и некоторые страницы руководств не были написаны или устарели. Тем не менее, маны остаются первым местом, куда следует обращаться за помощью.

Для доступа к ману просто введите man, а затем ваш запрос. Запустится программа-пейджер (просмотрщик, обычно less или more) со справочной информацией. Для того, чтобы закрыть её, нажмите клавишу q. Например, чтобы посмотреть информацию о команде ls, введите:

$ man ls

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

Секции ман-страниц

Файлы, содержащие информацию манов хранятся в /usr/share/man (или в /usr/man на некоторых старых системах). В этой директории вы найдёте страницы руководств, упорядоченные по следующим секциям:

Многочисленные ман-страницы

Некоторые темы существуют более чем в одной секции. Для демонстрации этого воспользуюемся командой whatis, показывающей доступные маны по теме:

$ whatis printf

printf               (1)  - format and print data
printf               (3)  - formatted output conversion

В данном случае, man printf по-умолчанию обратится к странице в секции 1 (Пользовательские программы). Если мы пишем программу на языке C, нас вероятно больше интересует страница из секции 3 (Библиотечные функции). Вы можете вызывать ман необходимой секции указав это в командной строке, так для вызова printf(3) мы введём:

$ man 3 printf

Поиск нужного мана

Иногда сложно найти правильную ман-страницу по заданной теме. В этом случае можно воспользоваться man -k для поиска по разделам «ИМЯ» ман-страниц. Но будьте осторожны, поскольку осуществляется поиск по подстроке и что-то, навроде man -k ls, выдаст очень много всего! Вот пример использования уточняющего запроса:

$ man -k whatis

apropos              (1)  - search the whatis database for strings
makewhatis           (8)  - Create the whatis database
whatis               (1)  - search the whatis database for complete words

Всё об “apropos”

Предыдущий пример не случаен. Во-первых, команда apropos полностью соответствует команде man -k. (На самом деле, я даже вам раскрою небольшой секрет. Когда вы запускаете man -k, фактически «за кулисами» стартует apropos). Во-вторых, существует команда makewhatis, которая сканирует все страницы в вашей Linux системе и создает базу данных для whatis и apropos. Обычно она запускается периодически из-под рута, чтобы поддерживать базу в актуальном состоянии:

# makewhatis

Для более подробной информации о команде «man» и её друзьях, вам стоит начать с изучения её собственной ман-страницы:

$ man man

MANPATH

По умолчанию, программа man будет искать ман-страницы в /usr/share/man, /usr/local/man, /usr/X11R6/man, и быть может в /opt/man. Возможно, вы захотите добавить новый пункт в этом пути поиска. Для этого, просто откройте /etc/man.conf в текстовом редакторе и добавьте строчку вроде такой:

MANPATH /opt/man

С этого момента, страницы руководств в директориях /opt/man/man* также будут найдены. Помните, что вам необходимо запустить makewhatis, чтобы добавить новые маны в базу whatis.

GNU info

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

$ info

Простой вызов команды info даст список доступных инфо-страниц в вашей системе. Вы можете перемещаться по нему используя стрелки, переходить по ссылкам (которые обозначены звездочкой) с помощью клавиши Enter и выйти нажав q. Навигация основана на таковой в Emacs, так что если вы знакомы с этим редактором, вам будет легко освоиться. Чтобы познакомиться с Emacs, посмотрите руководство на developerWorks: Living in Emacs.

Вы также можете указать нужную инфо-страницы в командной строке:

$ info diff

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

$ info info

/usr/share/doc

Есть еще один источник помощи в вашей системе Linux. Большинство программ поставляются с дополнительной документацией в других форматах, таких как: простые текстовые файлы, PDF, PostScript, HTML. Посмотрите в каталоге usr/share/doc (или /usr/doc на более старых системах). Вы найдете длинный список директорий, каждая из которых идет с определенным приложением на вашей системе. Поиск по этой документации может навести вас на очень ценную информацию, которая не доступна в манах или инфо-страницах, такую как учебники или дополнительная технической документация. Беглый взгляд указывает на то, что здесь очень много материала для чтения:

$ cd /usr/share/doc
$ find . -type f | wc -l
7582

Фьюу! Вашим домашним заданием на этот вечер будет прочитать всего лишь половину (3791) этих документов. Учтите, завтра будет опрос.

Linux Documentation Project

В дополнение к системной документации, в интернете существует ряд отличных ресурсов посвященных Linux. «Linux Documentation Project» (LDP) — это группа добровольцев, которые занимаются составлением полного набора свободной документации по Linux. Данный проект существует чтобы собрать различные части документации по Linux в определенным месте, где её будет легко искать и использовать.

Обзор LDP

LDP состоит из следующих разделов:

• Guides (руководства) — большие, очень серьезные пособия, такие как The Linux Programmer’s Guide (Руководство программиста Linux)
• HOWTOs — помощь по конкретной теме, например DSL HOWTO
• FAQs — сборники ответов на часто задаваемые вопросы, навроде этого Brief Linux FAQ
• Man pages — помощь по конкретной команде (это те же самые маны, что вы видите в вашей системе, когда используете команду man).

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

LDP в добавок предоставляет доступ к списку ссылок и ресурсов, таких как Linux Gazette и Linux Weekly News, а также к спискам рассылки и архивам новостей.

Списки рассылки

Списки рассылки являются, вероятно, самым важным средством взаимодействия разработчиков Linux. Зачастую проекты разрабатываются участниками живущими на большом расстоянии друг от друга, возможно даже на противоположных сторонах земного шара. Списки рассылки представляют метод взаимодействия, в котором каждый разработчик проекта может связаться со всеми остальными и вместе дискутировать посредством электронной почты. Один из самых известных списков рассылки разработчиков, это Linux Kernel Mailing List (список рассылки ядра Linux).

Еще о списках рассылки

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

Если вы уделили время чтобы прочитать LKML FAQ по ссылке выше, то возможно заметили, что подписчики на списки рассылок часто недружелюбно относятся к вопросам, которые часто повторяются. Всегда разумно поискать в архивах рассылки перед тем, как задавать свой вопрос. Есть шансы, что это сэкономит и ваше время тоже!

Группы новостей

Новостные группы (англ. newsgroups) в интернете похожи на списки рассылки, но основаны на другом протоколе, который называется NNTP (Network News Transfer Protocol, что в переводе «Сетевой протокол передачи новостей»), а не на обмене электронной почтой. Чтобы иметь возможность общаться, вам придется установить NTTP-клиент, например slrn или pan. Основным преимуществом является тот факт, что вы можете принять участие в дискуссии, когда вам это нужно, а не постоянно смотреть как она ломится в ваш почтовый ящик

Сайты поставщиков и прочие

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

• Redhat Linux
• Debian Linux
• Gentoo Linux
• SuSE Linux
• Caldera
• Turbolinux

Поставщики аппаратного и программного обеспечения

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

• IBM и Linux
• HP и Linux
• Sun и Linux
• Oracle и Linux.

Перевод выполнил коллективный разум с помощью notabenoid.com. Спасибо хабравчанам (в алф. порядке): DMinsky, habrrich и kindacute (на хабре?). Их карма заслуживает плюсов. Если кого не упомянул, напишите в личку или в комментариях.

Продолжение…

Об авторах

Daniel Robbins

Дэниэль Роббинс — основатель сообщества Gentoo и создатель операционной системы Gentoo Linux. Дэниэль проживает в Нью-Мехико со свой женой Мэри и двумя энергичными дочерьми. Он также основатель и глава Funtoo, написал множество технических статей для IBM developerWorks, Intel Developer Services и C/C++ Users Journal.

Chris Houser

Крис Хаусер был сторонником UNIX c 1994 года, когда присоединился к команде администраторов университета Тэйлора (Индиана, США), где получил степень бакалавра в компьютерных науках и математике. После он работал во множестве областей, включая веб-приложения, редактирование видео, драйвера для UNIX и криптографическую защиту. В настоящий момент работает в Sentry Data Systems. Крис также сделал вклад во множество свободных проектов, таких как Gentoo Linux и Clojure, стал соавтором книги The Joy of Clojure.

Aron Griffis

Эйрон Гриффис живет на территории Бостона, где провел последнее десятилетие работая в Hewlett-Packard над такими проектами, как сетевые UNIX-драйвера для Tru64, сертификация безопасности Linux, Xen и KVM виртуализация, и самое последнее — платформа HP ePrint. В свободное от программирования время Эйрон предпочитает размыщлять над проблемами программирования катаясь на своем велосипеде, жонглируя битами, или болея за бостонскую профессиональную бейсбольную команду «Красные Носки».

Фундаментальные основы Linux. Часть II: Первые шаги в изучении интерфейса командной строки

Оригинал:

Linux Fundamentals

Автор: Paul Cobbaut

Дата публикации: 16 октября 2014 г.

Перевод: А.Панин

Дата перевода: 11 декабря 2014 г.

В данной главе описывается методика использования man-страниц (также называемых страницами руководств) при работе с вашим компьютером под управлением Unix или Linux.

Вы узнаете о том, как использовать команду man, а также такие связанные с ней команды, как whereis, whatis и mandb.

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

Команда man $команда

paul@laika:~$ man whois
Форматирование страницы whois(1), подождите...

Команда man $имя_файла_конфигурации

paul@laika:~$ man syslog.conf
Форматирование страницы syslog.conf(5), подождите...

Команда man $демон

paul@laika:~$ man syslogd
Форматирование страницы syslogd(8), подождите...

Команда man -k (apropos)

paul@laika:~$ man -k syslog
lm-syslog-setup (8)  - configure laptop mode to switch syslog.conf ...
logger (1)           - a shell command interface to the syslog(3) ...
syslog-facility (8)  - Setup and remove LOCALx facility for sysklogd
syslog.conf (5)      - syslogd(8) configuration file
syslogd (8)          - Linux system logging utilities.
syslogd-listfiles (8) - list system logfiles

Команда whatis

paul@u810:~$ whatis route
route (8)            - show / manipulate the IP routing table

Команда whereis

paul@laika:~$ whereis -m whois
whois: /usr/share/man/man1/whois.1.gz

paul@laika:~$ man /usr/share/man/man1/whois.1.gz

Номера справочных разделов

1 Исполняемые программы или команды оболочки (shell) 
2 Системные вызовы (функции, предоставляемые ядром) 
3 Библиотечные вызовы (функции, предоставляемые программными библиотеками) 
4 Специальные файлы (обычно находящиеся в каталоге /dev) 
5 Форматы файлов и соглашения, например о /etc/passwd 
6 Игры 
7 Разное (включает пакеты макросов и соглашения), например man(7), groff(7) 
8 Команды администрирования системы (обычно, запускаемые только суперпользователем) 
9 Процедуры ядра [нестандартный раздел]

Команда man $раздел $файл

[paul@RHEL52 ~]$ man passwd      # открывает первую найденную страницу руководства
[paul@RHEL52 ~]$ man 5 passwd    # открывает страницу руководства из раздела 5

Команда man man

Если вы желаете узнать больше о команде man, прочитайте это замечательное руководство (Read The Fantastic Manual — RTFM).

paul@laika:~$ man woman
Нет справочной страницы для woman

Утилита mandb

root@laika:~# mandb
В 0 man-подкаталогах содержатся более новые справочные страницы. 
Добавлено 0 справочных страниц. 
Добавлено 0 побочных cat-страниц. 
Вычищено 0 старых записей базы данных.

[root@centos65 ~]# apropos scsi
scsi: ничего подходящего не найдено.
[root@centos65 ~]# makewhatis 
[root@centos65 ~]# apropos scsi
hpsa                 (4)  - HP Smart Array SCSI driver
lsscsi               (8)  - list SCSI devices (or hosts) and their attributes
sd                   (4)  - Driver for SCSI Disk Drives
st                   (4)  - SCSI tape device

Состояние перевода: На этой странице представлен перевод статьи man page. Дата последней синхронизации: 14 октября 2021. Вы можете помочь синхронизировать перевод, если в английской версии произошли изменения.

man-страницы (от англ. manual — руководство) — справочные страницы, которые предоставляются почти всеми *nix-дистрибутивами, включая Arch Linux. Для их отображения служит команда man.

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

Установка

man-db реализует man в Arch Linux, а less является просмотрщиком по умолчанию. Также можно использовать mandoc.

man-pages предоставляет руководства Linux.

Русский перевод доступен в man-pages-ru.

Можно использовать приложения для просмотра руководств:

• GNOME Help — Просмотрщик справки для GNOME. Он позволяет смотреть man-страницы через yelp man:<name> или недокументированным сочетанием клавиш Ctrl+L в существующем окне.

https://wiki.gnome.org/Apps/Yelp || yelp

• KHelpCenter — Приложения для документации KDE Applications. Man-страницы доступны в UNIX manual pages или при запуске khelpcenter man:<name>.

https://userbase.kde.org/KHelpCenter || khelpcenter

• Konqueror — Файловый менеджер KDE и веб-браузер. Он может отображать man-страницы через man:<name>.

https://konqueror.org/ || konqueror

• xman — Обеспечивает просмотр man-страниц по категориям.

https://xorg.freedesktop.org/ || xorg-xman

Доступ к man-страницам

Чтобы отобразить man-страницу, наберите

$ man имя_страницы

Страницы разделены на несколько разделов. Полный список разделов смотрите в man-pages(7).

На man-страницы принято ссылаться по имени, с указанием номера раздела в скобках. Часто существуют сразу несколько man-страниц с одинаковыми именами, но в разных категориях, например man(1) и man(7). В таком случае, команде man необходимо передать номер конкретного раздела перед именем man-страницы, например:

$ man 5 passwd

отобразит man-страницу по файлу /etc/passwd вместо утилиты passwd.

Или можно указать номер раздела после названия страницы, отделив его точкой:

$ man passwd.5

Поиск по страницам

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

$ man -k выражение
$ man --apropos выражение
$ apropos выражение

выражение по умолчанию интерпретируется как регулярное выражение.

Если вы хотите произвести более углубленный поиск по всему содержимому страниц, используйте опцию -K:

$ man -K password

Примечание: Возможность поиска реализауется отдельным кэшем. Он обновляется автоматически службой man-db.service, которую периодически запускает man-db.timer. Если вы получаете сообщение «ничего подходящего не найдено» для любого поискового запроса, попробуйте вручную обновить кэш, запустив команду mandb как root.

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

$ whatis ls

ls (1p)              - list directory contents
ls (1)               - list directory contents

Ширина страницы

Ширина man-страниц регулируется переменной окружения MANWIDTH.

Если ширина терминала слишком маленькая, переносы строк могут сломаться, что затруднит чтение. Можно исправить это установкой значения MANWIDTH при запуске man. В bash это можно сделать примерно так:

~/.bashrc

man() {
    local width=$(tput cols)
    [ $width -gt $MANWIDTH ] && width=$MANWIDTH
    env MANWIDTH=$width 
    man "$@"
}

Просмотр локальных страниц

Кроме утилиты man, для чтения man-страниц вы также можете использовать веб-браузер, например lynx или Firefox. Просмотр страниц в браузере позволяет воспользоваться основным преимуществом info-страниц — гиперссылками.

Конвертирование страниц в HTML

mandoc

Установите пакет mandoc. Чтобы конвертировать страницу, для примера, free(1), наберите:

$ mandoc -Thtml -Ostyle=style.css /usr/share/man/man1/free.1.gz > free.html

Получившийся файл free.html теперь можно открыть в любом веб-браузере.

man2html

Установите man2html из официальных репозиториев.

Сконвертируйте страницу командой:

$ man free | man2html -compress -cgiurl man$section/$title.$section$subsection.html > ~/man/free.html

Другая полезная функция man2html — экспорт в обычный текстовый файл, который можно распечатать:

$ man free | man2html -bare > ~/free.txt

man -H

Реализация утилиты man от GNU, также позволяет открыть страницу в веб-браузере:

$ man -H free

Команда запустит браузер, установленный в переменной окружения BROWSER. Вы можете указать браузер явно, передав путь до исполняемого файла сразу после опции -H.

roffit

Установите пакет roffit^AUR.

Для конвертирования страницы выполните:

$ gunzip -c /usr/share/man/man1/free.1.gz | roffit > free.html

Конвертирование в PDF

Man-страницы всегда были удобны для печати: они написаны в формате troff, который является типографским языком. Таким образом вы можете легко сконвертировать man-страницы в любой из форматов, который поддерживается в groff, который используется в man-db. Чтобы узнать список доступных устройств вывода, смотрите опцию -T в groff(1) (или mandoc(1) если вы используете пакет mandoc).

Эта команда создаст PDF-файл:

$ man -Tpdf имястраницы > имяфайла

Обратите внимание, что шрифты главным образом ограничены набором Times и имеют жестко заданные размеры. Документ не будет содержать гиперссылок. Некоторые man-страницы форматировались так, чтобы выглядеть хорошо в терминале, однако могут отображаться некорректно в форме PostScript или PDF-документов.

Просмотр онлайн-страниц

Существуют множество онлайн-хранилищ man-страниц; вот небольшой список:

• Arch manual pages содержит man-страницы пакетов Arch Linux. Используется для ссылок на man-страницы в этой вики. Также можно использовать !archman DuckDuckGo bang для прямого поиска по man-страницам Arch.
• Man7.org. Первоисточник страниц для man-pages.
• manned.org — коллекция из разных дистрибутивов Linux, BSD и т.д. Множество версий пакетов.
• man-страницы на die.net
• man.cx
• man-страницы Debian GNU/Linux
• репозиторий man-страниц Ubuntu
• man-страницы DragonFlyBSD
• man-страницы FreeBSD Hypertext
• man-страницы NetBSD
• man-страницы OpenBSD
• Руководство Plan 9 — Том 1
• Руководство Inferno — Том 1
• man-страницы форума The UNIX and Linux Forums

Также есть сравнительная таблица.

Важно: Некоторые дистрибутивы Linux предоставляют исправленные или устаревшие man-страницы, которые могут отличаться от тех, которые поставляются с пакетами Arch Linux. Имейте это в виду, просматривая man-страницы онлайн.

Полезные страницы

Здесь приведен небольшой список полезных man-страниц, которые могут помочь вам получить более углубленные знания о множестве полезных вещей. Некоторые из них могут служить хорошими справочниками (например, таблица ASCII).

• ascii(7)
• boot(7)
• charsets(7)
• chmod(1)
• credentials(7)
• fstab(5)
• hier(7)
• systemd(1)
• locale(1p), locale(5), locale(7)
• printf(3)
• proc(5)
• regex(7)
• signal(7)
• term(5), term(7)
• termcap(5)
• terminfo(5)
• utf-8(7)

Вам могут быть интересны также и другие страницы седьмой категории:

$ man -s 7 -k ".*"

А также страницы, относящиеся непосредственно к Arch Linux:

• alpm-hooks(5)
• libalpm(3)
• makepkg(8)
• makepkg.conf(5)
• makepkg-template(1)
• mkinitcpio(8)
• pacman(8)
• pacman.conf(5)
• pacman-conf(8)
• pacman-key(8)

See also

• Gentoo:man page
• Write The Fine Manual with pod2man
• History of UNIX Manpages

Хотите, чтобы ваша новая программа для Linux выглядела профессионально? Дайте ему страницу руководства. Мы покажем вам самый простой и быстрый способ сделать это.

Страницы руководства

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

Предоставление страницы руководства для написанной вами утилиты или команды поднимает ее из полезного фрагмента кода в полностью сформированный пакет Linux. Люди ожидают, что для программы, написанной для Linux, будет предоставлена ​​справочная страница. Если вы изначально поддерживаете Linux, страница руководства обязательна, если вы хотите, чтобы к вашей программе относились серьезно.

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

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

Вам следует сконцентрироваться на своем контенте, а не бороться с неясным набором макросов.

pandoc спешит на помощь

В программа pandoc читает файлы разметки и генерирует новые примерно на 40 различных языках разметки и форматах документов, включая страницу руководства. Он полностью меняет процесс написания страниц руководства, так что вам не придется ломать голову над иероглифами.

Для начала вы можете установить pandoc в Ubuntu с помощью этой команды:

sudo apt-get install pandoc

В Fedora вам понадобится следующая команда:

sudo dnf install pandoc

На Манджаро введите:

sudo pacman -Syu pandoc

Разделы мужской страницы

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

Как минимум, большинство страниц руководства содержат следующие разделы:

Имя: имя команды и краткое однострочное описание ее функции.
Сводка: краткое описание вызовов, которые кто-то может использовать для запуска программы. Они показывают типы допустимых параметров командной строки.
Описание: описание команды или функции.
Параметры: список параметров командной строки и их назначение.
Примеры: несколько примеров общего использования.
Значения выхода: возможные коды возврата и их значения.
Ошибки: список известных ошибок и причуд. Иногда это дополняется (или заменяется) ссылкой на систему отслеживания проблем для проекта.
Автор: человек или люди, написавшие команду.
Авторские права: Ваше сообщение об авторских правах. Они также обычно включают тип лицензии, под которой выпущена программа.

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

Вот некоторые другие разделы, которые вы будете видеть достаточно часто:

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

Разделы руководства

Руководство по Linux состоит из всех страниц руководства, которые затем разбиты на пронумерованные разделы:

Исполняемые программы: или команды оболочки.
Системные вызовы: функции, предоставляемые ядром.
Вызовы библиотеки: функции в библиотеках программ.
Специальные файлы.
Форматы файлов и соглашения: например, «/ etc / passwd».
Игры.
Разное: пакеты макросов и соглашения, такие как groff.
Команды системного администрирования: обычно зарезервированы для root.
Процедуры ядра: обычно не устанавливаются по умолчанию.

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

Формат страницы руководства

Макроформат groff непросто разобрать визуально. Напротив, уценка — это легкий ветерок.

Ниже приведена справочная страница в groff.

Эта же страница показана ниже в уценке.

Передняя Материя

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

Первая строка: содержит имя команды, за которой следует раздел руководства в круглых скобках без пробелов. Имя становится левым и правым разделами заголовка страницы руководства. По соглашению, имя команды пишется в верхнем регистре, хотя вы найдете много таких, которые этого не делают. Все, что следует за именем команды и номером раздела руководства, становится левым разделом нижнего колонтитула. Это удобно использовать для номера версии программного обеспечения.
Вторая строка: имя (имена) автора (ов). Они отображаются в автоматически созданном разделе авторов на странице руководства. Вам не нужно добавлять раздел «Авторы» — просто укажите здесь хотя бы одно имя.
Третья строка: дата, которая также становится центральной частью нижнего колонтитула.

имя

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

Раздел имени содержит быстрый однострочный текст, который включает имя команды, пробел, дефис (-), пробел, а затем очень краткое описание того, что делает команда.

Синопсис

Синопсис содержит различные форматы, которые может принимать командная строка. Эта команда может принимать шаблон поиска или параметр командной строки. Две звездочки (**) по обе стороны от имени команды означают, что имя будет отображаться жирным шрифтом на странице руководства. Одиночная звездочка

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

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

Раздел описания страницы руководства в разметке.

Описание объясняет, что делает команда или программа. Он должен кратко освещать важные детали. Помните, вы не пишете руководство пользователя.

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

Раздел параметров на странице руководства в markdown.

Раздел параметров содержит описание любых параметров командной строки, которые можно использовать с командой. По соглашению они выделены жирным шрифтом, поэтому перед ними и после них стоит поставить две звездочки (**). Включите текстовое описание параметров в следующую строку и начните его с двоеточия (:), за которым следует пробел.

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

Раздел примеров на странице руководства в markdown.

Раздел примеров содержит выбор различных форматов командной строки. Обратите внимание, что мы начинаем строки описания с двоеточия (:), как и в разделе параметров.

Выйти из раздела значений на странице руководства в markdown.

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

Раздел с ошибками на странице руководства в разметке.

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

Раздел авторских прав на странице руководства в markdown.

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

Эффективный рабочий процесс

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

pandoc ms.1.md -s -t man | /usr/bin/man -l -

pandoc ms.1.md -s -t человек | / usr / bin / man -l — в окне терминала.

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

Эта команда также вызывает pandoc в файле уценки (здесь он называется «ms.1.md»):
Параметр -s (автономный) создает полную страницу руководства сверху вниз, а не просто текст в формате man.

Параметр -t (тип вывода) с оператором «man» указывает pandoc генерировать вывод в формате man. Мы не сказали pandoc отправлять свой вывод в файл, поэтому он будет отправлен в stdout.

Мы также передаем этот вывод в man с параметром -l (локальный файл). Он говорит man не искать в базе данных man страницу руководства. Вместо этого он должен открыть указанный файл. Если имя файла -, man будет вводить данные со стандартного ввода.

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

Создание вашей мужской страницы

pandoc ms.1.md -s -t man -o ms.1

pandoc ms.1.md -s -t man -o ms.1 в окне терминала.

Это соответствует соглашению о присвоении имени странице руководства после описываемой команды и добавлению номера раздела руководства, как если бы это было расширение файла.

manpath

manpath в окне терминала.

Результаты дают нам следующую информацию:
/ usr / share / man: расположение стандартной библиотеки страниц руководства. Мы не добавляем страницы в эту библиотеку.
/ usr / local / share / man: эта символическая ссылка указывает на «/ usr / local / man».

/ usr / local / man: Здесь нам нужно разместить нашу новую страницу руководства.

Обратите внимание, что различные разделы руководства содержатся в своих собственных каталогах: man1, man2, man3 и так далее. Если каталог для раздела не существует, нам нужно его создать.

sudo mkdir /usr/local/man/man1

Для этого мы набираем следующее:

sudo cp ms.1 /usr/local/man/man1

Затем мы копируем файл «ms.1» в правильный каталог: man ожидает, что страницы руководства будут сжаты, поэтому мы будем использовать gzipсжать это

sudo gzip /usr/local/man/man1/ms.1

:

sudo mandb

sudo mkdir / usr / local / man / man1 в окне терминала.

man ms

man ms в окне терминала.

верхний раздел новой страницы руководства.

средний раздел новой страницы руководства.

Нижний раздел новой страницы руководства.

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

Если хотите . . .