Як створити сторінку людини в Linux

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

Сторінки людини

У старому жарті про Unix є ядро ​​правди «the тільки команда, яка вам потрібна Знати — це людина». Довідкові сторінки містять багато знань, і вони повинні бути першим місцем, куди ви звертаєтеся, коли хочете дізнатися про команду.

Надання сторінки керівництва для утиліти або команди, яку ви написали, підносить її від корисного фрагмента коду до повністю сформованого пакета Linux. Люди очікують, що для програми, яка була написана для Linux, буде надано сторінку керівництва. Якщо ви ізначально підтримуєте Linux, сторінка man є обов’язковою, якщо ви хочете, щоб вашу програму сприймали серйозно.

Історично сторінки man були написані з використанням набору макросів форматування. Коли ви закликаєте людину відкрити сторінку, вона кличе groff прочитати файл і створити відформатований вихід, відповідно до макросів у файлі. Вихід передається на менше, а потім відображається для вас.

Якщо ви часто не створюєте сторінки керівництва, написати її та вставити макроси вручну — важка робота. Створення сторінки man, яка правильно аналізує і виглядає правильно, може обігнати вашу мету надати стислий, але повний опис вашої команди.

Ви повинні зосередитися на своєму вмісті, а не боротися з незрозумілим набором макросів.

пандок на порятунок

The програма pandoc читає файли розмітки та генерує нові приблизно на 40 різних мовах розмітки та форматах документів, включаючи сторінку керівництва. Це повністю трансформує процес написання сторінки man, тому вам не доведеться боротися з ієрогліфами.

Щоб почати, ви можете встановити pandoc на Ubuntu за допомогою цієї команди:

sudo apt-get install pandoc

У Fedora потрібна така команда:

sudo dnf install pandoc

На Manjaro введіть:

sudo pacman -Syu pandoc

Розділи сторінки людини

Довідкові сторінки містять розділи, які відповідають стандартній конвенції щодо імен. Розділи, які потрібні вашій довідковій сторінці, продиктовані складністю команди, яку ви описуєте.

Як мінімум, більшість сторінок керівництва містять такі розділи:

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

Якщо ви переглянете деякі складніші сторінки керівництва, ви побачите, що також є багато інших розділів. Наприклад, спробуйте чоловіка. Однак не обов’язково включати їх усі — лише ті, які вам дійсно потрібні. На сторінках керівництва немає місця для багатослівності.

Деякі інші розділи, які ви будете бачити досить часто:

Дивіться також: Інші команди, пов’язані з темою, дехто вважає корисними або доречними.
Файли: список файлів, що входять до пакета.
Застереження: інші моменти, на які слід знати або звернути увагу.
Історія: історія змін для команди.

Розділи Посібника

Посібник Linux складається з усіх сторінок керівництва, який потім розбивається на такі пронумеровані розділи:

Виконувані програми: або команди оболонки.
Системні виклики: функції, що надаються ядром.
Виклики бібліотек: Функції в бібліотеках програм.
Спеціальні файли.
Формати файлів та умовні позначення: наприклад, “/etc/passwd”.
Ігри.
Різне: пакети макросів і умовні угоди, такі як groff.
Команди системного адміністрування: зазвичай зарезервовані для root.
Підпрограми ядра: зазвичай не встановлюються за замовчуванням.

Кожна man-сторінка має вказувати, до якого розділу вона належить, і вона також повинна зберігатися у відповідному місці для цього розділу, як ми побачимо пізніше. Довідкові сторінки для команд і утиліт належать до першого розділу.

Формат сторінки людини

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

Нижче наведена сторінка man в groff.

Та сама сторінка показана нижче в розмітці.

Передня справа

Перші три рядки утворюють щось, що називається передньою матерією. Усі вони мають починатися зі знака відсотка (%), без пробілів, але один після, а потім:

Перший рядок: Містить назву команди, а потім розділ посібника в дужках, без пробілів. Ім’я стає лівим і правим розділами заголовка сторінки керівництва. За умовою, назва команди пишеться у верхньому регістрі, хоча ви знайдете багато інших. Все, що слідує за назвою команди та номером розділу вручну, стає лівим розділом нижнього колонтитула. Це зручно використовувати для номера версії програмного забезпечення.
Другий рядок: ім’я (імена) автора(ів). Вони відображаються в автоматично згенерованому розділі авторів на сторінці посібника. Вам не потрібно додавати розділ «Автори» — просто вкажіть тут принаймні одне ім’я.
Третій рядок: дата, яка також стає центральною частиною нижнього колонтитула.

Ім’я

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

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

Синопсис

Конспект містить різні формати, які може приймати командний рядок. Ця команда може приймати шаблон пошуку або параметр командного рядка. Дві зірочки (**) по обидва боки від назви команди означають, що назва буде відображатися жирним шрифтом на сторінці керівництва. Єдина зірочка

по обидва боки від тексту, щоб сторінка довідника відображала його підкреслено.

За замовчуванням після розриву рядка йде порожній рядок. Щоб зробити жорсткий розрив без порожнього рядка, ви можете використовувати зворотну косу риску ().

Опис

Опис пояснює, що робить команда або програма. Він повинен коротко охоплювати важливі деталі. Пам’ятайте, що ви не пишете посібник користувача.

Використання двох цифрових знаків (##) на початку рядка створює заголовок другого рівня. Ви можете використовувати їх, щоб розбити свій опис на менші частини.

Параметри

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

Якщо опис досить короткий, man відобразить його в тому ж рядку, що й параметр командного рядка. Якщо він занадто довгий, він відображається як абзац з відступом, який починається з рядка під параметром командного рядка.

Приклади

Розділ прикладів містить добірку різних форматів командного рядка. Зверніть увагу, що ми починаємо рядки опису з двокрапки (:), так само, як ми робили розділ параметрів.

Вихідні значення

У цьому розділі наведено значення, які повертаються командою, що викликає процес. Це може бути оболонка, якщо ви викликали її з командного рядка, або сценарій, якщо ви запустили її зі сценарію оболонки. У цьому розділі ми також починаємо рядки опису з двокрапки (:).

помилки

У розділі про помилки наведено перелік відомих помилок, помилок або примх, про які потрібно знати людям. Для проектів із відкритим вихідним кодом зазвичай сюди можна включити посилання на засіб відстеження проблем проекту, щоб перевірити стан будь-яких помилок або повідомити про нові.

Авторське право

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

Ефективний робочий процес

Ви можете редагувати свою man-сторінку у своєму улюбленому редакторі. Більшість, які підтримують підсвічування синтаксису, будуть знати про розмітку та кольори тексту для виділення заголовків, а також виділяють жирним шрифтом і підкреслюють його. Це чудово, але ви не дивитеся на відтворену man-сторінку, яка є справжнім доказом у пудингу.

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

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

Використавши цю команду, можна натиснути стрілку вгору, щоб повторити її, а потім натиснути Enter.

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

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

Ми також передаємо цей вихід у man за допомогою параметра -l (локальний файл). Він говорить людині не шукати в базі даних man, шукаючи сторінку man. Замість цього він повинен відкрити названий файл. Якщо ім’я файлу -, man візьме вхідні дані зі стандартного входу.

Це зводиться до того, що ви можете зберегти зі свого редактора та натиснути Q, щоб закрити man, якщо він працює у вікні терміналу. Потім ви можете натиснути стрілку вгору, а потім Enter, щоб побачити відтворену версію вашої сторінки man, прямо всередині man.

Створення вашої сторінки людини

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

Після того, як ви завершили роботу зі своєю сторінкою man, вам потрібно створити її остаточну версію, а потім встановити її у вашій системі. Наступна команда наказує pandoc створити сторінку керівництва під назвою «ms.1»:

Це дотримується конвенції про іменування сторінки man за командою, яку вона описує, і додавання номера розділу посібника, як якщо б це було розширення файлу.

manpath

Це створює файл «ms.1», який є нашою новою сторінкою керівництва. Куди ми його покладемо? Ця команда вкаже нам, де man шукає сторінки керівництва:

Результати дають нам таку інформацію:
/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 очікує, що сторінки man будуть стиснуті, тому ми будемо використовувати gzipстиснути його

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

:

sudo mandb

Щоб змусити man додати новий файл до своєї бази даних, введіть наступне:

man ms

Це воно! Тепер ми можемо викликати нашу нову сторінку довідника так само, як і будь-яку іншу, ввівши:

Наша нова man-сторінка знайдена та відображена.

Вона виглядає так само, як і будь-яка інша сторінка керівництва, із жирним, підкресленим і з відступом текстом у відповідних місцях.

Рядки опису, які підходять поруч із описуваним варіантом, з’являються в одному рядку. Занадто довгі рядки з’являються під описуваним варіантом.

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

Якщо ти хочеш . . .