Sådan opretter du en man-side på Linux

Vil du have dit nye Linux-program til at se professionelt ud? Giv det en man-side. Vi viser dig den nemmeste og hurtigste måde at gøre det på.

Manden Pages

Der er en kerne af sandhed i den gamle Unix-joke, “den eneste kommando, du har brug for at vide er en mand.” Man-siderne indeholder et væld af viden, og de bør være det første sted, du henvender dig, når du vil lære om en kommando.

Ved at give en man-side til et hjælpeprogram eller en kommando, du har skrevet, hæver det fra et nyttigt stykke kode til en fuldt udformet Linux-pakke. Folk forventer, at der leveres en man-side til et program, der er skrevet til Linux. Hvis du oprindeligt understøtter Linux, er en man-side obligatorisk, hvis du ønsker, at dit program skal tages seriøst.

Historisk set er man-siderne blevet skrevet ved hjælp af et sæt formateringsmakroer. Når du opfordrer mand til at åbne en side, kalder den groff til læs filen og generer formateret output, ifølge makroerne i filen. Udgangen føres til mindre, og derefter vist for dig.

Medmindre du opretter man-sider ofte, er det hårdt arbejde at skrive en og manuelt indsætte makroerne. Handlingen med at oprette en man-side, der analyserer korrekt og ser rigtig ud, kan overhale dit mål for at give en kortfattet, men dog grundig, beskrivelse af din kommando.

Du bør koncentrere dig om dit indhold, ikke kæmpe mod et obskurt sæt makroer.

pandoc til undsætning

Det pandoc program læser markdown-filer og genererer nye i omkring 40 forskellige markup-sprog og dokumentformater, inklusive man-sidens. Det forvandler man page skriveprocessen totalt, så du ikke behøver at kæmpe med hieroglyfer.

For at komme i gang kan du installere Pandoc på Ubuntu med denne kommando:

sudo apt-get install pandoc

På Fedora er kommandoen du har brug for følgende:

sudo dnf install pandoc

På Manjaro skal du skrive:

sudo pacman -Syu pandoc

Udsnit af en man-side

man-sider indeholder sektioner, der følger en standardnavnekonvention. De sektioner, som din man-side har brug for, er dikteret af den sofistikerede kommando, du beskriver.

Som minimum indeholder de fleste man-sider disse sektioner:

Navn: Navnet på kommandoen og en fyldig one-liner, der beskriver dens funktion.
Synopsis: En kortfattet beskrivelse af de påkald, nogen kan bruge til at starte programmet. Disse viser typer af accepterede kommandolinjeparametre.
Beskrivelse: En beskrivelse af kommandoen eller funktionen.
Indstillinger: En liste over kommandolinjeindstillinger, og hvad de gør.
Eksempler: Nogle eksempler på almindelig brug.
Udgangsværdier: De mulige returkoder og deres betydning.
Bugs: En liste over kendte fejl og særheder. Nogle gange er dette suppleret med (eller erstattet af) et link til problemet tracker for projektet.
Forfatter: Den eller de personer, der skrev kommandoen.
Copyright: Din copyright-meddelelse. Disse inkluderer normalt også den type licens, som programmet udgives under.

Hvis du kigger nogle af de mere komplicerede man-sider igennem, vil du se, at der også er mange andre sektioner. For eksempel, prøv mand mand. Du behøver dog ikke at inkludere dem alle – bare dem, du virkelig har brug for. man-sider er ikke noget sted for ord.

Nogle andre sektioner, du vil se rimeligt ofte, er:

Se også: Andre kommandoer relateret til emnet, som nogle ville finde nyttige eller relevante.
Filer: En liste over filer inkluderet i pakken.
Advarsler: Andre punkter at vide eller passe på.
Historik: En ændringshistorik for kommandoen.

Afsnit af manualen

Linux-manualen består af alle man-siderne, som derefter er opdelt i disse nummererede sektioner:

Eksekverbare programmer: Eller shell-kommandoer.
Systemkald: Funktioner leveret af kernen.
Bibliotekskald: Funktioner inden for programbiblioteker.
Særlige filer.
Filformater og konventioner: For eksempel “/etc/passwd”.
Spil.
Diverse: Makropakker og konventioner, såsom groff.
Systemadministrationskommandoer: Normalt reserveret til root.
Kernel-rutiner: Normalt ikke installeret som standard.

Hver man-side skal angive, hvilken sektion den tilhører, og den skal også gemmes på den passende placering for den sektion, som vi vil se senere. Man-siderne for kommandoer og hjælpeprogrammer hører hjemme i afsnit 1.

Formatet på en man-side

Groff-makroformatet er ikke let at visuelt parse. I modsætning hertil er markdown en leg.

Nedenfor er en man-side i groff.

Den samme side er vist nedenfor i markdown.

Front Materie

De første tre linjer danner noget, der hedder frontstof. Disse skal alle starte med et procenttegn (%), uden indledende mellemrum, men et bagefter, efterfulgt af:

Den første linje: Indeholder navnet på kommandoen, efterfulgt af den manuelle sektion i parentes, uden mellemrum. Navnet bliver venstre og højre sektion af man-sidehovedet. Efter konvention er kommandonavnet med store bogstaver, selvom du vil finde mange, der ikke er det. Alt, hvad der følger kommandonavnet og det manuelle sektionsnummer, bliver den venstre sektion af sidefoden. Det er praktisk at bruge dette til softwareversionsnummeret.
Anden linje: Navnet/navnene på forfatteren/forfatterne. Disse vises i en automatisk genereret forfattersektion på man-siden. Du behøver ikke at tilføje en “Forfattere”-sektion – du skal blot inkludere mindst ét ​​navn her.
Den tredje linje: Datoen, som også bliver den midterste del af sidefoden.

Navn

Sektioner er angivet med linjer, der starter med et taltegn (#), som er den markering, der angiver en overskrift i markdown. Taltegnet (#) skal være det første tegn på linjen, efterfulgt af et mellemrum.

Navneafsnittet indeholder en hurtig one-liner, der inkluderer navnet på kommandoen, et mellemrum, en bindestreg (-), et mellemrum og derefter en meget kort beskrivelse af, hvad kommandoen gør.

Synopsis

Synopsen indeholder de forskellige formater, kommandolinjen kan tage. Denne kommando kan acceptere et søgemønster eller en kommandolinjeindstilling. De to stjerner (**) på hver side af kommandonavnet betyder, at navnet vil blive vist med fed skrift på man-siden. En enkelt stjerne

på hver side af noget tekst får man-siden til at vise den understreget.

Som standard efterfølges et linjeskift af en tom linje. For at fremtvinge et hårdt brud uden en tom linje, kan du bruge en bagende skråstreg ().

Beskrivelse

Beskrivelsen forklarer, hvad kommandoen eller programmet gør. Det bør dække de vigtige detaljer kort og præcist. Husk, at du ikke skriver en brugervejledning.

Brug af to taltegn (##) i starten af ​​en linje skaber en niveau to overskrift. Du kan bruge disse til at dele din beskrivelse op i mindre bidder.

Muligheder

Indstillingssektionen indeholder en beskrivelse af alle kommandolinjeindstillinger, der kan bruges med kommandoen. Ifølge konventionen vises disse med fed skrift, så inkluder to stjerner (**) før og efter dem. Inkluder tekstbeskrivelsen af ​​mulighederne på næste linje, og start den med et kolon (:), efterfulgt af et mellemrum.

Hvis beskrivelsen er kort nok, vil man vise den på samme linje som kommandolinjeindstillingen. Hvis det er for langt, vises det som et indrykket afsnit, der begynder på linjen under kommandolinjeindstillingen.

Eksempler

Eksempelafsnittet indeholder et udvalg af forskellige kommandolinjeformater. Bemærk, at vi starter beskrivelseslinjerne med et kolon (:), ligesom vi gjorde afsnittet med muligheder.

Afslut værdier

Dette afsnit viser de returværdier, som din kommando sender tilbage til opkaldsprocessen. Dette kan være skallen, hvis du kaldte den fra kommandolinjen, eller et script, hvis du startede den fra et shell-script. Vi starter også beskrivelseslinjer med et kolon (:) i dette afsnit.

Bugs

Fejlsektionen viser kendte fejl, gotchas eller særheder, som folk har brug for at vide om. For open source-projekter er det almindeligt at inkludere et link her til projektets problemsporing for at kontrollere status for eventuelle fejl eller rapportere nye.

ophavsret

Afsnittet om ophavsret indeholder din copyright-erklæring og normalt en beskrivelse af den type licens, som softwaren udgives under.

En effektiv arbejdsgang

Du kan redigere din man-side i din foretrukne editor. De fleste, der understøtter syntaksfremhævning, vil være opmærksomme på markdown og farve teksten for at fremhæve overskrifter, samt fed og understrege den. Det er fantastisk, så vidt det rækker, men du ser ikke på en gengivet man-side, som er det virkelige bevis i buddingen.

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

Åbn et terminalvindue i den mappe, der indeholder din markdown-fil. Med den åben i din editor, gem med jævne mellemrum din fil på din harddisk. Hver gang du gør det, kan du udføre følgende kommando i terminalvinduet:

Når du har brugt denne kommando, kan du trykke på pil op for at gentage den og derefter trykke på Enter.

Denne kommando kalder også pandoc på markdown-filen (her hedder den “ms.1.md”):
Valgmuligheden -s (standalone) genererer en komplet man-side fra top til bund i stedet for blot noget tekst i man-format.

Indstillingen -t (outputtype) med “man”-operatoren fortæller pandoc at generere sit output i man-format. Vi har ikke bedt Pandoc om at sende sit output til en fil, så det vil blive sendt til stdout.

Vi overfører også det output til man med muligheden -l (lokal fil). Det fortæller manden ikke at søge gennem mandsdatabasen på udkig efter man-siden. I stedet skal den åbne den navngivne fil. Hvis filnavnet er -, vil man tage sit input fra stdin.

Hvad dette bunder i er, at du kan gemme fra din editor og trykke på Q for at lukke mand, hvis det kører i terminalvinduet. Derefter kan du trykke på pil op efterfulgt af Enter for at se en gengivet version af din man-side lige inde i mand.

Oprettelse af din man-side

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

Når du har fuldført din man-side, skal du oprette en endelig version af den og derefter installere den på dit system. Følgende kommando fortæller pandoc at generere en man-side kaldet “ms.1”:

Dette følger konventionen om at navngive man-siden efter den kommando, den beskriver, og tilføje det manuelle afsnitsnummer, som om det var en filtypenavn.

manpath

Dette opretter en “ms.1” fil, som er vores nye man-side. Hvor stiller vi det? Denne kommando fortæller os, hvor man søger efter man-sider:

Resultaterne giver os følgende information:
/usr/share/man: Placeringen af ​​standardbiblioteket med man-sider. Vi tilføjer ikke sider til dette bibliotek.
/usr/local/share/man: Dette symbolske link peger på “/usr/local/man.”

/usr/local/man: Det er her, vi skal placere vores nye man-side.

Bemærk, at de forskellige manualsektioner er indeholdt i deres egne mapper: mand1, mand2, mand3, og så videre. Hvis mappen for sektionen ikke eksisterer, skal vi oprette den.

sudo mkdir /usr/local/man/man1

For at gøre det skriver vi følgende:

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

Vi kopierer derefter “ms.1”-filen til den korrekte mappe: man forventer, at man-siderne bliver komprimeret, så vi bruger gzipat komprimere den

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

:

sudo mandb

For at få mand til at tilføje den nye fil til sin database, skriv følgende:

man ms

Det er det! Vi kan nu kalde vores nye man-side den samme som enhver anden ved at skrive:

Vores nye man-side er fundet og vist.

Den ligner en hvilken som helst anden man-side med fed, understreget og indrykket tekst på de relevante steder.

Beskrivelseslinjer, der passer ud for den mulighed, de beskriver, vises på samme linje. Linjer, der er for lange til at passe, vises under den mulighed, de beskriver.

Vi har også automatisk genereret en “Forfattere”-sektion. Sidefoden inkluderer også softwareversionsnummeret, datoen og kommandonavnet, som defineret i forsiden.

Hvis du vil . . .