Желите ли да ваш нови Линукс програм изгледа професионално? Учините га доступним кроз ман страницу. У овом чланку ћемо показати најједноставнији и најбржи начин за то.
Ман Странице
Постоји доста истине у старој шали о Униксу: „Једина команда коју треба да знате је ‘man’.“ Ман странице садрже велику количину информација и требало би да буду прва ствар коју погледате када желите да сазнате више о некој команди.
Обезбеђивање ман странице за програм који сте написали подиже његов статус са корисног комада кода на комплетан Линукс пакет. Корисници очекују ман страницу за било који програм писан за Линукс. Ако ваш програм подржава Линукс, ман страница је неопходна да би га други озбиљно схватили.
Традиционално, ман странице су писане помоћу макроа за форматирање. Када покренете команду `man` да бисте видели страницу, она користи `groff` за читање датотеке и генерисање форматираног излаза, у складу са макроима у датотеци. Резултат се прослеђује `less`, a zatim се приказује.
Уколико не пишете често ман странице, ручно писање и уметање макроа може бити прилично компликовано. Процес креирања ман странице која се исправно приказује и анализира може затамнити ваш циљ да дате кратак, али исцрпан опис ваше команде.
Требало би да се фокусирате на садржај, а не да се борите са компликованим сетом макроа.
Pandoc у Помоћ
Pandoc програм чита Markdown датотеке и генерише нове у око 40 различитих формата, укључујући формат ман странице. Ово потпуно трансформише процес писања ман странице, елиминишући потребу да се борите са компликованим синтаксама.
Да бисте започели, инсталирајте Pandoc на Ubuntu помоћу следеће команде:
sudo apt-get install pandoc
На Fedora-и, користите ову команду:
sudo dnf install pandoc
На Manjaro-u, откуцајте:
sudo pacman -Syu pandoc
Одељци Ман Странице
Ман странице се састоје од одељака који следе стандардну конвенцију именовања. Који одељци су вам потребни зависи од сложености команде коју описујете.
Већина ман страница, у најмању руку, садржи следеће одељке:
Име: Назив команде и једноставан опис њене функције у једном реду.
Синопсис: Кратак опис како се команда позива, укључујући прихватљиве параметре.
Опис: Детаљан опис команде или функције.
Опције: Листа доступних опција командне линије и њихово значење.
Примери: Неколико примера уобичајене употребе.
Излазне вредности: Могући повратни кодови и њихово тумачење.
Грешке: Листа познатих грешака и ограничења. Може бити допуњена (или замењена) линком до система за праћење проблема пројекта.
Аутор: Особа или групе које су написале команду.
Ауторско право: Информације о ауторском праву и типу лиценце под којом је програм издат.
Ако погледате неке од сложенијих ман страница, видећете да постоји и много других одељака. На пример, погледајте `man man`. Међутим, не морате да укључите све — само оне које су релевантне за вашу команду. Ман странице нису место за дугачке објашњења.
Неки други одељци које често можете видети су:
Погледајте и: Листа других повезаних команди које би корисници могли сматрати корисним.
Датотеке: Листа датотека укључених у пакет.
Упозорења: Додатне информације на које треба обратити пажњу.
Историја: Запис промена за команду.
Одељци Приручника
Линукс приручник се састоји од свих ман страница, које су подељене на нумерисане одељке:
Извршни програми: Или команде љуске.
Системски позиви: Функције које обезбеђује кернел.
Позиви библиотека: Функције у програмским библиотекама.
Специјални фајлови.
Формати датотека и конвенције: На пример, „/etc/passwd“.
Игре.
Разно: Макро пакети и конвенције, попут грофф.
Команде системске администрације: Обично резервисане за роот корисника.
Рутине кернела: Обично нису подразумевано инсталиране.
Свака ман страница мора да наведе ком одељку припада и мора бити ускладиштена на одговарајућој локацији за тај одељак, као што ћемо видети касније. Ман странице за команде и алате припадају првом одељку.
Формат Ман Странице
Groff макро формат није једноставан за визуелно разумевање. Markdown, с друге стране, је прилично лак.
Испод је ман страница у Groff формату.
Иста страница је приказана испод у Markdown формату.
Уводни Део
Прве три линије чине уводни део. Све оне морају да почну знаком процента (%) без водећег размака, већ са једним размаком након процента, праћено са:
Први ред: Садржи назив команде, затим број приручника у заградама без размака. Назив постаје леви и десни део заглавља ман странице. По конвенцији, назив команде се пише великим словима, мада се то не дешава увек. Све што следи назив команде и број приручника постаје леви део подножја. Ово је згодно за чување броја верзије софтвера.
Други ред: Име(на) аутора(а). Они се приказују у аутоматски генерисаном одељку о ауторима на ман страници. Не морате да додате одељак „Аутори“ – само укључите бар једно име овде.
Трећи ред: Датум, који такође постаје средишњи део подножја.
Име
Одељци се означавају линијама које почињу знаком броја (#), који у Markdown-у означава заглавље. Знак броја (#) мора бити први знак у реду, праћен размаком.
Одељак за име садржи брзи опис у једном реду, који укључује назив команде, размак, цртицу (-), размак и кратак опис функције команде.
Синопсис
Одељак Синопсис приказује различите начине на које се команда може позвати. Команда може прихватити образац претраге или опцију командне линије. Две звездице (**) са обе стране имена команде означавају да ће име бити приказано подебљано на ман страници. Једна звездица са обе стране текста довешће до тога да се текст прикаже подвучен на ман страници.
Подразумевано, прелом реда је праћен празним редом. Да бисте наметнули прелом без празног реда, можете користити обрнуту косу црту (\).
Опис
Одељак Опис објашњава шта команда или програм ради. Требало би да сажето покрије важне детаље. Не пишете кориснички приручник.
Коришћење два знака броја (##) на почетку реда ствара наслов другог нивоа. Можете их користити да поделите опис на мање делове.
Опције
Одељак Опције садржи опис свих опција командне линије које се могу користити са командом. По конвенцији, оне су приказане подебљаним словима, па користите две звездице (**) пре и после њих. Текстуални опис опције ставите у следећи ред и почните га са двотачком (:), праћеном размаком.
Ако је опис довољно кратак, ман ће га приказати у истом реду као и опција командне линије. Ако је дугачак, приказује се као увучен пасус који почиње у реду испод опције.
Примери
Одељак Примери садржи избор различитих формата командне линије. Имајте на уму да редове за опис почињемо са двотачком (:), као што је то урађено у одељку Опције.
Излазне Вредности
Овај одељак наводи повратне вредности које команда враћа процесу који је позвао. То може бити љуска ако је команда позвана са командне линије или скрипта ако је позвана из скрипте. Редове са описима почињемо двотачком (:) и у овом одељку.
Грешке
Одељак Грешке наводи познате грешке, недостатке или ограничења на које корисници треба да обрате пажњу. За пројекте отвореног кода, уобичајено је да се овде укључи веза ка систему за праћење грешака пројекта, како би се проверио статус грешака или пријавиле нове.
Ауторско Право
Одељак о Ауторском Праву садржи вашу изјаву о ауторским правима и, обично, опис типа лиценце под којом је софтвер издат.
Ефикасан Радни Процес
Можете уређивати ман страницу у омиљеном уређивачу. Већина уређивача који подржавају истицање синтаксе ће бити свесни Markdown синтаксе и бојиће текст да би истакли наслове, као и подебљано и подвучено. Ово је корисно, али не видите како изгледа ман страница, што је најважније.
pandoc ms.1.md -s -t man | /usr/bin/man -l -
Отворите прозор терминала у директоријуму који садржи вашу Markdown датотеку. Када уређујете датотеку, повремено је сачувајте на диску. Сваки пут када то урадите, извршите следећу команду у прозору терминала:
Користећи ову команду, можете притиснути стрелицу нагоре да бисте је поновили, а затим притиснути Enter.
Ова команда позива Pandoc на вашу Markdown датотеку (у овом случају, `ms.1.md`).
Опција `-s` (standalone) генерише комплетну ман страницу од почетка до краја, а не само текст у ман формату.
Опција `-t` (тип излаза) са параметром `man` говори Pandoc-у да генерише излаз у ман формату. Нисмо рекли Pandoc-у да пошаље излаз у датотеку, па ће бити послат на `stdout`.
Излаз прослеђујемо команди `man` са опцијом `-l` (local file). Ово говори команди `man` да не претражује базу података ман страница. Уместо тога, требало би да отвори наведену датотеку. Ако је име датотеке -, команда `man` ће прихватити унос са `stdin`.
Ово значи да можете сачувати промене из уређивача и притиснути `q` да бисте затворили `man`, ако је отворен у прозору терминала. Затим можете притиснути стрелицу нагоре, а затим Enter да бисте видели приказану верзију ваше ман странице, директно у `man`.
Креирање Ваше Ман Странице
pandoc ms.1.md -s -t man -o ms.1
Када завршите ман страницу, треба да креирате њену финалну верзију и инсталирате је на ваш систем. Следећа команда говори Pandoc-у да генерише ман страницу под називом `ms.1`:
Ово прати конвенцију именовања ман страница према називу команде коју описује и додавање броја приручника као екстензију датотеке.
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` очекује да ман странице буду компримоване, па ћемо користити `gzip` да је компресујемо.
sudo gzip /usr/local/man/man1/ms.1
Да бисмо натерали `man` да дода нову датотеку у своју базу података, откуцајте:
sudo mandb
man ms
То је то! Сада можемо позвати нашу нову ман страницу као и било коју другу командом:
Наша нова ман страница је пронађена и приказана.
Изгледа исто као и свака друга ман страница, са подебљаним, подвученим и увученим текстом на одговарајућим местима.
Линије описа које се уклапају поред опције коју описују се појављују у истом реду. Линије које су предуге се појављују испод опције коју описују.
Аутоматски је генерисан одељак „Аутори“. Подножје такође укључује број верзије софтвера, датум и назив команде, као што је дефинисано у уводном делу.
Ако желиш да . . .
Када Pandoc креира вашу ман страницу, такође можете директно уредити датотеку у groff макро формату пре него што је преместите у директоријум ман страница и компримујете је.