Комплетан туторијал за команду man у Линуксу

Ако се већ неко време петљате са ГНУ/Линуксом, вероватно сте више пута користили команду `man` да бисте се извукли из застоја са синтаксом програма, необичном опцијом или конфигурационом датотеком. Упркос томе, многи људи је користе само површно и нису свесни свега што нуди: одељке, формате, пречице, па чак и могућност креирања сопствених приручника.

У наредним редовима ћете пронаћи комплетан туторијал о Линуксовој страници упутства : шта је то тачно, како су странице упутства организоване, како их ефикасно консултовати, где се чувају, како их ручно креирати помоћу Грофових макроа и како их лако генерисати помоћу алата као што је Пандоц. Циљ је да на крају не само читате упутства већ и пишете сопствена за документовање скрипти и апликација.

Шта је човек и зашто је толико важан у Линуксу

У UNIX-сличним системима, укључујући GNU/Linux, главна документација је организована у man странице , доступне преко команде `man` . Ове странице пружају детаљне описе команди, услужних програма, системских позива, библиотечких функција, посебних датотека и још много тога.

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

Да бисте приступили помоћи за било који инсталирани алат, једноставно откуцајте ` man command_name` у терминалу . Резултати се приказују у пагинираном формату (обично помоћу LESS прегледача), што вам омогућава лаку навигацију кроз дугачке документе без затрпавања екрана.

У многим дистрибуцијама, странице су доступне на неколико језика и чувају се у различитим директоријумима у зависности од језика. Није сав садржај преведен на шпански , али у Дебијану и његовим дериватима можете инсталирати пакете попут manpages-es и manpages-es-extra да бисте имали добар део приручника доступан на шпанском језику.

У оквиру ГНУ екосистема постоји и добро познати Пројекат документације за Линукс (TLDP) , који координира званичну документацију на енглеском језику и има шпанску верзију (es.tldp.org). Такође можете погледати комплетан водич за серверске приручнике . Иако није ограничен само на странице приручника, био је кључни пројекат у ширењу техничке документације за Линукс.

Ручна организација по одељцима

Приручник за UNIX и Linux је подељен на нумерисане одељке који групишу одређене типове информација . Ово спречава мешање, на пример, корисничке команде са системским позивом језгра који има исто име.

Класични (и најраспрострањенији) делови приручника су следећи, сваки повезан са добро дефинисаним типом садржаја унутар човека:

• Одељак 1: корисничке извршне команде (програми покренути из љуске).
• Одељак 2: системски позиви или системски позиви које обезбеђује језгро.
• Одељак 3библиотечке функције (C, C++, Perl, итд.).
• Одељак 4: посебне датотеке уређаја, обично у / дев.
• Одељак 5: формати датотека и конвенције (на пример / етц / пассвд).
• Одељак 6: игре и чувари екрана.
• Одељак 7разно (протоколи, стандарди, разне конвенције итд.).
• Одељак 8: команде и демони за системску администрацију (намењени за root кориснике).
• Одељак 9: интерне рутине језгра (нису увек присутне или стандардизоване).

Ова подела се огледа и у логичкој структури приручника и у системским директоријумима: сваки одељак има свој manN фолдер (man1, man2, man3, итд.), где се чувају одговарајуће странице, обично компресоване помоћу gzip-а.

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

Како ефикасно користити човека

Основна употреба команде је веома једноставна: ако желимо да консултујемо помоћ за било који програм, једноставно откуцамо нешто попут `man command` у терминалу да бисмо отворили његову страницу приручника . Одатле улазимо у пагинирани прегледач (обично `less`) који нам омогућава да се крећемо кроз садржај.

Када се исто име појави у више одељака, `man` скенира приручник од најнижег до највишег одељка и приказује прво подударање које пронађе. На пример, ако покренете `man chmod` , видећете страницу корисничких команди (одељак 1) јер тај одељак има предност над одељком 2.

Ако треба да форсирате одређени одељак, можете га експлицитно навести пре имена: покретање man 1 chmod вам даје упутство за команду , док помоћу man 2 chmod приступате опису системског позива chmod језгра.

Општи формат команде је веома лако запамтити: man name… . Ако изоставите одељак, man ће претраживати у растућем редоследу; ако га укључите, отићи ћете директно на исправну страницу без двосмислености.

Унутар странице, излаз се приказује у пагинацији, обично користећи Less као интерни прегледач . Можете се кретати помоћу тастера са стрелицама, Page Up и Page Down, размакнице или стандардних Less пречица. Да бисте изашли и вратили се у командну линију, једноставно притисните тастер q.

Корисне пречице приликом консултовања приручника са мање

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

Ако листате посебно дугачку страницу и пронађете кључну тачку на коју желите да се вратите касније, можете да означите тренутну позицију у документу . Једноставно притисните тастер m , а затим слово (az или AZ) да бисте направили обележивач.

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

Имајте на уму да ознаке постоје само док је та страница отворена . Чим затворите man (а самим тим и less), оне нестају. Међутим, овај трик функционише и за било коју другу датотеку коју директно отворите са less, не само за странице приручника (man pages).

Још једна веома практична карактеристика је могућност покретања команди шелла без затварања странице упутства . Баш као у едиторима као што су vi или vim, можете притиснути ! унутар less-а, унети команду коју желите да испробате и покренути је; када завршите, враћате се тамо где сте били на страници упутства једноставним притиском на Enter.

Како је синтакса описана на страницама упутства (man pages)?

Један од најважнијих делова сваке странице приручника је одељак СИНОПСИС , који приказује синтаксу команде, функције или датотеке. Да би се осигурало да је сажет, али прецизан, користи се низ конвенција које треба савладати.

Када видите елемент између заграда , то значи да је опционалан . Ако се текст појављује као ` {x,y}`, можете изабрати да ли ћете укључити ту опцију или не; међутим, ако је приказано као `{x,y}` , елементи унутар заграда су алтернативе, али морате изабрати једну од њих.

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

Опције су понекад сумиране синтаксом попут `-x` , што сугерише да ниједна од њих није обавезна, али ако их користите, можете комбиновати било које од слова било којим редоследом . Дакле, `-x`, `-y`, `-z`, `-xy`, `-zx`, итд., биле би валидне, све док програм прихвата ту комбинацију.

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

Типична структура странице приручника

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

Основна анатомија странице приручника обично укључује неколико добро познатих одељака као што су ИМЕ, СИНОПСИС и ОПИС , којима се могу додати други у зависности од тога шта је потребно документовати. Не постоји крут захтев, али постоји низ широко коришћених конвенција.

Најчешћи одељци које ћете пронаћи (или које би требало да користите приликом креирања сопствених страница) су, између осталог, следећи, који групишу информације на предвидљив начин за корисника :

• ИМЕ: име команде или датотеке и кратак опис.
• СИНОПСИС: линија или линије које сумирају параметре и опције.
• ОПИС: детаљно објашњење како функционише.
• ОПЦИЈЕ / ОПЦИЈЕ: опис свих опција командне линије (углавном у одељцима 1 и 8).
• КОМАНДЕ: листа подкоманди или интерних радњи, ако их алат има.
• ЖИВОТНА СРЕДИНА: релевантне променљиве окружења и како их програм користи.
• ДАТОТЕКЕ / АРХИВЕ: датотеке које алат користи или мења (конфигурација, логови итд.).
• ГРЕШКЕ / ГРЕШКЕпознати проблеми или ограничења.
• ПРИМЕР: примери употребе из стварног света, веома корисни за свакодневни живот.
• АУТОРИаутори програма или самог приручника, често са имејлом.
• ВИДИ ТАКОЂЕ / VÉASE TBIÍA: референце на друге сродне странице приручника.

Поред ових, уобичајено је укључити и друге као што су ИЗЛАЗНИ СТАТУС, УПОЗОРЕЊА, НАПОМЕНЕ, ПОВРАТНА ВРЕДНОСТ или ДИЈАГНОСТИКА када желите дубље да се позабавите излазним кодовима, упозорењима, додатним напоменама или специфичним порукама о грешкама.

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

Грофови макрои за форматирање који се користе у страницама упутства

Ако отворите изворни фајл класичне странице приручника (на пример, распакивањем gpg.1.gz), видећете прилично груб текст пун редова који почињу тачком након чега следе скраћенице . Ове скраћенице су управо макрои за форматирање које систем приручника разуме.

Макро који отвара страницу зове се .TH и дефинише главни заглавак . Општа структура коју прати је отприлике оваква: .TH назив-команде број-секције датум наслов аутора , све у једном реду, са великим словима за назив команде.

Пример из стварног света може изгледати отприлике овако .TH GPG 1 2015-03-08 „GnuPG 1.4.12“ „GNU Privacy Guard“ , где су наведени назив програма, одељак, датум ревизије приручника, назив верзије и описни наслов.

Различити делови садржаја су структурирани помоћу .SH макроа, који уводи нове одељке у документ . Његов основни облик је веома једноставан: .SH НАЗИВ_ОДЕЉКА , након чега следи текст који чини тај одељак, све док се не декларише нови.

За форматирање одређених фрагмената текста користе се макрои као што су .B, .I и .R , што означава подебљани, курзивни/подвучени и „римски“ фонт (нормалан текст), респективно. Постоје и комбинације попут .BI или .IR за мешање стилова унутар истог реда.

Веома једноставан пример би био нешто попут .B ово је .I тест , што би се отприлике приказало као „ово је“ истакнуто и „тест“ курзивом. Мана је што ови макрои често утичу на целу линију ако се пажљиво не контролишу.

За прецизнију контролу, уобичајено је користити секвенце за промену фонта као што су \fB, \fI и \fR , које мењају стил на одређеним тачкама унутар реда. Дакле, могли бисте написати нешто попут \fB ово је \fI тест за прецизнији резултат.

Експлицитни преломи редова су означени са .br, док се нови пасуси креирају са .pp . На овај начин, аутор приручника одлучује како ће текст бити визуелно структуриран када се приказује помоћу команде man, без ослањања искључиво на размак.

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

Локација и организација страница приручника у систему

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

Веома типична путања где се налазе ове странице је /usr/share/man , мада можете пронаћи и друге локације као што су /usr/man , /usr/local/man или /usr/local/share/man , у зависности од дистрибуције или да ли се ради о локално инсталираном софтверу.

Сваки одељак приручника одговара поддиректоријуму под називом manN (man1, man2, man3, итд.) . На пример, типичан кориснички програм може имати свој приручник у /usr/share/man/man1/program.1.gz , док се администраторска страница може налазити у man8.

Ако желите да пронађете датотеке повезане са одређеним програмом (укључујући и његову страницу приручника), можете користити `whereis program_name` да би вам систем приказао релевантне путање . Излаз ће обично садржати тачну путању до .N.gz датотеке која садржи страницу приручника.

Када треба да „анализирате“ приручник да бисте сазнали како је направљен, а да притом не ризикујете да било шта оштетите, можете копирати датотеку из /usr/share/man у безбедан директоријум као што је /usr/src, а затим је декомпримирати помоћу gzip-а да бисте анализирали његов садржај помоћу свог омиљеног едитора.

Имајте на уму да нумерација одељака није декоративна: приликом прегледа /usr/share/man видећете директоријуме од man1 до man8 (а понекад и man9) , а сваки од њих групише приручнике одређеног типа. На овај начин се одржава доследна и лако одржавајућа структура.

Како да ручно креирате сопствене странице приручника

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

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

Приликом именовања датотеке, пратите конвенцију name.section . Ако се ваш скрипт зове test и представља обичан кориснички програм, обично бисте га назвали test.1 јер припада одељку 1. Затим, унутра, дефинисаћете наслов са .TH, одељке са .SH и форматирани садржај помоћу макроа које већ знате.

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

Да бисте је учинили доступном другим корисницима, једноставно копирајте компресовану датотеку у одговарајући директоријум секције , на пример /usr/share/man/man1/ ако је у питању нормална команда или man8 ако је у питању администраторска команда.

Када је датотека смештена на исправну локацију, можете отворити свој приручник једноставним куцањем `man test` из било ког терминала на систему . Од тада ће се понашати као и било која друга стандардна страница приручника.

Креирање приручника помоћу pandoc-а и Markdown-а

Директно уређивање у Groff формату је у реду за учење, али може бити мало компликовано. Ако више волите нешто што је једноставније за коришћење, можете користити Markdown и конвертовати га у формат странице приручника помоћу алата као што је pandoc , што знатно убрзава процес документације.

Први корак је инсталирање pandoc-а користећи менаџер пакета ваше дистрибуције (apt, dnf, pacman, итд.). Након инсталације, можете креирати своју man страницу у датотеци са екстензијом .N.md, на пример, hello.1.md за команду под називом hello.

У тој Markdown датотеци можете написати своју документацију са одељцима за ИМЕ, СИНОПСИС, ОПИС, ОПЦИЈЕ, ПРИМЕРЕ и било које друге одељке који су вам потребни. Било који једноставан уређивач текста попут vim, nano, gedit или слично ће радити за овај задатак.

Када завршите са писањем садржаја у Markdown-у, време је да кажете pandoc-у да га конвертује у формат странице упутства који man разуме . Да бисте то урадили, користите команду попут: `pandoc -s -t man -o hello.1 hello.1.md`, где име излаза укључује секцију као своју екстензију.

Опција `-s` (самостална) говори pandoc-у да генерише комплетну страницу приручника , са свом потребном структуром, а не само исечак текста без заглавља. Опција `-t man`, с друге стране, наводи да тип излаза треба да буде управо онај формат приручника који систем тада разуме.

Када генеришете датотеку hola.1, можете је компресовати ако желите, копирати је у /usr/local/man/man1 или неку другу одговарајућу локацију и проверити да ли ради тако што ћете откуцати `man hola`. Ово ће вам дати чист и одржив приручник, згодно написан у Markdown-у.

Инсталирање, лоцирање и уклањање ваших man страница

Када развијате сопствени скрипт или програм, има смисла не само инсталирати бинарну датотеку, већ и поставити њену страницу упутства (man page) на исправну путању како би је сваки корисник могао лако позвати из терминала.

Ако сте креирали, на пример, извршну датотеку под називом hello, типична локација за бинарну датотеку би била /usr/bin/hello , тако да је можете позвати једноставним куцањем hello без потребе да идете у њен изворни фолдер или мењате PATH.

Одговарајућа страница упутства (man) треба да се налази у /usr/share/man/man1/hola.1.gz или сличном директоријуму у складу са одељком и политикама ваше дистрибуције. Ако је у питању административни алат, можда бисте желели да га сместите у man8.

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

Да бисте ручно деинсталирали, једноставно уклоните бинарну датотеку из њене путање (на пример, /usr/bin/hola) и страницу приручника из одговарајућег директоријума приручника . Након тога, сваки покушај покретања команде `man hola` вратиће грешку која указује да унос не постоји.

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

На крају крајева, савладавање команде `man` и формата страница приручника вам омогућава не само да ефикасно консултујете Линукс документацију, већ и да трансформишете сопствене скрипте и апликације у добро документоване и кориснички прилагођене алате . Када укључите приручнике са јасним одељцима, примерима и референцама, значајно побољшавате искуство за свакога ко ће користити ваш рад, било да је то неко други или чак ви сами за неколико месеци када се више не сећате детаља.