Komplett veiledning for man-kommandoen i Linux

Hvis du har tuklet med GNU/Linux en stund, har du sannsynligvis brukt `man`-kommandoen mer enn én gang for å komme deg ut av en fastlåst situasjon med programsyntaks, et uvanlig alternativ eller en konfigurasjonsfil. Likevel bruker mange den bare overfladisk og er ikke klar over alt den tilbyr: seksjoner, formater, snarveier og til og med muligheten til å lage sine egne manualer.

I de følgende linjene finner du en komplett veiledning om Linux man-siden : hva det er nøyaktig, hvordan man-sidene er organisert, hvordan du kan konsultere dem effektivt, hvor de er lagret, hvordan du oppretter dem manuelt med Groff-makroer, og hvordan du enkelt genererer dem med verktøy som Pandoc. Målet er at du ikke bare skal lese manualer, men også skrive dine egne for å dokumentere skript og applikasjoner.

Hva er mennesket, og hvorfor er det så viktig i Linux

I UNIX-lignende systemer, inkludert GNU/Linux, er hoveddokumentasjonen organisert i man-sider , tilgjengelige via `man` -kommandoen . Disse sidene gir detaljerte beskrivelser av kommandoer, verktøy, systemkall, bibliotekfunksjoner, spesialfiler og mye mer.

Hver man-oppføring gir en oversikt over kommandoens bruk , en omfattende beskrivelse, en liste over alternativer, eksempler og ofte tilleggsinformasjon som relaterte filer, miljøvariabler, kjente feil eller referanser til andre relaterte man-sider.

For å få tilgang til hjelpen for et hvilket som helst installert verktøy, skriver du ganske enkelt ` man command_name` i terminalen . Resultatene vises i et paginert format (vanligvis ved bruk av LESS-visningsprogrammet), slik at du enkelt kan navigere gjennom lange dokumenter uten å rote til skjermen.

I mange distribusjoner er sidene tilgjengelige på flere språk og lagres i forskjellige kataloger avhengig av språket. Ikke alt innholdet er oversatt til spansk , men i Debian og dets derivater kan du installere pakker som manpages-es og manpages-es-extra for å ha en god del av manualen tilgjengelig på spansk.

Innenfor GNU-økosystemet finnes også det velkjente Linux Documentation Project (TLDP) , som koordinerer offisiell dokumentasjon på engelsk og har en spansk versjon (es.tldp.org). Du kan også se den komplette veiledningen til servermanualer . Selv om den ikke er begrenset til manualsider, har den vært et sentralt prosjekt i formidlingen av teknisk dokumentasjon for Linux.

Manuell organisering etter seksjoner

UNIX- og Linux-håndboken er delt inn i nummererte seksjoner som grupperer spesifikke typer informasjon . Dette forhindrer at for eksempel en brukerkommando blandes med et kjernesystemkall som har samme navn.

De klassiske (og mest utbredte) delene av manualen er følgende, hver assosiert med en veldefinert type innhold i mennesket:

• Seksjon 1: brukerkjørbare kommandoer (programmer som startes fra skallet).
• Seksjon 2systemkall eller syskall levert av kjernen.
• Seksjon 3: bibliotekfunksjoner (C, C++, Perl, osv.).
• Seksjon 4spesielle enhetsfiler, vanligvis i / dev.
• Seksjon 5filformater og konvensjoner (for eksempel / Etc / passwd).
• Seksjon 6spill og skjermsparere.
• Seksjon 7diverse (protokoller, standarder, diverse konvensjoner osv.).
• Seksjon 8systemadministrasjonskommandoer og daemoner (beregnet for root).
• Seksjon 9interne kjernerutiner (ikke alltid tilstede eller standardiserte).

Denne inndelingen gjenspeiles både i den logiske strukturen i manualen og i systemkatalogene: hver seksjon har sin egen manN-mappe (man1, man2, man3 osv.), hvor de tilsvarende sidene er lagret, vanligvis komprimert med gzip.

Det er vanlig å finne navn gjentatt i forskjellige seksjoner. For eksempel finnes chmod både som en brukerkommando og som et systemkall . I disse tilfellene er seksjonen det som skiller en side fra en annen, og det er avgjørende å vite hvilken du vil ha tilgang til.

Hvordan bruke mannen effektivt

Den grunnleggende bruken av kommandoen er veldig enkel: Hvis vi vil se hjelpen for et program, skriver vi ganske enkelt noe sånt som «man command» i terminalen for å åpne manualsiden . Derfra går vi inn i en paginert visningsfunksjon (vanligvis «less») som lar oss navigere gjennom innholdet.

Når samme navn vises i flere seksjoner, skanner `man` manualen fra den laveste til den høyeste seksjonen og viser det første treffet den finner. Hvis du for eksempel kjører `man chmod` , vil du se brukerkommandosiden (seksjon 1) fordi den seksjonen har prioritet over seksjon 2.

Hvis du trenger å tvinge frem en bestemt seksjon, kan du spesifisere den eksplisitt før navnet: å kjøre man 1 chmod gir deg manualen for kommandoen , mens med man 2 chmod får du tilgang til beskrivelsen av kjernens chmod-systemkall.

Det generelle formatet til kommandoen er veldig lett å huske: mann navn… . Hvis du utelater seksjonen, vil mann søke i stigende rekkefølge; hvis du inkluderer den, vil du gå direkte til riktig side uten tvetydighet.

Innenfor siden vises resultatet i paginering, vanligvis ved å bruke Less som intern visning . Du kan navigere ved hjelp av piltastene, Page Up og Page Down, mellomromstasten eller standard Less-snarveier. For å avslutte og gå tilbake til kommandolinjen, trykker du bare på q -tasten.

Nyttige snarveier når du konsulterer manualer med mindre

Siden mennesket er avhengig av mindre, arver det en hel rekke snarveier som gjør det mye enklere å lese lange manualer. Noen av dem går ubemerket hen, men når du først bruker dem, er det vanskelig å leve uten dem.

Hvis du blar gjennom en spesielt lang side og finner et viktig punkt du vil gå tilbake til senere, kan du bokmerke gjeldende posisjon i dokumentet . Bare trykk på m -tasten etterfulgt av en bokstav (az eller AZ) for å opprette et bokmerke.

Når du vil gå tilbake til den markøren, trykker du bare på anførselstegnet ' etterfulgt av den samme bokstaven du brukte for å lage den. På denne måten kan du raskt hoppe mellom viktige posisjoner uten å måtte anstrenge deg for å prøve å huske hvor alt var.

Husk at taggene bare eksisterer mens du har den siden åpen . Så snart du lukker man (og dermed less), forsvinner de. Dette trikset fungerer imidlertid også for alle andre filer du åpner direkte med less, ikke bare man-sider.

En annen veldig praktisk funksjon er muligheten til å kjøre skallkommandoer uten å lukke man-siden . Akkurat som i editorer som vi eller vim, kan du trykke ! inni less, skrive inn kommandoen du vil prøve og kjøre den. Når du er ferdig, går du tilbake til der du var på man-siden ved å trykke Enter.

Hvordan er syntaksen beskrevet i man-sidene?

En av de viktigste delene av enhver manualside er SYNOPSIS-delen , som viser syntaksen til kommandoen, funksjonen eller filen. For å sikre at den er konsis, men presis, brukes en rekke konvensjoner som bør mestres.

Når du ser et element mellom parenteser , betyr det at det er valgfritt . Hvis teksten vises som ` {x,y}`, kan du velge å inkludere det alternativet eller ikke. Hvis det derimot vises som `{x,y}` , er elementene i parentesene alternativer, men du må velge ett av dem.

Hvis sammendraget inneholder noe slikt , indikerer det at du kan bruke x. Jeg gjør ingenting , nettopp fordi hele uttrykket er omsluttet av hakeparenteser. På samme måte, hvis x… vises , betyr det at x kan gjentas så mange ganger som nødvendig på kommandolinjen.

Alternativene oppsummeres noen ganger med syntaks som `-x` , noe som antyder at ingen av dem er obligatoriske, men hvis du bruker dem, kan du kombinere hvilken som helst av bokstavene i hvilken som helst rekkefølge . Dermed vil `-x`, `-y`, `-z`, `-xy`, `-zx` osv. være gyldige, så lenge programmet godtar den kombinasjonen.

Denne kompakte måten å uttrykke syntaks på lar deg kondensere alle mulighetene til én linje , selv om det kan virke litt kryptisk i starten. Når du først har fått taket på det, blir det mye enklere å lese manualer.

Typisk struktur på en manualside

Bak hver man-side ligger en tekstfil i et spesifikt format basert på Groff og et sett med makroer som definerer seksjoner, titler, stiler, avsnitt osv. Selv om resultatet ved første øyekast er "bare tekst", er det mye mer ved det enn det.

Den grunnleggende anatomien til en manualside inneholder vanligvis flere kjente seksjoner som NAVN, SYNOPSIS og BESKRIVELSE , som andre kan legges til avhengig av hva som må dokumenteres. Det er ingen strenge krav, men det finnes en rekke mye brukte konvensjoner.

De vanligste seksjonene du finner (eller som du bør bruke når du lager dine egne sider) er blant annet følgende, som grupperer informasjon på en forutsigbar måte for brukeren :

• NAVN: kommando- eller filnavn og en kort beskrivelse.
• SAMMENDRAGlinje eller linjer som oppsummerer parametere og alternativer.
• BESKRIVELSE: detaljert forklaring av hvordan det fungerer.
• ALTERNATIVER / ALTERNATIVER: beskrivelse av alle kommandolinjealternativer (hovedsakelig i avsnitt 1 og 8).
• KOMMANDOER: liste over underkommandoer eller interne handlinger, hvis verktøyet har dem.
• MILJØrelevante miljøvariabler og hvordan programmet bruker dem.
• FILER / ARKIVfiler som verktøyet bruker eller endrer (konfigurasjon, logger osv.).
• FEIL / FEILkjente problemer eller begrensninger.
• EKSEMPEL: eksempler på bruk fra den virkelige verden, veldig nyttige i hverdagen.
• FORFATTERE: forfattere av programmet eller selve manualen, ofte med e-post.
• SE OGSÅ / VÉASE TBIÍAreferanser til andre relaterte man-sider.

I tillegg til disse er det vanlig å inkludere andre som AVSLUTTSTATUS, ADVARSLER, MERKNADER, RETURVERDI eller DIAGNOSTIKK når du vil gå dypere inn i avslutningskoder, advarsler, tilleggsmerknader eller spesifikke feilmeldinger.

Selv om det kan virke litt kjedelig i starten, vil det å respektere disse avsnittene når du skriver manualene dine få brukerne til å føle seg «hjemme », ettersom de vil vite hvor de skal finne hver type informasjon uten å måtte utforske i blinde.

Groff-formateringsmakroer brukt i man-sider

Hvis du åpner kildefilen til en klassisk man-side (for eksempel ved å pakke ut gpg.1.gz), vil du se en ganske grov tekst full av linjer som begynner med et punktum etterfulgt av forkortelser . Disse forkortelsene er nettopp formateringsmakroene som det manuelle systemet forstår.

Makroen som åpner siden kalles .TH og definerer hovedoverskriften . Den generelle strukturen den følger er omtrent slik: .TH kommandonavn seksjonsnummer dato Forfattertittel , alt på én linje, med store bokstaver for kommandonavnet.

Et eksempel fra den virkelige verden kan se omtrent slik ut: .TH GPG 1 2015-03-08 "GnuPG 1.4.12" "GNU Privacy Guard" , der programnavnet, seksjonen, datoen for manuell revisjon, versjonsnavnet og en beskrivende tittel er spesifisert.

De ulike delene av innholdet er strukturert med .SH-makroen, som introduserer nye seksjoner i dokumentet . Grunnformen er veldig enkel: .SH SECTION_NAME , etterfulgt av teksten som utgjør den seksjonen, inntil en ny er deklarert.

For å formatere spesifikke tekstfragmenter brukes makroer som .B, .I og .R , som indikerer henholdsvis fet skrift, kursiv/understreket og "roman" skrift (normal tekst). Kombinasjoner som .BI eller .IR finnes også for å blande stiler innenfor samme linje.

Et veldig enkelt eksempel ville være noe sånt som .B this is a .I test , som omtrent vises som «dette er en» uthevet og «test» i kursiv. Ulempen er at disse makroene ofte påvirker hele linjen hvis de ikke kontrolleres nøye.

For finere kontroll er det vanlig å bruke fontendringssekvenser som \fB, \fI og \fR , som endrer stilen på bestemte punkter i en linje. Så du kan skrive noe sånt som \fB, dette er en \fI-test for et mer presist resultat.

Eksplisitte linjeskift er angitt med .br, mens nye avsnitt opprettes med .pp . På denne måten bestemmer forfatteren av manualen hvordan teksten er visuelt strukturert når den vises med man, uten å bare stole på mellomrom.

Hvis det er nødvendig å legge igjen interne kommentarer som brukere ikke vil se når de kjører man, kan en kommentarmakro brukes (for eksempel med linjer som begynner med et punktum og en omvendt skråstrek), som er nyttig for å gi ledetråder til fremtidige vedlikeholdere av manualen uten at det vises i den endelige versjonen.

Plassering og organisering av manualsider i systemet

For å forstå hvordan manualsider fungerer fullt ut, er det utrolig nyttig å vite hvor filene fysisk er lagret på systemet . Dette er spesielt nyttig når du vil inspisere, kopiere eller lage dine egne manualer.

En veldig typisk sti der disse sidene befinner seg er /usr/share/man , selv om du også kan finne andre steder som /usr/man, /usr/local/man eller /usr/local/share/man , avhengig av distribusjonen eller om det er lokalt installert programvare.

Hver del av manualen tilsvarer en underkatalog kalt manN (man1, man2, man3, osv.) . For eksempel kan et typisk brukerprogram ha manualen sin i /usr/share/man/man1/program.1.gz , mens en administrasjonsside kan ligge i man8.

Hvis du vil finne filene som er knyttet til et bestemt program (inkludert manualsiden), kan du bruke `whereis program_name` for å få systemet til å vise deg relevante stier . Resultatet vil vanligvis inkludere den nøyaktige stien til .N.gz-filen som inneholder manualsiden.

Når du trenger å «dissekere» en manual for å lære hvordan den er laget uten å risikere å skade noe, kan du kopiere filen fra /usr/share/man til en sikker katalog som /usr/src, og deretter dekomprimere den med gzip for å analysere innholdet med din favoritteditor.

Husk at seksjonsnummereringen ikke er dekorativ: når du inspiserer /usr/share/man vil du se katalogene man1 til man8 (og noen ganger man9) , og hver av dem grupperer manualer av en bestemt type. På denne måten opprettholdes en konsistent og lettstelt struktur.

Slik lager du dine egne man-sider «for hånd»

Når du forstår den grunnleggende strukturen og makroene, kan du begynne å lage din egen manual for skript eller programmer (for eksempel en Bash-manual ). Prosessen er ikke så komplisert som den kan virke, selv om den krever litt oppmerksomhet på detaljer for å sikre at den er ren og nyttig.

En klassisk tilnærming innebærer å velge en eksisterende man-side som referanse (for eksempel den for gpg eller iptables), kopiere den til en annen katalog, pakke den ut og bruke den som en mal for å lære den faktiske syntaksen . Derfra fjerner du innhold, og etterlater bare strukturen du trenger.

Når du navngir filen, følg name.section- konvensjonen . Hvis skriptet ditt heter test og er et vanlig brukerprogram, vil du vanligvis kalle det test.1 fordi det tilhører seksjon 1. Deretter definerer du tittelen med .TH, seksjonene med .SH og det formaterte innholdet med makroene du allerede kjenner.

Når du har den klar, er neste trinn å komprimere filen med gzip , som vil generere test.1.gz klar til å installeres på riktig sted. Det komprimerte formatet er det som brukes av det manuelle systemet som standard.

For å gjøre den tilgjengelig for andre brukere, kopierer du ganske enkelt den komprimerte filen til riktig seksjonskatalog , for eksempel /usr/share/man/man1/ hvis det er en vanlig kommando, eller man8 hvis det er en administrativ kommando.

Når filen er plassert på riktig sted, kan du åpne manualen din ved å skrive `man test` fra hvilken som helst terminal på systemet . Fra da av vil den oppføre seg som en hvilken som helst annen standard man-side.

Lage manualer med pandoc og Markdown

Det er greit å redigere direkte i Groff-format for læring, men det kan være litt røft i kantene. Hvis du foretrekker noe mer brukervennlig, kan du bruke Markdown og konvertere det til man-sideformat med verktøy som pandoc , noe som øker hastigheten på dokumentasjonsprosessen betraktelig.

Det første trinnet er å installere pandoc ved hjelp av distribusjonens pakkebehandler (apt, dnf, pacman, osv.). Når den er installert, kan du opprette man-siden din i en fil med filtypen .N.md, for eksempel hello.1.md for en kommando kalt hello.

I den Markdown-filen kan du skrive dokumentasjonen din med seksjoner for NAVN, SYNOPSIS, BESKRIVELSE, ALTERNATIVER, EKSEMPLER og andre seksjoner du trenger. Enhver enkel teksteditor som vim, nano, gedit eller lignende vil fungere for denne oppgaven.

Når du er ferdig med å skrive Markdown-innholdet ditt, er det på tide å be pandoc om å konvertere det til man-sideformatet som man forstår . For å gjøre dette, bruk en kommando som: `pandoc -s -t man -o hello.1 hello.1.md`, der utdatanavnet inkluderer seksjonen som filtypen.

Alternativet `-s` (frittstående) forteller pandoc at det skal generere en komplett man-side med all nødvendig struktur, og ikke bare et tekstutdrag uten overskrift. Alternativet `-t man`, derimot, spesifiserer at utdatatypen skal være nøyaktig det manuelle formatet som systemet da forstår.

Når du har generert hola.1-filen, kan du komprimere den hvis du ønsker, kopiere den til /usr/local/man/man1 eller et annet passende sted , og bekrefte at den fungerer ved å skrive `man hola`. Dette vil gi deg en ren og vedlikeholdbar manual, praktisk skrevet i Markdown.

Installere, finne og fjerne man-sidene dine

Når du utvikler ditt eget skript eller program, er det fornuftig ikke bare å installere binærfilen, men også å plassere man-siden i riktig sti, slik at enhver bruker enkelt kan kalle den fra terminalen.

Hvis du for eksempel har opprettet en kjørbar fil kalt hello, vil en typisk plassering for binærfilen være /usr/bin/hello , slik at du kan kalle den ved å skrive hello uten å måtte gå til kildemappen eller endre PATH-en.

Den tilhørende man-siden bør finnes i /usr/share/man/man1/hola.1.gz eller en lignende katalog i henhold til distribusjonens seksjon og retningslinjer. Hvis det er et administrativt verktøy, foretrekker du kanskje å plassere det i man8.

I miljøer der du distribuerer programvaren din til tredjeparter, er det veldig praktisk å inkludere installasjons- og avinstallasjonsskript som kopierer eller fjerner både binærfilen og man-siden. På denne måten, hvis brukeren bestemmer seg for å slette verktøyet ditt, vil ingen foreldreløs dokumentasjon bli liggende igjen på systemet.

For å avinstallere manuelt, fjern ganske enkelt binærfilen fra banen (for eksempel /usr/bin/hola) og man-siden fra den tilhørende man-katalogen . Etter det vil ethvert forsøk på å kjøre `man hola` returnere en feil som indikerer at oppføringen ikke finnes.

Ved å bruke disse stedene konsekvent integreres programvaren din "naturlig" i systemet , og følger de samme mønstrene som brukes av verktøyene som er inkludert i distribusjonen.

Til syvende og sist lar det å mestre `man`-kommandoen og formatet på manualsider deg ikke bare effektivt konsultere Linux-dokumentasjon, men også transformere dine egne skript og applikasjoner til veldokumenterte og brukervennlige verktøy . Når du integrerer manualer med tydelige seksjoner, eksempler og referanser, forbedrer du opplevelsen betydelig for alle som skal bruke arbeidet ditt, enten det er noen andre eller til og med deg selv om noen måneder når du ikke lenger husker detaljene.