Kézikönyv-lapok
elektronikus dokumentációs fájlformátum From Wikipedia, the free encyclopedia
Remove ads
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.
.jpg)
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,[1] 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.
Remove ads
Története
![Thumb](#/media/Fájl:Screenshot_of_"Xman"_program.png)
A Unix (pl. GCOS[2]) 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ó.[3] 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/UNIX[4] é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.[5]
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.[3] 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.[6]
A negyedik kiadásban a man oldalakat a troff szedőcsomag[3] é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,[5] 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[7], de először korlátozták[8], majd 2017-ben eltávolították[9], miután végül megtalálták.[10]
Remove ads
Formázás
A man oldalak alapértelmezett formátuma a troff, a man makrocsomaggal[11] (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.[12]
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.[13][14][15]
A Linux esetében a man7.org szolgáltatás a rendszerre vonatkozó kézikönyvek kiszolgálására jött létre.[16] A ManKier szolgáltatás szélesebb választékot kínál, és integrálja a TLDR oldalakat is.[17]
Remove ads
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,[18] macOS, Linux,[19] és Solaris 11.4) a Research Unix által használt számozási sémát örökli,[20][21] míg a System V más sorrendet használ:[22]
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:
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:
(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.
Remove ads
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:[24]
- 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.
Remove ads
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.[25] 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.[24] 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.[26] Mind a mandoc, mind a groff projekt az mdoc-ot tekinti az új dokumentumok preferált formátumának.[27]
Bár a man oldalak a troff számára 10 pontos Roman betűkkel írt szövegek, ez a megkülönböztetés általában vitatható, mivel a man oldalakat a terminálon (TTY) nézik, nem pedig papíron. Ennek eredményeképpen a „small font” makró ritkán használatos.[28] Másrészt a félkövér és dőlt betűs szöveget a terminál támogatja az ECMA-48-on keresztül, és a groff grotty-ja ezeket kérés szerint ki is adja, amikor felismeri a támogató terminált. A BSD mandoc azonban csak a félkövér és aláhúzott szöveget támogatja (a dőlt betű helyett) az írógép backspace-then-overstrike szekvenciáján keresztül, amit less-szel kell lefordítani ECMA-48-ra.[29][30]
Néhány eszközt használtak a kevésbé mesterkélt formátumú dokumentumok kézi oldalakká történő átalakítására. Ilyen például a GNU help2man, amely a --help kimenetet és néhány további tartalmat vesz alapul, hogy kézikönyvoldalt hozzon létre.[31] A kézikönyv aligha lenne hasznosabb, mint az említett kimenet, de a GNU programok esetében ez nem probléma, mivel a texinfo a fő dokumentációs rendszer.[32] Számos eszköz, köztük a pandoc, a ronn és az md2man támogatja a Markdownból kézikönyv-oldalakra való konvertálást. Mindezek az eszközök a man formátumot bocsátják ki, mivel a Markdown nem elég kifejező ahhoz, hogy megfeleljen az mdoc szemantikai tartalmának. A DocBooknak van egy beépített man(7) konvertere – a mandoc szerzője[33] szerint megdöbbentő minőségben, aki írt egy külön mdoc(7) konvertert.
A man oldalak általában angol nyelven íródnak, de előfordulhat, hogy a rendszerben más nyelvekre is rendelkezésre állnak fordítások. A GNU man-db és a mandoc man ismert, hogy alkönyvtárak alatt keres lokalizált kézikönyvoldalakat.[34][18]
Alternatívák
A man kevés alternatívája örvendett nagy népszerűségnek, kivéve talán a GNU projekt „info” rendszerét, amely egy korai és egyszerű hipertext rendszer. Létezik egy harmadik féltől származó, TLDR pages (tldr) néven ismert erőfeszítés is, amely egyszerű példákat kínál a leggyakoribb felhasználási esetekre, hasonlóan egy puskázó táblázathoz.[35]
Ezenkívül néhány Unix GUI alkalmazás (különösen a GNOME és a KDE fejlesztői környezetek használatával készültek) már HTML formátumú dokumentációt biztosít a végfelhasználók számára, és beágyazott HTML megjelenítő programokat (például a yelp) tartalmaz az alkalmazáson belüli súgó olvasásához. Az Emacsban egy HTML rendszer is a tervek szerint felváltja a texinfo-t.[36]
Remove ads
Példa
Az yacc.1 tartalma:
.TH YACC "1" "November 2007" "GNU Bison 3.8.2" "User Commands"
.SH NAME
yacc \- GNU Project parser generator
.SH SYNOPSIS
.B yacc
[\fIOPTION\fR]... \fIFILE\fR
.SH DESCRIPTION
.I Yacc
(Yet Another Compiler Compiler) is a parser generator. This
version is a simple wrapper around
.IR bison (1).
It passes option
\fB\-y\fR, \fB\-\-yacc\fR
to activate the upward compatibility mode. See
.IR bison (1)
for more information.
.SH AUTHOR
Written by Paul Eggert.
.SH "REPORTING BUGS"
Report bugs to <bug-bison@gnu.org>.
.SH COPYRIGHT
Copyright \(co 2021 Free Software Foundation, Inc.
.br
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.SH "SEE ALSO"
Remove ads
Lásd még
Jegyzetek
További információk
Fordítás
Wikiwand - on
Seamless Wikipedia browsing. On steroids.
Remove ads