Как да създадете страница на човек в Linux

Искате новата ви програма за Linux да изглежда професионално? Дайте му страница на човек. Ще ви покажем най-лесния и бърз начин да го направите.

Страниците на човека

Има ядро ​​истина в старата шега за Unix, „the само команда, от която се нуждаете да знаеш е човек.“ Man страниците съдържат изобилие от знания и те трябва да са първото място, което обръщате, когато искате да научите за дадена команда.

Предоставянето на man страница за помощна програма или команда, която сте написали, я издига от полезен код до напълно оформен Linux пакет. Хората очакват да бъде предоставена man страница за програма, която е написана за Linux. Ако първоначално поддържате Linux, man страница е задължителна, ако искате програмата ви да бъде взета сериозно.

Исторически страниците на man са били написани с помощта на набор от макроси за форматиране. Когато призовавате човек да отвори страница, той вика groff към прочетете файла и генерирайте форматиран изход, според макросите във файла. Изходът се прехвърля в по-малко и след това показан за вас.

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

Трябва да се концентрирате върху съдържанието си, а не да се борите с неясен набор от макроси.

пандок за спасяване

В програма pandoc чете файлове за маркиране и генерира нови на около 40 различни езика за маркиране и формати на документи, включително този на страницата на ръководството. Той напълно трансформира процеса на писане на man страница, така че не е нужно да се борите с йероглифи.

За да започнете, можете да инсталирате pandoc на Ubuntu с тази команда:

sudo apt-get install pandoc

Във Fedora командата, от която се нуждаете, е следната:

sudo dnf install pandoc

На Manjaro напишете:

sudo pacman -Syu pandoc

Раздели на страница с мъж

man страниците съдържат секции, които следват стандартна конвенция за именуване. Секциите, от които се нуждае вашата man страница, са продиктувани от сложността на командата, която описвате.

Най-малкото повечето страници на man съдържат следните секции:

Име: Името на командата и съдържателен едноред, който описва нейната функция.
Синопсис: Кратко описание на извикванията, които някой може да използва, за да стартира програмата. Те показват типовете приети параметри на командния ред.
Описание: Описание на командата или функцията.
Опции: Списък с опции на командния ред и какво правят.
Примери: Някои примери за обичайна употреба.
Изходни стойности: възможните кодове за връщане и техните значения.
Бъгове: Списък с известни грешки и странности. Понякога това се допълва с (или се заменя с) връзка към проследяващия проблем за проекта.
Автор: Човекът или хората, които са написали командата.
Авторско право: Вашето съобщение за авторски права. Те обикновено включват и вида на лиценза, под който се пуска програмата.

Ако прегледате някои от по-сложните man страници, ще видите, че има и много други секции. Например опитайте мъж мъж. Не е нужно обаче да ги включвате всички — само тези, от които наистина се нуждаете. man страниците не са място за многословие.

Някои други раздели, които ще виждате доста често, са:

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

Раздели от ръководството

Ръководството за Linux се състои от всички man страници, които след това се разделят на тези номерирани секции:

Изпълними програми: Или команди на обвивката.
Системни извиквания: Функции, предоставени от ядрото.
Извиквания на библиотека: Функции в програмните библиотеки.
Специални файлове.
Файлови формати и конвенции: Например „/etc/passwd“.
игри.
Разни: Макро пакети и конвенции, като groff.
Команди за системно администриране: Обикновено са запазени за root.
Подпрограми на ядрото: Обикновено не се инсталира по подразбиране.

Всяка man страница трябва да посочи към кой раздел принадлежи и също така трябва да се съхранява на подходящото място за този раздел, както ще видим по-нататък. Man страниците за команди и помощни програми принадлежат към първия раздел.

Форматът на страницата на човек

Макроформатът groff не е лесен за визуален анализ. За разлика от това, уценяването е лесно.

По-долу има страница на man в groff.

Същата страница е показана по-долу в маркировката.

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

Първите три реда образуват нещо, наречено предна материя. Всички те трябва да започват със знак за процент (%), без водещи интервали, а едно след това, последвано от:

Първият ред: Съдържа името на командата, последвано от ръчния раздел в скоби, без интервали. Името се превръща в лявата и дясната част на заглавката на страницата на ръководството. По конвенция името на командата е с главни букви, въпреки че ще намерите много, които не са. Всичко, което следва името на командата и номера на ръчната секция, става лявата част на долния колонтитул. Удобно е да използвате това за номера на версията на софтуера.
Вторият ред: Името(ата) на автора(ите). Те се показват в автоматично генериран раздел за автори на страницата на ръководството. Не е нужно да добавяте раздел „Автори“ – просто включете поне едно име тук.
Трети ред: Датата, която също става централна част на долния колонтитул.

име

Секциите са обозначени с редове, които започват със знак за цифра (#), което е маркировка, която показва заглавка в markdown. Знакът за число (#) трябва да бъде първият знак на реда, последван от интервал.

Секцията за име съдържа бърз едноред, който включва името на командата, интервал, тире (-), интервал и след това много кратко описание на това, което прави командата.

Синопсис

Синопсисът съдържа различните формати, които командният ред може да приеме. Тази команда може да приеме шаблон за търсене или опция от командния ред. Двете звездички (**) от двете страни на името на командата означават, че името ще бъде показано в удебелен шрифт на страницата на ръководството. Една звездичка

от двете страни на някакъв текст кара man страницата да го показва подчертано.

По подразбиране прекъсването на ред е последвано от празен ред. За да наложите твърдо прекъсване без празен ред, можете да използвате обратна наклонена черта ().

Описание

Описанието обяснява какво прави командата или програмата. Тя трябва да обхваща накратко важните детайли. Не забравяйте, че не пишете ръководство за потребителя.

Използването на два числови знака (##) в началото на ред създава заглавие от второ ниво. Можете да ги използвате, за да разбиете описанието си на по-малки парчета.

Настроики

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

Ако описанието е достатъчно кратко, man ще го покаже на същия ред като опцията от командния ред. Ако е твърде дълъг, се показва като абзац с отстъп, който започва на реда под опцията на командния ред.

Примери

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

Изходни стойности

Този раздел изброява върнатите стойности, които вашата команда изпраща обратно към процеса на извикване. Това може да е обвивката, ако я извикате от командния ред, или скрипт, ако сте я стартирали от шел скрипт. Започваме описателните редове с двоеточие (:) и в този раздел.

Бъгове

Разделът за грешки изброява известни грешки, проблеми или странности, за които хората трябва да знаят. За проекти с отворен код е обичайно тук да се включва връзка към инструмента за проследяване на проблеми на проекта, за да се провери състоянието на всички грешки или да се докладват за нови.

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

Разделът за авторски права съдържа вашата декларация за авторски права и обикновено описание на типа лиценз, под който се издава софтуерът.

Ефективен работен поток

Можете да редактирате вашата man страница в любимия си редактор. Повечето, които поддържат подчертаване на синтаксиса, ще са наясно с намалението и ще оцветят текста, за да подчертаят заглавията, както и ще го удебеляват и подчертават. Това е страхотно, доколкото се отнася, но вие не гледате изобразена man страница, което е истинското доказателство в пудинга.

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

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

След като използвате тази команда, можете да натиснете стрелката нагоре, за да я повторите, и след това да натиснете Enter.

Тази команда също извиква pandoc във файла за уценяване (тук се нарича „ms.1.md“):
Опцията -s (самостоятелна) генерира пълна man страница отгоре до долу, а не само някакъв текст във формат man.

Опцията -t (тип изход) с оператора “man” казва на pandoc да генерира своя изход във формат man. Не сме казали на pandoc да изпрати своя изход във файл, така че той ще бъде изпратен до stdout.

Ние също така изпращаме този изход в man с опцията -l (локален файл). Той казва на човека да не търси в базата данни на man, търсейки man страницата. Вместо това трябва да отвори наименувания файл. Ако името на файла е -, man ще вземе входа му от stdin.

Това се свежда до това, че можете да запишете от вашия редактор и да натиснете Q, за да затворите man, ако работи в прозореца на терминала. След това можете да натиснете стрелката нагоре, последвано от Enter, за да видите изобразена версия на вашата man страница, точно в man.

Създаване на вашата man страница

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

След като завършите вашата man страница, трябва да създадете окончателна версия и след това да я инсталирате на вашата система. Следната команда казва на pandoc да генерира man страница, наречена „ms.1“:

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

manpath

Това създава файл „ms.1“, който е нашата нова страница на ръководството. Къде да го поставим? Тази команда ще ни каже къде man търси man страници:

Резултатите ни дават следната информация:
/usr/share/man: Местоположението на стандартната библиотека от man страници. Ние не добавяме страници към тази библиотека.
/usr/local/share/man: Тази символична връзка сочи към „/usr/local/man.“

/usr/local/man: Това е мястото, където трябва да поставим нашата нова 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 ms

Това е! Вече можем да извикаме нашата нова man страница по същия начин като всяка друга, като напишем:

Нашата нова man страница е намерена и показана.

Изглежда точно като всяка друга man страница, с удебелен, подчертан и отстъпен текст на подходящите места.

Редове с описание, които пасват до опцията, която описват, се появяват на същия ред. Редове, които са твърде дълги, за да се поберат, се показват под опцията, която описват.

Също така автоматично генерирахме раздел „Автори“. Долен колонтитулът включва също номера на версията на софтуера, датата и името на командата, както е дефинирано в предната част.

Ако искаш . . .