Komplett veiledning for man-kommandoen i Linux

Hvis du har tuklet med GNU/Linux en stund, har du sannsynligvis brukt kommandoen mer enn én gang. mann for å få deg ut av en vanskelig situasjon med syntaksen til et program, et uvanlig alternativ eller en konfigurasjonsfil. Likevel bruker mange det bare overfladisk og er ikke klar over alt som ligger bak det: seksjoner, formater, snarveier og til og med muligheten for å lage sine egne manualer.

I de følgende linjene finner du en Komplett veiledning om bruk av man i LinuxDette vil dekke nøyaktig hva en manual er, hvordan sidene er organisert, hvordan man kan konsultere dem effektivt, hvor de er lagret, hvordan man oppretter dem manuelt ved hjelp av Groff-makroer, og hvordan man genererer dem enkelt 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 den såkalte manualsider eller manualsider, tilgjengelig via kommandoen mannDisse sidene beskriver i detalj kommandoer, verktøy, systemkall, bibliotekfunksjoner, spesialfiler og mye mer.

Hver manns innspill gir Synopsis av kommandobruk, en omfattende beskrivelse, listen over alternativer, eksempler og ofte tilleggsinformasjon som relaterte filer, miljøvariabler, kjente feil eller referanser til andre relaterte man-sider.

For å få tilgang til hjelp for et installert verktøy, skriv bare noe så enkelt som mann kommandonavn i terminalenResultatet vises paginert (vanligvis ved hjelp av LESS-visningsprogrammet), slik at du komfortabelt kan navigere gjennom lange dokumenter uten å rote til skjermen.

I mange distribusjoner er sider tilgjengelige på flere språk og lagres i forskjellige kataloger avhengig av språket. Ikke alt innhold er oversatt til spanskMen i Debian og derivater kan du installere pakker som manualsider-es y manpages-es-extra å ha en god del av manualen tilgjengelig på spansk.

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

Manuell organisering etter seksjoner

UNIX- og Linux-håndboken er delt inn i nummererte seksjoner som grupperer spesifikke typer informasjonDette 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 håndboken og i systemkatalogene: Hver seksjon har sin egen manN-mappe (man1, man2, man3, osv.), hvor de tilsvarende sidene lagres, vanligvis komprimert med gzip.

Det er vanlig å finne navn som gjentas i forskjellige deler. For eksempel, chmod finnes som en brukerkommando og som et systemkallI disse tilfellene er det seksjonen som utgjør forskjellen mellom en side og en annen, og det er viktig å vite hvilken vi ønsker å få tilgang til.

Hvordan bruke mannen effektivt

Den grunnleggende bruken av kommandoen er veldig enkel: hvis vi vil konsultere hjelpen til et program, trenger vi bare å skrive noe slikt i terminalen: man-kommandoen for å åpne manualsidenDerfra går vi inn i en paginert visningsfunksjon (vanligvis mindre) som lar oss navigere gjennom innholdet.

Når samme navn vises i flere seksjoner, søker man i håndboken fra den laveste delen til den høyeste og viser det første treffet den finner. Hvis du for eksempel kjører mann chmodDu vil se brukerkommandosiden (del 1) fordi den delen har prioritet over del 2.

Hvis du trenger å tvinge frem en bestemt seksjon, kan du eksplisitt spesifisere den før navnet: når du kjører mann 1 chmod får du kommandomanualen, mens med mann 2 chmod Du får tilgang til beskrivelsen av kjernens chmod-systemkall.

Det generelle formatet som kommandoen følger er veldig lett å huske: mannsnavn…Hvis du utelater seksjonen, vil man søke i stigende rekkefølge. Hvis du inkluderer den, kommer du direkte til riktig side uten tvetydighet.

Innenfor siden presenteres resultatet paginert, vanligvis ved hjelp av mindre som en intern søkerDu kan navigere ved hjelp av piltastene, Page Up og Page Down, mellomromstasten eller de typiske snarveiene Less. For å avslutte og gå tilbake til kommandolinjen, trykker du bare på Enter-tasten. q.

Nyttige snarveier når du konsulterer manualer med mindre

Etter hvert som mennesket lener seg på mindre, arver det et helt batteri med snarveier som gjør lesingen enklere av lange manualer. Noen av dem går ubemerket hen, men når du først har brukt dem, er det vanskelig å leve uten dem.

Hvis du surfer på en spesielt lang side og finner et viktig punkt du vil gå tilbake til senere, kan du marker gjeldende posisjon i dokumentetDu trenger bare å trykke på tasten m etterfulgt av en bokstav (az eller AZ) for å lage en markør.

Når du vil gå tilbake til det merket, trykker du bare på anførselstegn. «etterfulgt av samme bokstav som du brukte da du lagde den. På denne måten kan du raskt hoppe mellom viktige posisjoner uten å måtte anstrenge deg for å huske hvor alt var.

Husk det Merker lever bare så lenge du har den siden åpen.Så snart du lukker `man` (og dermed `less`), går de tapt. Dette trikset fungerer imidlertid også for alle andre filer du åpner direkte med `less`, ikke bare man-sider.

En annen svært praktisk detalj er muligheten for Kjør skallkommandoer uten å lukke manualsidenAkkurat som i editorer som vi eller vim, kan du trykke ! Inne i less skriver du inn kommandoen du vil teste og kjører den. Når du er ferdig, går du tilbake til der du var i manualen ved å trykke Enter.

Hvordan er syntaksen beskrevet i man-sidene?

En av de viktigste delene av enhver manualside er SAMMENDRAGSSEKSJONDenne delen 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 Dette betyr at det er valgfritt.Hvis teksten vises som Du kan velge å velge dette alternativet eller ikke; men hvis det vises som {x,y}Elementene i bukseseler er alternativer, men du må velge ett av dem.

Hvis sammendraget inneholder noe slikt Det indikerer at du kan bruke x, jeg er ingentingnettopp fordi hele uttrykket er omsluttet av hakeparenteser. Hvis det i sin tur vises x...Dette betyr at x kan gjentas så mange ganger du trenger på kommandolinjen.

Alternativene oppsummeres noen ganger med syntaks som Dette antyder at ingen av dem er obligatoriske, men hvis du bruker dem, Du kan 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å tillater kondensering alle mulighetene på én linjeSelv om det kan virke litt kryptisk i starten, blir det mye mer effektivt å lese manualer når du først har internalisert det.

Typisk struktur på en manualside

Bak hver mann-side er det en tekstfil i et bestemt format basert på Groff og i 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 som så.

Den grunnleggende anatomien til en manualside inkluderer vanligvis flere seksjoner kjent som NAVN, SAMMENDRAG og BESKRIVELSEDisse kan suppleres med andre avhengig av hva som må dokumenteres. Det er ingen streng forpliktelse, 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 f.eks. UTGANGSTATUS, FORHOLDSREGLER, 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 gjøre det lettere brukerne føler seg «hjemme»fordi de vil vite hvor de skal lete etter 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 rå tekst full av linjer som begynner med et punktum etterfulgt av akronymerDisse akronymene er nettopp formateringsmakroene som det manuelle systemet forstår.

Makroen som åpner siden kalles .TH og definerer hovedoverskriftenDen generelle strukturen som 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 programnavn, seksjon, dato for manuell revisjon, versjonsnavn og en beskrivende tittel er spesifisert.

De ulike delene av innholdet er strukturert med makroen .SH, som introduserer nye seksjoner i dokumentetDen grunnleggende formen er veldig enkel: .SH SEKTIONSNAVN, og deretter teksten som utgjør den delen, helt til en ny deklareres.

For å formatere spesifikke tekstfragmenter brukes makroer som for eksempel .B, .I og .RDisse indikerer henholdsvis fet skrift, kursiv/understreket skrift 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 dette: .B dette er en .I-testsom omtrentlig ville blitt vist som «dette er en» uthevet og «bevis» i kursiv. Ulempen er at Disse makroene påvirker vanligvis resten av hele linjen. hvis de ikke kontrolleres nøye.

For finere kontroll er det vanlig å bruke kildebyttesekvenser som \fB, \fI og \fRsom endrer stilen kort innenfor en linje. Så du kan skrive noe sånt som Dette er en test for å få et mer nøyaktig resultat.

Eksplisitte linjeskift er angitt med .br, mens nye avsnitt opprettes med .PPPå denne måten bestemmer forfatteren av manualen hvordan teksten skal struktureres visuelt når den vises, uten å utelukkende stole på hvit plass.

Om nødvendig, dra Interne kommentarer som brukerne ikke vil se Når du kjører man, kan du bruke en kommentarmakro (for eksempel med linjer som starter med et punktum og en omvendt skråstrek), som er nyttig for å gi hint til fremtidige vedlikeholdere av manualen uten at den vises i den endelige versjonen.

Plassering og organisering av manualsider i systemet

For å forstå hvordan manualsidene fungerer fullt ut, er det veldig nyttig å vite hvor filene fysisk er lagret i systemetDette er spesielt nyttig når du vil inspisere, kopiere eller lage dine egne manualer.

En veldig typisk rute der disse sidene befinner seg er / usr / aksje / mannselv om du også kan finne andre steder, som f.eks. /usr/man, /usr/local/man eller /usr/local/share/manavhengig av distribusjonen eller om det er lokalt installert programvare.

Hver del av manualen tilsvarer en underkatalog kalt mannN (mann1, mann2, mann3 osv.)For eksempel kan et typisk brukerprogram ha manualen sin i /usr/share/man/man1/programa.1.gz, mens en administrasjonsside kan ligge i man8.

Hvis du vil finne filene som er knyttet til et bestemt program (inkludert man-siden), kan du bruke hvor programnavn er slik at systemet indikerer relevante stierUtdataene vil vanligvis inkludere den nøyaktige banen til .N.gz-filen fra manualsiden.

Når du trenger å «dissekere» en manual for å lære hvordan den lages uten å risikere å ødelegge noe, kan du Kopier filen fra /usr/share/man til en sikker mappe som /usr/src, og dekomprimer den deretter med gzip for å analysere innholdet med favoritteditoren din.

Husk at seksjonsnummereringen ikke er dekorativ: ved inspeksjon /usr/share/man vil du se mappene man1 til man8 (og noen ganger man9)Hver av dem grupperer manualer av en bestemt type. På denne måten oppnås en sammenhengende og lettstelt struktur.

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

Når du forstår strukturen og de grunnleggende makroene, kan du dykke ned i det. lag din egen manual for skript eller programmer (for eksempel en Bash-manualProsessen er ikke så komplisert som den kan virke, selv om den krever litt forsiktighet for å sikre at den er ren og brukbar.

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, dekomprimere den og bruk den som en mal for å lære den faktiske syntaksenDerfra fjerner du innhold og lar bare den strukturen du trenger være igjen.

Når filen gis navn, følges konvensjonen av seksjonsnavnHvis skriptet ditt heter test og det er et vanlig brukerprogram, er det vanlige å kalle det test.1 fordi den går til seksjon 1Så, inni, definerer du tittelen med .TH, seksjonene med .SH, og det formaterte innholdet med makroene du allerede kjenner.

Når du har det klart, er neste steg komprimere filen med gzipDette vil generere test.1.gz, klar til å installeres på riktig sted. Det komprimerte formatet er det som brukes av standard manuell system.

For å gjøre den tilgjengelig for andre brukere, ganske enkelt kopier den komprimerte filen til riktig seksjonskatalogFor 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 håndboken din ved å skrive mann-test fra hvilken som helst systemterminalFra da av vil den oppføre seg som en hvilken som helst annen man-side installert på standardmåten.

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 Bruk Markdown og konverter det til man-format med verktøy som pandoc.noe som fremskynder dokumentasjonsprosessen betraktelig.

Det første trinnet er å installere pandoc ved hjelp av pakkebehandleren i distribusjonen din (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 som gjenspeiler NAVN, SAMMENDRAG, BESKRIVELSE, ALTERNATIVER OG EKSEMPLER og alle andre du måtte trenge. Enhver enkel teksteditor som vim, nano, gedit eller lignende vil fungere for denne oppgaven.

Når du er ferdig med å skrive innholdet i Markdown, er det på tide å be pandoc om å konvertere det til manuell format som forstår mennesketFor å gjøre dette brukes en kommando som denne: pandoc -s -t man -o hola.1 hola.1.md, der utdatanavnet har seksjonen som filtypen.

Alternativet -s (frittstående) ber pandoc generere en fullstendig man-sidemed all nødvendig struktur, og ikke bare et tekstfragment uten overskrift. På sin side er alternativet `-t man`-klausulen spesifiserer at utdatatypen må være nøyaktig i formatet til manualen. som systemet deretter forstår.

Når hola.1-filen er generert, kan du komprimere den hvis du ønsker det, og kopiere den til /usr/local/man/man1 eller en annen passende sti og bekreft at det fungerer ved å skrive `man hola`. På denne måten får du en ren og lettstelt manual, med den ekstra fordelen av å ha skrevet den 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å plasser man-siden din i riktig sti slik at enhver bruker enkelt kan ringe henne 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/helloså du kan kalle den ganske enkelt ved å skrive hello uten å måtte gå til kildemappen eller endre PATH-en.

Den relevante manualsiden skal gå til /usr/share/man/man1/hola.1.gz eller en lignende katalog I henhold til seksjonen og retningslinjene for distribusjonen din. Hvis det er et administrasjonsverktø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 sletter 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 forbli spredt rundt i systemet.

For å avinstallere manuelt, trenger du bare å Fjern binærfilen fra banen (f.eks. /usr/bin/hello) og man-siden fra den tilhørende man-katalogen.Etter det vil ethvert forsøk på å kjøre man hola returnere en feilmelding om at oppføringen ikke finnes.

Å bruke disse stedene konsekvent gjør det Programvaren din integreres «naturlig» i systemet, etter 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 til man-sider deg ikke bare å konsultere Linux-dokumentasjon veldig effektivt, men også Gjør dine egne skript og applikasjoner om til veldokumenterte og brukervennlige verktøyNår du bruker manualer med tydelige avsnitt, eksempler og referanser, forbedrer du opplevelsen betraktelig for den som skal bruke arbeidet ditt, enten det er noen andre eller deg selv om noen måneder når du ikke lenger husker detaljene.