A man page (a manual page, kézikönyv-oldal rövidítése) a szoftver dokumentációjának egy formája, amely a Unix és Unix-szerű operációs rendszereken található. A lefedett témák közé tartoznak a programok, a rendszerkönyvtárak, a rendszerhívások és néha a helyi rendszer részletei. A helyi állomás rendszergazdái létrehozhatják és telepíthetik az adott állomáshoz kapcsolódó kézikönyvoldalakat. A kézikönyv végfelhasználó a man parancs és az általa kívánt konkrét adat megadásával hívhat meg egy dokumentációs oldalt. Ezeket a kézikönyvoldalakat jellemzően a valós idejű munkát végző végfelhasználók, programozók és rendszergazdák kérik, de nyomtatásra is formázhatók.

Alapértelmezés szerint a man általában egy formázó programot használ, mint például az nroff egy makróval, valamint egy terminál pager programot, mint például a more vagy less, hogy a kimenetét megjelenítse a felhasználó képernyőjén.

A man oldalakat gyakran a szoftverdokumentáció online formájaként emlegetik, annak ellenére, hogy a man parancs nem igényel internet-hozzáférést. A MANPATH környezeti változó gyakran megadja a különböző dokumentációs oldalak keresésére szolgáló könyvtárak elérési útvonalainak listáját. A man oldalak még azokból az időkből származnak, amikor a nyomtatott dokumentáció volt a norma.

Története

A Unix (pl. GCOSA General Comprehensive Operating System (GCOS) a 36 bites GE-600 sorozatú és Honeywell 6000 sorozatú nagyszámítógépek felé orientált operációs rendszercsalád.) előtt a dokumentáció nyomtatott oldalakból állt, amelyek a helyiségben álltak a felhasználók (személyzet, diákok...) rendelkezésére, acél kötegekbe rendezve, egy monolitikus acél olvasóállványba zárva, egy asztalhoz vagy pulthoz csavarozva, az oldalakat a moduláris információfrissítések, cserék, hibajegyzékek és kiegészítések számára rendezve.

A Unix történetének első két évében nem létezett dokumentáció. A The Unix Programmer's Manual először 1971. november 3-án jelent meg. Az első tényleges man oldalakat Dennis Ritchie és Ken Thompson írta a menedzserük, Doug McIlroy nyomására 1971-ben. A man oldalakon kívül a Programmer's Manual egy sor rövid tanulmányt is felhalmozott, amelyek egy része oktatóanyag (pl. az általános Unix-használatról, a C programozási nyelvről és az olyan eszközökről, mint a Yacc), más részük pedig az operációs rendszer jellemzőinek részletesebb leírása. A kézikönyv nyomtatott változata eredetileg egyetlen kötegben volt, de a PWB/UNIXA Programmer's Workbench (PWB/UNIX) a Unix operációs rendszer egy korai, mára már megszűnt változata volt, amelyet az AT&T Bell Labs Computer Science Research Groupjában hoztak létre. Kijelölt célja az volt, hogy időmegosztásos munkakörnyezetet biztosítson programozók nagy csoportjai számára, akik nagyobb kötegelt feldolgozó számítógépek számára írtak szoftvereket. és a Research Unix 7. kiadása óta két kötetre osztották, és a nyomtatott man oldalak képezték az 1. kötetet. Originally published in Microsystems 5(11), November 1984.

A dokumentáció későbbi változatai az első man oldalak tömörségét utánozták. Ritchie a harmadik kiadás bevezetőjét kiegészítette egy „Hogyan kezdjünk hozzá” résszel, Lorinda Cherry pedig a hatodik és hetedik kiadáshoz mellékelte a „Purple Card” zsebreferenciát. A szoftverek verzióit a kézikönyv kiadásáról nevezték el; a Unix Programmer's Manual hetedik kiadása például a Unix 7. kiadásához vagy 7. verziójához tartozott.

A negyedik kiadásban a man oldalakat a troff szedőcsomag és a hozzá tartozó -man makrók segítségével formázták (amelyeket a kézikönyv hatodik és hetedik kiadása között teljesen átdolgoztak, de azóta sem változtak drasztikusan). Akkoriban nagy előrelépésnek számított, hogy a kézikönyvoldali rendszeren keresztül online dokumentáció állt rendelkezésre. A mai napig gyakorlatilag minden Unix parancssoros alkalmazáshoz tartozik man oldal, és sok Unix-felhasználó a man oldalak hiányát a program alacsony minőségének vagy hiányossága jeleként érzékeli. Sőt, egyes projektek, mint például a Debian, mindent megtesznek azért, hogy man oldalakat írjanak azt hiányoló programokhoz. A 4.4BSD modern utódai a man oldalakat is terjesztik, mint a rendszer dokumentációjának egyik elsődleges formáját (miután a régi -man makrókat felváltotta az újabb -mdoc).

Volt egy rejtett húsvéti tojás a man parancs man-db verziójában, amely a parancsot a „gimme gimme gimme gimme” visszatérésre késztette, ha 00:30-kor futott (utalás az ABBA Gimme! Gimme! Gimme! című dalára). 2011-ben vezették be, de először korlátozták, majd 2017-ben eltávolították, miután végül megtalálták.

Formázás

A man oldalak alapértelmezett formátuma a troff, a man makrocsomaggalA troff olyan makrókat tartalmaz, amelyek a dokumentum feldolgozásának megkezdése előtt futnak le. Ezek a makrók magukban foglalják az oldalfejlécek és láblécek beállítását, új parancsok definiálását és a kimenet formázásának befolyásolását. (megjelenés-orientált) vagy az mdoc (szemantika orientált). Ez lehetővé teszi, hogy egy man oldalt PostScript, PDF és különböző más formátumba gépeljünk át megtekintésre vagy nyomtatásra.

Néhány Unix-rendszer rendelkezik csomaggal a man2html parancshoz, amely lehetővé teszi a felhasználók számára, hogy HTML-böngészővel nézhessék a man-oldalakat. A groff-ot és man-db-t használó rendszereknek ehelyett a jobb minőségű natív HTML kimenetet (man—html) kell használniuk. A GNU Emacs WoMan (a „WithOut man”-ból) programja lehetővé teszi a man oldalak böngészését a szerkesztőből.

2010-ben az OpenBSD lemondott a troff-ról a man oldalak formázásánál a mandoc javára, amely egy speciális fordító/formázó a man oldalakhoz, és natívan támogatja a PostScript, HTML, XHTML és a terminál kimenetet. A kézikönyvoldalakban használt troff-oknak csak egy részhalmazát támogatja, különösen azokat, amelyek mdoc makrókat használnak.

Online szolgáltatások Számos weboldal kínál online hozzáférést a különböző Unix-szerű rendszerek kézikönyvoldalakhoz.

2013 februárjában a BSD közösségben elindult egy új, nyílt forráskódú mdoc.su szolgáltatás, amely egységesítette és lerövidítette a főbb modern BSD projektek man.cgi szkriptjeinek elérését egy egyedi, nginx-alapú, determinisztikus URL-rövidítési szolgáltatáson keresztül a *BSD man oldalakhoz.

A Linux esetében a man7.org szolgáltatás a rendszerre vonatkozó kézikönyvek kiszolgálására jött létre. A ManKier szolgáltatás szélesebb választékot kínál, és integrálja a TLDR oldalakat is.

A parancsok használata Egy Unix-parancs kézikönyvének elolvasásához a felhasználó a következőket írja be: man <command_name> Az oldalakra hagyományosan a „name(section)” jelöléssel hivatkoznak: például ftp(1). A szakasz különböző módokon utal a témára való hivatkozásra – például rendszerhívásként, vagy shell (parancssori) parancsként vagy csomagként, vagy egy csomag konfigurációs fájljaként, vagy kódolási konstrukcióként/fejlécként.

Ugyanaz az oldal neve a kézikönyv több szakaszában is előfordulhat, például amikor a rendszerhívások, felhasználói parancsok vagy makrócsomagok neve egybeesik. Ilyen például a man(1) és a man(7), vagy az exit(2) és az exit(3). A nem alapértelmezett kézikönyvrészlet elérésének szintaxisa a különböző man implementációk között változik.

Solaris és illumos rendszereken például a printf(3C) olvasásának szintaxisa a következő: man -s 3c printf Linuxon és BSD származékokon ugyanaz a meghívás lenne: man 3 printf amely a printf-et keresi a man oldalak 3. szakaszában. A tényleges fájlnév valószínűleg tartalmazza a szakaszt. A példát folytatva, a printf.3.gz egy tömörített man-oldal fájl lenne a printf 3. szakaszában.

Kézikönyv szakaszok A kézikönyv általában nyolc számozott szakaszra oszlik. A legtöbb mai rendszer (pl. BSD,man(1) – FreeBSD General Commands Manual macOS, Linux,man(1) – Linux General Commands Manual és Solaris 11.4) a Research Unix által használt számozási sémát örökli, míg a System V más sorrendet használ: Common System V Leírás 1 1 Általános parancsok 2 2 rendszerhívások 3 3 Könyvtári funkciók, különös tekintettel a C szabványos könyvtárra 4 7 Speciális fájlok (általában a /dev könyvtárban található eszközök) és illesztőprogramok 5 4 Fájlformátumok és konvenciók 6 6 Játékok és képernyővédők 7 5 Vegyes 8 1M Rendszeradminisztrációs parancsok démonok

A POSIX API-k a 2. és a 3. szakaszban is jelen vannak, ahol a 2. szakasz tartalmazza a rendszerhívásként megvalósított API-kat, a 3. szakasz pedig a könyvtári rutinokként megvalósított API-kat.

Egyes rendszereken további szakaszok is szerepelhetnek, mint például: Szakasz Leírás 0 C könyvtár fejlécfájlok (Unix v6) 9 Kernel rutinok (FreeBSD, SVR4, Linux) l LAPACK könyvtári funkciók n Tcl/Tk parancsok x Az X Window System

Egyes szakaszok egy utótaggal tovább vannak tagolva; például egyes rendszerekben a 3C szakasz a C könyvtárhívásokhoz, a 3M a matematikai könyvtárhoz stb. tartozik. Ennek következménye, hogy a 8. szakasz (rendszergazdai parancsok) néha a fő parancsok szakasz 1M alszakaszába kerül. Néhány alfejezet utótagjának általános jelentése van a szakaszok között: Alszakasz Leírás p POSIX specifikációk x X Window System dokumentáció (A 3. szakasz inkább kivétel a különböző nyelvekre vonatkozó számos utótaggal.)

A man egyes verziói a legutóbbi megtekintett oldalak formázott változatait gyorsítótárazzák. Ennek egyik formája a cat oldal, amelyet egyszerűen a lapozóba (pl.: more vagy less) csöveznek (pipeline) megjelenítésre.

Elrendezés Minden man oldal közös elrendezést követ, amely egyszerű ASCII szöveges megjelenítésre van optimalizálva, lehetőleg mindenféle kiemelés vagy betűtípus-szabályozás nélkül. A jelen lévő szakaszok a következők lehetnek:

NAME A parancs vagy függvény neve, amelyet egysoros leírás követ arról, hogy mit csinál. SYNOPSIS Parancsok esetén egy hivatalos leírás arról, hogyan kell futtatni, és milyen parancssori opciókat igényel. Programfüggvények esetén a függvény által felvett paraméterek listája, valamint az, hogy melyik fejlécfájl tartalmazza a függvény deklarációját. DESCRIPTION A parancs vagy funkció működésének szöveges leírása. Programok esetében ez a szakasz gyakran tartalmazza a rendelkezésre álló parancssori opciók magyarázatát. EXAMPLES Néhány példa a gyakori használatra. SEE ALSO A kapcsolódó parancsok vagy funkciók listája.

Más szakaszok is előfordulhatnak, de ezek nincsenek jól szabványosítva a man oldalakon. Gyakoriak például: OPTIONS, EXIT STATUS, RETURN VALUE, ENVIRONMENT, BUGS, FILES, AUTHOR, REPORTING BUGS, HISTORY és COPYRIGHT.

Szerzői eszközök A kézikönyvoldalakat a régi man makrókkal, az új doc makrókkal vagy a kettő kombinációjával (mandoc) lehet megírni.groff_tmac(5) – Linux File Formats Manual A man makrókészlet minimálisan gazdag szövegfunkciókat biztosít, a címsor, a szakaszcímek, a (félkövér, kicsi vagy dőlt) betűtípusok, a bekezdések és a behúzás hozzáadása/csökkentése irányelvekkel.man(7) – Linux Miscellanea Manual Az újabb mdoc nyelv szemantikusabb jellegű, és speciális makrókat tartalmaz a legtöbb szabványos részhez, mint például a program neve, szinopszis, függvénynevek és a szerzők neve. Ezek az információk felhasználhatók a kézikönyvek szemantikus keresésének megvalósítására olyan programokkal, mint a mandoc. Bár tartalmaz direktívákat is a formázás közvetlen vezérlésére, várhatóan a speciális makrók a legtöbb felhasználási esetet lefedik.mdoc(7) – FreeBSD Miscellaneous Information Manual Mind a mandoc, mind a groff projekt az mdoc-ot tekinti az új dokumentumok preferált formátumának.