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

Прозорец на терминал на лаптоп с Linux.

Фатмавати Ахмад Заенури/Shutterstock



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

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

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





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

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



Реклама

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

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

СВЪРЗАНИ: Как да използвате командата man на Linux: Скрити тайни и основи



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

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

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

man

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

man

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

man

СВЪРЗАНИ: Как да използвате pandoc за конвертиране на файлове в командния ред на Linux

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

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

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

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

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

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

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

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

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

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

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

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

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

По-долу има страница на човек в |_+_|.

Горната част на man страница във формат groff.

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

Горната част на man страница във формат markdown.

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

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

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

име

Секциите са обозначени с редове, които започват със знак за число (|_+_|), което е маркировка, която указва заглавка в markdown. Числовият знак (|_+_| трябва да бъде първият знак на реда, последван от интервал.

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

Синопсис

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

Реклама

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

Описание

Секция с описание на страница с man в markdown.

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

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

Настроики

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

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

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

Примери

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

Разделът с примери съдържа селекция от различни формати на командния ред. Имайте предвид, че започваме редовете за описание с двоеточие (|_+_|), точно както направихме секцията с опции.

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

Изход от секцията със стойности на man страница в markdown.

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

Бъгове

Раздел за грешки на страница на man в markdown.

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

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

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

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

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

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

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

man

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

Реклама

Тази команда също извиква |_+_| във файла с намаление (тук се нарича ms.1.md):

  • |_+_| (самостоятелна) опция генерира завършено отгоре до долу |_+_| страница, а не просто някакъв текст в |_+_| формат.
  • |_+_| (тип изход) опция с оператора man казва |_+_| да генерира своя изход в |_+_| формат. Не сме казали |_+_| за да изпрати своя изход във файл, така че той ще бъде изпратен до |_+_|.

Ние също така предаваме този изход в |_+_| с |_+_| опция (локален файл). Казва |_+_| да не търси през |_+_| база данни търси |_+_| страница. Вместо това трябва да отвори наименувания файл. Ако името на файла е |_+_|, |_+_| ще вземе своя вход от |_+_|.

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

СВЪРЗАНИ: Какво представляват stdin, stdout и stderr в Linux?

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

След като завършите |_+_| страница, трябва да създадете нейна окончателна версия и след това да я инсталирате на вашата система. Следната команда казва |_+_| за генериране на |_+_| страница, наречена ms.1:

man

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

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

man

Резултатите ни дават следната информация:

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

Имайте предвид, че различните ръчни секции се съдържат в техните собствени директории: man1, man2, man3 и т.н. Ако директорията за секцията не съществува, трябва да я създадем.

За целта набираме следното:

man

След това копираме файла ms.1 в правилната директория:

man

|_+_| очаква |_+_| страници да бъдат компресирани, така че ще използваме |_+_| да го компресирате :

groff

За да направите |_+_| добавете новия файл към неговата база данни, въведете следното:

less

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

man

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

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

Изглежда точно като всеки друг |_+_| страница, с удебелен, подчертан и отстъпен текст на съответните места.

среден раздел на новата страница на ръководството.

Реклама

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

Долна секция на нова страница на ръководството.

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

Ако искаш . . .

Веднъж |_+_| създаде вашия |_+_| страница, можете също директно да редактирате файла в |_+_| макро формат, преди да го преместите в |_+_| директория на страницата и |_+_| то.

ПРОЧЕТЕТЕ СЛЕДВАЩО
  • › Функции срещу формули в Microsoft Excel: Каква е разликата?
  • › 5 уебсайта, които всеки потребител на Linux трябва да направи отметка
  • › Какво представлява MIL-SPEC защита от изпускане?
  • › Компютърната папка е 40: Как Xerox Star създаде работния плот
  • & rsaquo; Кибер понеделник 2021: Най-добрите технологични сделки
  • › Как да намерите своя Spotify Wrapped 2021
Снимка на профила на Дейв Маккей Дейв Маккей
Дейв Маккей за първи път използва компютри, когато перфорираната хартиена лента беше на мода и оттогава той програмира. След повече от 30 години в ИТ индустрията, той вече е технологичен журналист на пълен работен ден. По време на кариерата си той е работил като програмист на свободна практика, мениджър на международен екип за разработка на софтуер, ръководител на проекти за ИТ услуги и, последно, като служител по защита на данните. Неговото писане е публикувано от howtogeek.com, cloudsavvyit.com, tenterpriser.com и opensource.com. Дейв е евангелист на Linux и привърженик на отворен код.
Прочетете пълната биография

Интересни Статии