Бажаєте, щоб ваш новий застосунок для Linux виглядав професійно? Додайте йому сторінку посібника! Ми покажемо вам найлегший і найшвидший спосіб це зробити.
Сторінки man
Існує старий жарт серед користувачів Unix, що “єдина команда, яку вам потрібно знати, це man“. І в цьому є зерно істини. Сторінки посібника містять величезну кількість інформації, і це має бути перше місце, куди ви звертаєтеся, коли хочете дізнатися про команду.
Надання сторінки посібника для утиліти або програми, яку ви написали, піднімає її статус від корисного фрагмента коду до повноцінного пакета Linux. Користувачі очікують наявності man-сторінки для будь-якої програми, розробленої для Linux. Якщо ви орієнтуєтеся на Linux, сторінка man є обов’язковою умовою, якщо ви хочете, щоб ваш програмний продукт сприймали серйозно.
Традиційно сторінки man створювалися з використанням набору макросів форматування. Коли ви запускаєте команду man для перегляду сторінки, вона викликає програму groff, яка обробляє файл і генерує відформатований вивід, відповідно до макросів у файлі. Цей вивід потім передається до less, де його можна переглянути.
Якщо ви не часто створюєте сторінки посібника, написання та ручне вставлення макросів може бути складним завданням. Створення сторінки man, яка правильно відображається і виглядає належним чином, може відволікти вас від вашої основної мети – надання стислого, але повного опису вашої команди.
Ваш фокус повинен бути на змісті, а не на боротьбі з незрозумілим набором макросів.
Pandoc на допомогу
Програма Pandoc може читати файли розмітки та генерувати нові приблизно в 40 різних форматах розмітки та документів, включаючи сторінки посібника. Це повністю змінює процес створення man-сторінки, позбавляючи вас від необхідності боротися з ієрогліфами.
Для початку, ви можете встановити pandoc на Ubuntu за допомогою цієї команди:
sudo apt-get install pandoc
У Fedora потрібна така команда:
sudo dnf install pandoc
На Manjaro введіть:
sudo pacman -Syu pandoc
Розділи сторінки посібника
Сторінки посібника містять розділи, які відповідають стандартній конвенції щодо імен. Розділи, необхідні вашій сторінці посібника, залежать від складності команди, яку ви описуєте.
Як мінімум, більшість сторінок посібника містять такі розділи:
Ім’я: ім’я команди та короткий однорядковий опис її функції.
Синопсис: короткий опис викликів, які можна використовувати для запуску програми. Він показує типи прийнятних параметрів командного рядка.
Опис: докладний опис команди або функції.
Параметри: перелік параметрів командного рядка та їхні функції.
Приклади: деякі типові приклади використання.
Значення виходу: можливі коди повернення та їхнє значення.
Помилки: список відомих помилок та особливостей. Іноді він доповнюється (або замінюється) посиланням на трекер проблем для проекту.
Автор: людина або група людей, які написали команду.
Авторське право: ваше повідомлення про авторське право. Воно також зазвичай включає тип ліцензії, за якою випускається програма.
Переглянувши деякі складніші сторінки посібника, ви побачите, що існують і багато інших розділів. Наприклад, спробуйте man man. Однак не обов’язково включати їх усі – лише ті, які вам дійсно потрібні. На сторінках посібника немає місця для багатослів’я.
Інші розділи, які ви досить часто зустрічатимете:
Дивіться також: інші команди, пов’язані з темою, які можуть бути корисними або доречними.
Файли: список файлів, що входять до пакету.
Застереження: інші моменти, про які слід знати або звернути на них увагу.
Історія: історія змін для команди.
Розділи посібника
Посібник Linux складається з усіх сторінок посібника, які потім розбиваються на пронумеровані розділи:
1. Виконувані програми: або команди оболонки.
2. Системні виклики: функції, що надаються ядром.
3. Виклики бібліотек: функції в програмних бібліотеках.
4. Спеціальні файли.
5. Формати файлів та умовні позначення: наприклад, “/etc/passwd”.
6. Ігри.
7. Різне: пакети макросів та умовні угоди, такі як groff.
8. Команди системного адміністрування: зазвичай зарезервовані для root.
9. Підпрограми ядра: зазвичай не встановлюються за замовчуванням.
Кожна сторінка 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-сторінка знайдена та відображена.
Вона виглядає так само, як і будь-яка інша сторінка посібника, з жирним, підкресленим і з відступом текстом у відповідних місцях.
Рядки опису, які поміщаються поруч з описуваним варіантом, з’являються в одному рядку. Занадто довгі рядки з’являються під описуваним варіантом.
Ми також автоматично створили розділ “Автори”. Нижній колонтитул також містить номер версії програмного забезпечення, дату та назву команди, як визначено у преамбулі.
Якщо ви бажаєте . . .
Після того, як pandoc створив вашу man-сторінку, ви також можете безпосередньо редагувати файл у форматі макросу groff, перш ніж перемістити його до каталогу сторінки man і заархівувати його.