Како направити ман страницу на Линук-у

Желите да ваш нови Линук програм изгледа професионално? Дајте му ман страницу. Показаћемо вам најлакши и најбржи начин да то урадите.

Тхе ман Пагес

Постоји зрно истине у старој Уник шали, „тхе само наредба која вам је потребна знати је човек.” Ман странице садрже богато знање и оне би требало да буду прво место на које се окрећете када желите да научите о команди.

Обезбеђивање ман странице за услужни програм или команду коју сте написали подиже га од корисног дела кода до потпуно формираног Линук пакета. Људи очекују да се обезбеди ман страница за програм који је написан за Линук. Ако изворно подржавате Линук, ман страница је обавезна ако желите да се ваш програм схвати озбиљно.

Историјски гледано, ман странице су писане коришћењем скупа макроа за форматирање. Када позовете човека да отвори страницу, он позива Гроффа на прочитајте датотеку и генеришите форматирани излаз, према макроима у датотеци. Излаз се преноси у мање, а затим приказано за вас.

Осим ако често правите ман странице, писање једне и ручно уметање макроа је тежак посао. Чин креирања ман странице која правилно анализира и изгледа исправно може надмашити ваш циљ да пружите сажет, а ипак детаљан опис ваше команде.

Требало би да се концентришете на свој садржај, а не да се борите са нејасним скупом макроа.

пандоц то тхе Ресцуе

Тхе пандоц програм чита маркдовн датотеке и генерише нове на око 40 различитих језика за означавање и формата докумената, укључујући онај на страници ман. Потпуно трансформише процес писања ман странице тако да не морате да се борите са хијероглифима.

Да бисте започели, можете да инсталирате пандоц на Убунту помоћу ове команде:

sudo apt-get install pandoc

На Федора-и, команда која вам је потребна је следећа:

sudo dnf install pandoc

На Мањаро укуцајте:

sudo pacman -Syu pandoc

Одељци странице човека

ман странице садрже одељке који прате стандардну конвенцију именовања. Одељци који су потребни вашој ман страници су диктирани софистицираношћу команде коју описујете.

У најмању руку, већина ман страница садржи ове одељке:

Име: Име команде и језгровит једноструки ред који описује њену функцију.
Синопсис: Кратак опис позивања које неко може користити за покретање програма. Они показују типове прихваћених параметара командне линије.
Опис: Опис команде или функције.
Опције: Листа опција командне линије и шта оне раде.
Примери: Неки примери уобичајене употребе.
Излазне вредности: Могући повратни кодови и њихова значења.
Грешке: Листа познатих грешака и недоумица. Понекад је ово допуњено (или замењено) везом до праћења проблема за пројекат.
Аутор: Особа или људи који су написали наредбу.
Ауторско право: Ваша порука о ауторским правима. Они такође обично укључују тип лиценце под којом се програм издаје.

Ако погледате неке од компликованијих ман страница, видећете да постоје и многи други одељци. На пример, покушајте човека човека. Међутим, не морате их све укључити — само оне које су вам заиста потребне. ман странице нису место за речи.

Неки други одељци које ћете видети прилично често су:

Такође погледајте: Друге команде које се односе на предмет који би неки сматрали корисним или релевантним.
Датотеке: Листа датотека укључених у пакет.
Упозорења: Остале тачке на које треба знати или пазити.
Историја: Историја промена за команду.

Делови приручника

Приручник за Линук се састоји од свих ман страница, који се затим дели на ове нумерисане одељке:

Извршни програми: Или команде љуске.
Системски позиви: Функције које обезбеђује кернел.
Позиви библиотеке: Функције унутар програмских библиотека.
Специјални фајлови.
Формати датотека и конвенције: На пример, „/етц/пассвд“.
Игре.
Разно: Макро пакети и конвенције, као што је грофф.
Команде системске администрације: Обично резервисане за роот.
Рутине кернела: Обично се не инсталирају подразумевано.

Свака ман страница мора да назначи ком одељку припада, а такође мора да буде ускладиштена на одговарајућој локацији за тај одељак, као што ћемо видети касније. Ман странице за команде и услужне програме припадају првом одељку.

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

Грофф макро формат није лако визуелно рашчланити. Насупрот томе, смањење је лако.

Испод је ман страница у грофф-у.

Иста страница је приказана испод у маркдовну.

Фронт Маттер

Прве три линије чине нешто што се зове предња материја. Сви они морају да почињу знаком процента (%), без водећих размака, већ једним после, након чега следи:

Први ред: Садржи назив команде, након чега следи ручни одељак у загради, без размака. Име постаје леви и десни део заглавља ман странице. По конвенцији, назив команде је написан великим словима, иако ћете наћи много оних који нису. Све што следи име команде и број ручног одељка постаје леви део подножја. Ово је згодно користити за број верзије софтвера.
Други ред: Име(на) аутора(а). Они су приказани у аутоматски генерисаном одељку за ауторе на страници ман. Не морате да додајете одељак „Аутори“ – само укључите бар једно име овде.
Трећи ред: Датум, који такође постаје средишњи део подножја.

Име

Делови су означени линијама које почињу са знаком броја (#), што је ознака која означава заглавље у маркдовну. Знак броја (#) мора бити први знак у реду, праћен размаком.

Одељак са именом садржи брзи једноструки ред који укључује име команде, размак, цртицу (-), размак, а затим и веома кратак опис онога што наредба ради.

Синопсис

Синопсис садржи различите формате које командна линија може да преузме. Ова команда може да прихвати образац претраге или опцију командне линије. Две звездице (**) са обе стране имена команде значе да ће име бити приказано подебљаним словима на страници упутства. Једна звездица

са обе стране неког текста доводи до тога да се страница ман приказује подвучено.

Подразумевано, после прелома реда следи празан ред. Да бисте наметнули тешки прекид без празне линије, можете користити обрнуту косу црту ().

Опис

Опис објашњава шта команда или програм ради. Требало би сажето да покрије важне детаље. Запамтите, не пишете упутство за употребу.

Коришћење два знака броја (##) на почетку реда ствара наслов другог нивоа. Можете их користити да разбијете свој опис на мање делове.

Опције

Одељак са опцијама садржи опис свих опција командне линије које се могу користити са командом. По договору, они су приказани подебљаним словима, тако да укључите две звездице (**) пре и после њих. Укључите текстуални опис опција у следећи ред и започните га двотачком (:), након чега следи размак.

Ако је опис довољно кратак, ман ће га приказати у истој линији као и опција командне линије. Ако је предугачак, приказује се као увучени пасус који почиње на линији испод опције командне линије.

Примери

Одељак са примерима садржи избор различитих формата командне линије. Имајте на уму да редове за опис почињемо двотачком (:), баш као што смо урадили одељак са опцијама.

Излазне вредности

Овај одељак наводи повратне вредности које ваша команда шаље назад процесу позива. Ово може бити љуска ако сте је позвали из командне линије или скрипта ако сте је покренули из схелл скрипте. Редове описа почињемо двотачком (:) иу овом одељку.

Бугс

Одељак о грешкама наводи познате грешке, недостатке или недостатке о којима људи треба да знају. За пројекте отвореног кода, уобичајено је да се овде укључи веза до алата за праћење проблема пројекта да бисте проверили статус грешака или пријавили нове.

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

Одељак о ауторским правима садржи вашу изјаву о ауторским правима и, обично, опис врсте лиценце под којом се софтвер издаје.

Ефикасан ток рада

Можете уредити своју ман страницу у свом омиљеном уређивачу. Већина оних који подржавају истицање синтаксе биће свесни смањења и боје текста да би истакли наслове, као и подебљано и подвучено. То је сјајно што се тиче, али не гледате приказану ман страницу, што је прави доказ у пудингу.

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

Отворите прозор терминала у директоријуму који садржи вашу маркдовн датотеку. Када је отворен у уређивачу, повремено чувајте датотеку на чврстом диску. Сваки пут када то урадите, можете извршити следећу команду у прозору терминала:

Када користите ову команду, можете да притиснете стрелицу нагоре да бисте је поновили, а затим притисните Ентер.

Ова команда такође позива пандоц на датотеку маркдовн (овде се зове „мс.1.мд“):
Опција -с (самостална) генерише комплетну ман страницу од врха до дна, а не само неки текст у ман формату.

Опција -т (тип излаза) са оператором „ман“ говори пандоц-у да генерише свој излаз у ман формату. Нисмо рекли пандоц-у да пошаље свој излаз у датотеку, тако да ће бити послат у стдоут.

Такође шаљемо тај излаз у ман са опцијом -л (локални фајл). Он говори човеку да не претражује ман базу података тражећи ман страницу. Уместо тога, требало би да отвори именовану датотеку. Ако је име датотеке -, ман ће узети њен унос из стдин-а.

Ово се своди на то да можете да сачувате из свог уређивача и притиснете К да затворите ман ако ради у прозору терминала. Затим можете притиснути стрелицу нагоре, а затим Ентер да бисте видели приказану верзију ваше ман странице, директно унутар ман.

Креирање ваше ман странице

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

Након што завршите своју ман страницу, потребно је да креирате њену коначну верзију, а затим да је инсталирате на свој систем. Следећа команда говори пандоц-у да генерише ман страницу под називом „мс.1“:

Ово прати конвенцију давања имена страници ман по команди коју описује и додавања броја ручног одељка као да је екстензија датотеке.

manpath

Ово креира датотеку „мс.1“, која је наша нова страна упутства. Где да га ставимо? Ова команда ће нам рећи где ман тражи ман странице:

Резултати нам дају следеће информације:
/уср/схаре/ман: Локација стандардне библиотеке ман страница. Не додајемо странице у ову библиотеку.
/уср/лоцал/схаре/ман: Ова симболична веза указује на „/уср/лоцал/ман.“

/уср/лоцал/ман: Овде треба да поставимо нашу нову ман страницу.

Имајте на уму да се различите ручне секције налазе у сопственим директоријумима: ман1, ман2, ман3, итд. Ако директоријум за одељак не постоји, морамо да га креирамо.

sudo mkdir /usr/local/man/man1

Да бисмо то урадили, откуцавамо следеће:

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

Затим копирамо датотеку „мс.1“ у исправан директоријум: ман очекује да се ман странице компримују, па ћемо користити гзипда га сабијем

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

:

sudo mandb

Да бисте натерали човека да дода нову датотеку у своју базу података, откуцајте следеће:

man ms

То је то! Сада можемо назвати нашу нову ман страницу исто као и било коју другу тако што ћемо укуцати:

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

Изгледа исто као и свака друга страна упутства, са подебљаним, подвученим и увученим текстом на одговарајућим местима.

Редови описа који се уклапају поред опције коју описују појављују се у истом реду. Линије које су предугачке да би се уклопиле појављују се испод опције коју описују.

Такође смо аутоматски генерисали одељак „Аутори“. Подножје такође укључује број верзије софтвера, датум и назив команде, као што је дефинисано у предњој страни.

Ако желиш да . . .