Wilt u dat uw nieuwe Linux-programma er professioneel uitziet? Geef het een man bladzijde. We laten u de gemakkelijkste en snelste manier zien om dit te doen.
De man Pages
Er zit een kern van waarheid in de oude Unix-grap, “het enige commando dat je moet weten is man. ” De man pagina’s bevatten een schat aan kennis, en ze zouden de eerste plaats moeten zijn waar u naar toe gaat als u meer wilt weten over een commando.
Het verstrekken van een man pagina voor een hulpprogramma of commando dat je hebt geschreven, verhoogt het van een nuttig stuk code naar een volledig gevormd Linux-pakket. Mensen verwachten een man pagina die moet worden geleverd voor een programma dat is geschreven voor Linux. Als u Linux native ondersteunt, is een man pagina is verplicht als u wilt dat uw programma serieus wordt genomen.
Historisch gezien de man pagina’s zijn geschreven met behulp van een set opmaakmacro’s. Wanneer u belt man om een pagina te openen, roept hij groff om het bestand te lezen en geformatteerde uitvoer te genereren, volgens de macro’s in het bestand. De output wordt doorgesluisd less, en vervolgens voor u weergegeven.
Tenzij je iets creëert man pagina’s vaak, is het hard werken om er een te schrijven en de macro’s handmatig in te voegen. De handeling van het creëren van een man een pagina die correct wordt geparseerd en er goed uitziet, kan voorbijgaan aan uw doel om een beknopte, maar grondige beschrijving van uw opdracht te geven.
U moet zich concentreren op uw inhoud en niet vechten tegen een obscure reeks macro’s.
VERWANT: Hoe Linux’s man Command te gebruiken: Hidden Secrets and Basics
pandoc aan de Redding
De pandoc programma leest markdown-bestanden en genereert nieuwe in ongeveer 40 verschillende opmaaktalen en documentformaten, waaronder die van de man bladzijde. Het transformeert het man pagina schrijfproces, zodat u niet hoeft te worstelen met hiërogliefen.
Om te beginnen, kunt u installeren pandoc op Ubuntu met dit commando:
sudo apt-get install pandoc
Op Fedora is het commando dat je nodig hebt het volgende:
sudo dnf install pandoc
Typ op Manjaro:
sudo pacman -Syu pandoc
VERWANT: Pandoc gebruiken om bestanden op de Linux-opdrachtregel te converteren
Secties van een man-pagina
man pagina’s bevatten secties die een standaard naamgevingsconventie volgen. De secties uw man de paginabehoeften worden bepaald door de verfijning van de opdracht die u beschrijft.
De meeste man-pagina’s bevatten minimaal deze secties:
- Naam: De naam van de opdracht en een pittige oneliner die de functie ervan beschrijft.
- Korte inhoud: Een beknopte beschrijving van de aanroepen die iemand kan gebruiken om het programma te starten. Deze tonen de soorten geaccepteerde opdrachtregelparameters.
- Omschrijving: Een beschrijving van de opdracht of functie.
- Opties: Een lijst met opdrachtregelopties en wat ze doen.
- Voorbeelden: Enkele voorbeelden van algemeen gebruik.
- Exit Waarden: De mogelijke retourcodes en hun betekenis.
- Bugs: Een lijst met bekende bugs en eigenaardigheden. Soms wordt dit aangevuld met (of vervangen door) een link naar de issue tracker van het project.
- Schrijver: De persoon of personen die de opdracht hebben geschreven.
- auteursrechten: Uw copyright-bericht. Deze omvatten meestal ook het type licentie waaronder het programma wordt vrijgegeven.
Als je enkele van de meer gecompliceerde man pagina’s, zie je dat er ook veel andere secties zijn. Probeer bijvoorbeeld man man. Je hoeft ze echter niet allemaal op te nemen – alleen degene die je echt nodig hebt. man pagina’s zijn geen plaats voor omslachtigheid.
Enkele andere secties die u redelijk vaak zult zien, zijn:
- Zie ook: Andere opdrachten die verband houden met het onderwerp, zouden sommigen nuttig of relevant vinden.
- Bestanden: Een lijst met bestanden in het pakket.
- Waarschuwingen: Andere punten om te weten of op te letten.
- Geschiedenis: Een wijzigingsgeschiedenis voor de opdracht.
Delen van de handleiding
De Linux-handleiding bestaat uit alle man pagina’s, die vervolgens worden opgesplitst in deze genummerde secties:
- Uitvoerbare programma’s: Of shell-opdrachten.
- Systeemoproepen: Functies geleverd door de kernel.
- Bibliotheekoproepen: Functies binnen programmabibliotheken.
- Speciale bestanden.
- Bestandsindelingen en conventies: Bijvoorbeeld “/ etc / passwd”.
- Spellen.
-
Diversen: Macropakketten en conventies, zoals
groff. - Systeembeheeropdrachten: Meestal gereserveerd voor root.
- Kernel-routines: Meestal niet standaard geïnstalleerd.
Elke man pagina moet aangeven tot welke sectie het behoort, en het moet ook worden opgeslagen op de juiste locatie voor die sectie, zoals we later zullen zien. De man pagina’s voor opdrachten en hulpprogramma’s behoren tot sectie één.
Het formaat van een man-pagina
De groff macro-indeling is niet gemakkelijk visueel te ontleden. Markdown daarentegen is een fluitje van een cent.
Hieronder is een man-pagina in groff.
Dezelfde pagina wordt hieronder weergegeven in markdown.
Front Matter
De eerste drie regels vormen iets genaamd voorwerk. Deze moeten allemaal beginnen met een procentteken (%), zonder voorloopspaties maar één erna, gevolgd door:
-
De eerste regel: Bevat de naam van de opdracht, gevolgd door het handmatige gedeelte tussen haakjes, zonder spaties. De naam wordt de linker- en rechtersectie van het
manpagina hoofd. Volgens afspraak is de opdrachtnaam in hoofdletters, hoewel u er genoeg zult vinden die dat niet zijn. Alles wat volgt op de commandonaam en het handmatige sectienummer wordt het linkerdeel van de voettekst. Het is handig om dit te gebruiken voor het softwareversienummer. -
De tweede regel: De naam (namen) van de auteur (s). Deze worden weergegeven in een automatisch gegenereerde auteurssectie van het
manbladzijde. U hoeft geen sectie “Auteurs” toe te voegen – neem hier gewoon minstens één naam op. - De derde regel: De datum, die ook het middelste deel van de voettekst wordt.
Naam
Secties worden aangegeven door lijnen die beginnen met een hekje (#), wat de markup is die een koptekst in markdown aangeeft. Het hekje (#) moet het eerste teken op de regel zijn, gevolgd door een spatie.
Het naamgedeelte bevat een pittige one-liner met de naam van het commando, een spatie, een koppelteken (-), een spatie en vervolgens een zeer korte beschrijving van wat de opdracht doet.
Korte inhoud
De synopsis bevat de verschillende formaten die de opdrachtregel kan aannemen. Deze opdracht kan een zoekpatroon of een opdrachtregeloptie accepteren. De twee asterisken (**) aan weerszijden van de commandonaam betekent dat de naam vetgedrukt wordt weergegeven op het man bladzijde. Een enkele asterisk (*) aan weerszijden van sommige tekst veroorzaakt de man pagina om deze onderstreept weer te geven.
Standaard wordt een regeleinde gevolgd door een lege regel. Om een harde pauze te forceren zonder een lege regel, kunt u een trailing backslash ().
Omschrijving
De beschrijving legt uit wat de opdracht of het programma doet. Het moet de belangrijke details beknopt behandelen. Onthoud dat u geen gebruikershandleiding schrijft.
Met behulp van twee nummerborden (##) aan het begin van een regel creëert een kop van niveau twee. U kunt deze gebruiken om uw beschrijving op te splitsen in kleinere stukjes.
Opties
De sectie met opties bevat een beschrijving van alle opdrachtregelopties die met de opdracht kunnen worden gebruikt. Volgens afspraak worden deze vetgedrukt weergegeven, dus neem twee sterretjes (**) voor en na hen. Voeg de tekstbeschrijving van de opties op de volgende regel toe en begin deze met een dubbele punt (:), gevolgd door een spatie.
Als de beschrijving kort genoeg is, man zal het op dezelfde regel weergeven als de opdrachtregeloptie. Als het te lang is, wordt het weergegeven als een ingesprongen alinea die begint op de regel onder de opdrachtregeloptie.
Voorbeelden
De voorbeeldensectie bevat een selectie van verschillende opdrachtregelformaten. Merk op dat we de beschrijvingsregels beginnen met een dubbele punt (:), net zoals we het gedeelte met opties hebben gedaan.
Exit Waarden
Deze sectie bevat de retourwaarden die uw opdracht terugstuurt naar het aanroepproces. Dit kan de shell zijn als je het vanaf de opdrachtregel hebt aangeroepen, of een script als je het vanuit een shell-script hebt gestart. We beginnen beschrijvingsregels met een dubbele punt (:) in deze sectie.
Bugs
De sectie bugs bevat bekende bugs, valstrikken of eigenaardigheden die mensen moeten kennen. Voor open-sourceprojecten is het gebruikelijk om hier een link op te nemen naar de issue-tracker van het project om de status van eventuele bugs te controleren of nieuwe te rapporteren.
auteursrechten
Het copyright-gedeelte bevat uw copyrightverklaring en meestal een beschrijving van het type licentie waaronder de software wordt vrijgegeven.
Een efficiënte workflow
U kunt uw man pagina in uw favoriete editor. De meesten die syntaxisaccentuering ondersteunen, zijn op de hoogte van markdown en kleuren de tekst om koppen te markeren, evenals vetgedrukt en onderstreept. Dat is geweldig voor zover het gaat, maar je kijkt niet naar een gerenderd man pagina, dat is het echte bewijs in de pudding.
Open een terminalvenster in de directory die uw markdown-bestand bevat. Met het geopend in uw editor, slaat u uw bestand regelmatig op uw harde schijf op. Elke keer dat u dat doet, kunt u de volgende opdracht uitvoeren in het terminalvenster:
pandoc ms.1.md -s -t man | /usr/bin/man -l -
Nadat u deze opdracht hebt gebruikt, kunt u op de pijl-omhoog drukken om deze te herhalen en vervolgens op Enter drukken.
Dit commando roept ook op pandoc op het markdown-bestand (hier heet het “ms.1.md”):
- De
-s(standalone) optie genereert een compleet van boven naar benedenmanpagina, in plaats van alleen wat tekst inmanformaat. - De
-t(output type) optie met de “man” operator verteltpandocom zijn output te genereren inmanformaat. We hebben het niet verteldpandocom zijn uitvoer naar een bestand te sturen, zodat het naarstdout.
We sturen die output ook naar man met de -l (lokaal bestand) optie. Het zegt man niet door de man database op zoek naar de man bladzijde. In plaats daarvan zou het het genoemde bestand moeten openen. Als de bestandsnaam -, man zal zijn input van stdin.
Waar dit op neerkomt, is dat je het kunt opslaan vanuit je editor en op Q kunt drukken om te sluiten man als het in het terminalvenster wordt uitgevoerd. Vervolgens kunt u op de pijl omhoog drukken, gevolgd door Enter om een gerenderde versie van uw man pagina, rechts binnen man.
VERWANT: Wat zijn stdin, stdout en stderr op Linux?
Uw manpagina maken
Nadat u uw man pagina, moet u een definitieve versie ervan maken en deze vervolgens op uw systeem installeren. Het volgende commando vertelt pandoc om een man pagina genaamd “ms.1”:
pandoc ms.1.md -s -t man -o ms.1
Dit volgt de conventie van het benoemen van het man pagina na het commando beschrijft het en voegt het handmatige sectienummer toe alsof het een bestandsextensie is.
Dit creëert een “ms.1” -bestand, dat ons nieuwe is man bladzijde. Waar plaatsen we het? Dit commando zal ons vertellen waar man zoekt naar man Pagina’s:
manpath
De resultaten geven ons de volgende informatie:
-
/ usr / share / man: De locatie van de standaardbibliotheek van
manPagina’s. We voegen geen pagina’s toe aan deze bibliotheek. - / usr / local / share / man: Deze symbolische link verwijst naar “/ usr / local / man.”
-
/ usr / local / man: Dit is waar we onze nieuwe moeten plaatsen
manbladzijde.
Merk op dat de verschillende handmatige secties zich in hun eigen mappen bevinden: man1, man2, man3, enzovoort. Als de directory voor de sectie niet bestaat, moeten we deze maken.
Om dit te doen, typen we het volgende:
sudo mkdir /usr/local/man/man1
We kopiëren dan het “ms.1” -bestand naar de juiste directory:
sudo cp ms.1 /usr/local/man/man1
man verwacht het man pagina’s die moeten worden gecomprimeerd, dus we gebruiken gzip om het te comprimeren:
sudo gzip /usr/local/man/man1/ms.1
Maken man voeg het nieuwe bestand toe aan de database, typ het volgende:
sudo mandb
Dat is het! We kunnen nu onze nieuwe bellen man pagina hetzelfde als alle andere door te typen:
man ms
Onze nieuwe man pagina is gevonden en weergegeven.
Het ziet er net zo uit als elk ander man pagina, met vetgedrukte, onderstreepte en ingesprongen tekst op de juiste plaatsen.
Regels met beschrijvingen die passen naast de optie die ze beschrijven, verschijnen op dezelfde regel. Lijnen die te lang zijn om te passen, verschijnen onder de optie die ze beschrijven.
We hebben ook automatisch een sectie “Auteurs” gegenereerd. De voettekst bevat ook het softwareversienummer, de datum en de opdrachtnaam, zoals gedefinieerd in het voorwerk.
Als je wilt . . .
Een keer pandoc heeft uw man pagina kunt u het bestand ook rechtstreeks bewerken in de groff macro-indeling voordat u deze naar het man paginamap, en gzip het.