Man-oldal létrehozása Linuxon

Szeretné, hogy új Linux-programja professzionálisan nézzen ki? Adj neki egy man oldalt. Megmutatjuk ennek legegyszerűbb és leggyorsabb módját.

Tartalomjegyzék

A férfi Pages

A régi Unix-viccben van az igazság magja: „a csak a parancsra van szüksége tudni ember.” A kézikönyvoldalak rengeteg tudást tartalmaznak, és ezeken kell először fordulnia, ha egy parancsról szeretne tájékozódni.

Ha egy megírt segédprogramhoz vagy parancshoz egy kézikönyvoldalt biztosít, az hasznos kódrészletből egy teljesen kialakított Linux-csomaggá válik. Az emberek azt várják, hogy egy kézikönyv oldalt biztosítsanak egy Linuxra írt programhoz. Ha natívan támogatja a Linuxot, akkor kötelező a kézikönyvoldal, ha azt szeretné, hogy programját komolyan vegyék.

Történelmileg a kézikönyvoldalakat formázási makrók segítségével írták. Amikor felszólítod az embert, hogy nyisson meg egy oldalt, az megszólítja Groff-ot olvassa el a fájlt, és formázott kimenetet generál, a fájlban található makrók szerint. A kimenet kevesebbre kerül, majd megjelenik az Ön számára.

  Hogyan nézheti meg, mennyi RAM van a számítógépben (és sebessége)

Hacsak nem készít gyakran kézikönyvoldalakat, egy ilyen írása és a makrók manuális beszúrása nehéz munka. A helyesen elemző és jól kinéző kézikönyvoldal létrehozása megelőzheti azt a célt, hogy tömör, mégis alapos leírást adjon a parancsról.

A tartalomra kell koncentrálnia, nem pedig a makrók homályos halmazával kell megküzdenie.

pandoc a Mentéshez

A pandoc program beolvassa a leíró fájlokat, és újakat generál körülbelül 40 különböző jelölőnyelven és dokumentumformátumban, beleértve a man oldalét is. Teljesen átalakítja a man oldal írási folyamatát, így nem kell a hieroglifákkal birkóznia.

A kezdéshez telepítheti a pandoc-ot az Ubuntu-ra ezzel a paranccsal:

sudo apt-get install pandoc

A

Fedorán a következő parancsra van szüksége:

sudo dnf install pandoc

A Manjaro gépen írja be:

sudo pacman -Syu pandoc

Egy férfi oldal szakaszai

a man oldalak szabványos elnevezési konvenciót követő szakaszokat tartalmaznak. Azt, hogy a man oldalnak mely szakaszokra van szüksége, a leírt parancs kifinomultsága határozza meg.

A legtöbb man oldal legalább a következő részeket tartalmazza:

Név: A parancs neve és a funkcióját leíró egysoros egysoros.
Szinopszis: A program elindításához felhasználható meghívások tömör leírása. Ezek az elfogadott parancssori paraméterek típusait mutatják.
Leírás: A parancs vagy funkció leírása.
Opciók: A parancssori opciók listája és azok funkciója.
Példák: Néhány példa a gyakori használatra.
Kilépési értékek: A lehetséges visszatérési kódok és jelentésük.
Hibák: Az ismert hibák és furcsaságok listája. Néha ezt kiegészítik (vagy helyettesítik) a projekt problémakövetőjére mutató hivatkozással.
Szerző: Az a személy vagy személyek, akik a parancsot írták.
Copyright: Az Ön szerzői jogi üzenete. Ezek általában azt is tartalmazzák, hogy milyen típusú licencet adnak ki a programnak.

Ha átnéz néhány bonyolultabb kézikönyvoldalt, látni fogja, hogy sok más rész is van. Például próbálja meg az embert. Nem kell azonban mindegyiket megadnia – csak azokat, amelyekre valóban szüksége van. a kézikönyvoldalakon nincs helye a szóhasználatnak.

Néhány további szakasz, amelyet meglehetősen gyakran fog látni:

Lásd még: A tárgyhoz kapcsolódó egyéb parancsok, amelyeket egyesek hasznosnak vagy relevánsnak találnának.
Fájlok: A csomagban található fájlok listája.
Figyelmeztetések: Egyéb tudnivalók vagy figyelnivalók.
Előzmények: A parancs változástörténete.

A kézikönyv szakaszai

A Linux kézikönyv az összes man oldalból áll, amelyek ezután a következő számozott részekre oszlanak:

Futtatható programok: Vagy shell parancsok.
Rendszerhívások: A kernel által biztosított funkciók.
Könyvtárhívások: A programkönyvtárak funkciói.
Különleges fájlok.
Fájlformátumok és konvenciók: Például „/etc/passwd”.
Játékok.
Vegyes: Makrócsomagok és konvenciók, mint például a groff.
Rendszeradminisztrációs parancsok: Általában a root számára fenntartva.
Kernel rutinok: Alapértelmezés szerint általában nem telepítik.

Minden kézikönyvoldalon fel kell tüntetni, hogy melyik részhez tartozik, és az adott szakasznak megfelelő helyen kell tárolni is, amint azt a későbbiekben látni fogjuk. A parancsok és segédprogramok kézikönyvoldalai az első részhez tartoznak.

  Felhasználói adatok megváltoztatása chfn és usermod segítségével Linuxon

A férfi oldal formátuma

A groff makró formátumot nem könnyű vizuálisan elemezni. Ezzel szemben a leértékelés gyerekjáték.

Lent egy man oldal groffban.

Ugyanez az oldal látható alább a leértékelésben.

Front Matter

Az első három sor valami úgynevezett frontanyagot alkot. Ezeknek mind százalékjellel (%) kell kezdődniük, szóköz nélkül, csak utána, majd ezt követi:

Az első sor: Tartalmazza a parancs nevét, majd a kézi részt zárójelben, szóközök nélkül. A név a kézikönyvoldal fejlécének bal és jobb oldali részévé válik. Megállapodás szerint a parancs neve nagybetűvel van írva, bár sok olyan is található, ami nem. Bármi, ami a parancs nevét és a kézikönyv szakaszszámát követi, a lábléc bal oldali részévé válik. Kényelmes ezt a szoftver verziószámához használni.
A második sor: A szerző(k) neve(i). Ezek a kézikönyvoldal automatikusan generált szerzői részében jelennek meg. Nem kell „Szerzők” részt hozzáadnia – csak adja meg legalább egy nevet.
A harmadik sor: A dátum, amely a lábléc középső részévé is válik.

Név

A szakaszokat számjellel (#) kezdõdõ sorok jelzik, ami a fejléc jelölése. A számjelnek (#) a sor első karakterének kell lennie, majd szóköznek kell lennie.

A név rész tartalmaz egy frappáns egysoros sort, amely tartalmazza a parancs nevét, egy szóközt, egy kötőjelet (-), egy szóközt, majd egy nagyon rövid leírást a parancs működéséről.

Szinopszis

Az összefoglaló tartalmazza a parancssor különböző formátumait. Ez a parancs fogadhat keresési mintát vagy parancssori opciót. A parancs nevének két oldalán található két csillag (**) azt jelenti, hogy a név félkövéren jelenik meg a kézikönyvoldalon. Egyetlen csillag

egyes szövegek mindkét oldalán a kézikönyvoldal aláhúzva jeleníti meg.

Alapértelmezés szerint a sortörést egy üres sor követi. Ha kemény törést szeretne kikényszeríteni üres sor nélkül, használhat a végén fordított perjelet ().

Leírás

A leírás elmagyarázza, mit csinál a parancs vagy a program. Tömören kell tartalmaznia a fontos részleteket. Ne feledje, hogy Ön nem használati útmutatót ír.

Ha két számjelet (##) használunk a sor elején, akkor egy második szintű címsor jön létre. Ezek segítségével kisebb részekre bonthatja a leírást.

Opciók

A beállítások szakasz a paranccsal használható parancssori beállítások leírását tartalmazza. Megállapodás szerint ezek félkövéren vannak szedve, ezért tegyen két csillagot (**) eléjük és utánuk. A következő sorba írja be a lehetőségek szöveges leírását, és kezdje kettősponttal (:), majd szóközzel.

Ha a leírás elég rövid, a man ugyanabban a sorban jeleníti meg, mint a parancssori opció. Ha túl hosszú, akkor behúzott bekezdésként jelenik meg, amely a parancssori opció alatti sorban kezdődik.

Példák

  Hogyan lehet követni egy Skype-kapcsolatot

A példák szakasz különféle parancssori formátumokat tartalmaz. Ne feledje, hogy a leírási sorokat kettősponttal (:) kezdjük, ugyanúgy, mint a beállítások részt.

Kilépési értékek

Ez a szakasz felsorolja azokat a visszatérési értékeket, amelyeket a parancs küld vissza a hívó folyamatnak. Ez lehet a shell, ha parancssorból hívta meg, vagy egy szkript, ha shell szkriptből indította el. A leírás sorait ebben a részben is kettősponttal (:) kezdjük.

Hibák

A hibák szakasz felsorolja az ismert hibákat, hibákat vagy furcsaságokat, amelyekről az embereknek tudniuk kell. Nyílt forráskódú projekteknél gyakori, hogy ide helyeznek egy hivatkozást a projekt problémakövetőjére, hogy ellenőrizzék a hibák állapotát, vagy jelentsék az újakat.

szerzői jog

A szerzői jogi rész tartalmazza az Ön szerzői jogi nyilatkozatát, és általában annak a licencnek a leírását, amely alapján a szoftvert kiadták.

Hatékony munkafolyamat

A man oldalt szerkesztheti kedvenc szerkesztőjében. A legtöbb, amely támogatja a szintaktikai kiemelést, tudatában van a leértékelésnek, és színezi a szöveget, hogy kiemelje a címsorokat, valamint félkövéren és aláhúzva. Ez nagyon jó, de nem egy renderelt man oldalt nézel, ami az igazi bizonyíték a pudingban.

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

Nyisson meg egy terminálablakot abban a könyvtárban, amely tartalmazza a leértékelési fájlt. Ha meg van nyitva a szerkesztőben, időnként mentse a fájlt a merevlemezére. Minden alkalommal végrehajthatja a következő parancsot a terminálablakban:

A parancs használata után a felfelé mutató nyíl megnyomásával megismételheti, majd nyomja meg az Enter billentyűt.

Ez a parancs a pandoc-ot is meghívja a markdown fájlban (itt a neve „ms.1.md”):
Az -s (önálló) opció egy tetőtől lefelé haladó teljes kézikönyvet hoz létre, nem csak néhány szöveget man formátumban.

A -t (output type) opció a „man” operátorral arra utasítja a pandoc-ot, hogy a kimenetét man formátumban hozza létre. Nem mondtuk a pandoc-nak, hogy küldje el a kimenetét egy fájlba, ezért elküldi az stdout-nak.

Ezt a kimenetet a -l (helyi fájl) kapcsolóval is bevezetjük a manba. Azt mondja az embernek, hogy ne keressen a man-adatbázisban a man oldalt keresve. Ehelyett meg kell nyitnia a megnevezett fájlt. Ha a fájlnév -, a man az stdin-től veszi a bemenetet.

Ez annyit jelent, hogy mentheti a szerkesztőből, és megnyomhatja a Q gombot a man bezárásához, ha az fut a terminálablakban. Ezután nyomja meg a felfelé mutató nyilat, majd az Enter billentyűt, hogy megtekinthesse a man oldal renderelt verzióját, közvetlenül a man belsejében.

A férfi oldal létrehozása

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

Miután befejezte a kézikönyv oldalt, létre kell hoznia annak végleges verzióját, majd telepítenie kell a rendszerére. A következő parancs arra utasítja a pandocot, hogy hozzon létre egy „ms.1” nevű kézikönyvoldalt:

Ez azt a szokást követi, hogy a kézikönyvoldalt az általa leírt parancs után nevezik el, és hozzáfűzik a kézikönyv szakaszszámát, mintha az egy fájlkiterjesztés lenne.

manpath

Ezzel létrehoz egy „ms.1” fájlt, amely az új man oldalunk. Hová tegyük? Ez a parancs megmondja nekünk, hol keres a man oldalakat:

Az eredmények a következő információkat adják számunkra:
/usr/share/man: A kézikönyvoldalak szabványos könyvtárának helye. Nem adunk hozzá oldalakat ehhez a könyvtárhoz.
/usr/local/share/man: Ez a szimbolikus hivatkozás a „/usr/local/man” címre mutat.

/usr/local/man: Ide kell elhelyeznünk az új man oldalunkat.

Ne feledje, hogy a kézikönyv különböző részei a saját könyvtárukban találhatók: man1, man2, man3 és így tovább. Ha a szakasz könyvtára nem létezik, létre kell hoznunk.

sudo mkdir /usr/local/man/man1

Ehhez a következőket írjuk be:

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

Ezután másoljuk az „ms.1” fájlt a megfelelő könyvtárba: A man elvárja, hogy a kézikönyvoldalakat tömörítsék, ezért a gzip-et használjukösszenyomni

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

:

sudo mandb

Ahhoz, hogy az ember hozzáadja az új fájlt az adatbázisához, írja be a következőt:

man ms

Ez az! Mostantól ugyanúgy hívhatjuk új man oldalunkat, mint bármelyik másikat, ha beírjuk:

Megtaláltuk és megjelenik az új man oldalunk.

Úgy néz ki, mint bármely más manoldal, félkövér, aláhúzott és behúzott szövegekkel a megfelelő helyeken.

Az általuk leírt lehetőség mellé illeszkedő leírássorok ugyanabban a sorban jelennek meg. Túl hosszú sorok jelennek meg az általuk leírt opció alatt.

Ezenkívül automatikusan létrehoztunk egy „Szerzők” részt. A lábléc tartalmazza a szoftver verziószámát, a dátumot és a parancs nevét is, az elülső részben meghatározottak szerint.

Ha akarod . . .

Miután a pandoc létrehozta a kézikönyvoldalt, közvetlenül is szerkesztheti a fájlt groff makró formátumban, mielőtt áthelyezné a kézikönyvoldali könyvtárba, és gzip-be csomagolhatja.