Kézikönyv-lapok

Innen: Hungaropédia
Ugrás a navigációhozUgrás a kereséshez
A sed segédprogram kézikönyvoldala, amint az a különböző Linux disztribúciókban látható.

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(wd) é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(wd) é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ű(wd) 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(wd) egy makróval, valamint egy terminál pager(wd) 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.

Története

xman, egy korai X11 alkalmazás kézikönyv oldalak megtekintéséhez
Az OpenBSD 8. szekciójának bevezető oldala szöveges konzolon

A Unix (pl. GCOS(wd)[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(wd) 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(wd)[4] és a Research Unix(wd) 7. kiadása(wd) ó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(wd) bevezetőjét kiegészítette egy „Hogyan kezdjünk hozzá” résszel, Lorinda Cherry(wd) pedig a hatodik(wd) és hetedik(wd) 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(wd) 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]

Formázás

A FreeBSD man(1) kézikönyv oldalának része, PDF formátumba szedve

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(wd) 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(wd) és man-db-t(wd) 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(wd) 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ú(wd), determinisztikus URL-rövidítési(wd) 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(wd) is.[17]

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(wd), felhasználói parancsok(wd) 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(wd) által használt számozási sémát örökli,[20][21] míg a System V más sorrendet használ:[22]

Common System V Leírás
1 1 Általános parancsok(wd)
2 2 rendszerhívások(wd)
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(wd) (á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(wd)
7 5 Vegyes
8 1M Rendszeradminisztrációs parancsok démonok(wd)

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(wd) (Unix v6)
9 Kernel rutinok (FreeBSD, SVR4, Linux)[21][18]
l LAPACK(wd) könyvtári funkciók[23]
n Tcl(wd)/Tk(wd) 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(wd) (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:[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.

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(wd) megvalósítására olyan programokkal, mint a mandoc(wd). 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(wd), mind a groff(wd) 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(wd) betűkkel írt szövegek, ez a megkülönböztetés általában vitatható, mivel a man oldalakat a terminálon (TTY(wd)) 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(wd) keresztül, és a groff grotty-ja ezeket kérés szerint ki is adja, amikor felismeri a támogató terminált. A BSD(wd) 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(wd), 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(wd) 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(wd) „info”(wd) 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(wd)) 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(wd).[36]

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"

Lásd még

Jegyzetek

  1. ↑ man(1). FreeBSD General Commands Manual . [2023. január 30-i dátummal az eredetiből archiválva]. (Hozzáférés: 2023. július 15.)
  2. ↑ A General Comprehensive Operating System (GCOS) a 36 bites GE-600 sorozatú(wd) és Honeywell 6000 sorozatú(wd) nagyszámítógépek felé orientált operációs rendszercsalád.
  3. ↑ 3,0 3,1 3,2 A Research Unix reader: annotated excerpts from the Programmer's Manual, 1971–1986, CSTR (1987) 
  4. ↑ A 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.
  5. ↑ 5,0 5,1 UNIX Evolution: 1975-1984 Part I - Diversity. [2012. július 17-i dátummal az eredetiből archiválva]. (Hozzáférés: 2012. december 22.) Originally published in Microsystems 5(11), November 1984.
  6. ↑ Fiedler, Ryan. „The Unix Tutorial / Part 3: Unix in the Microcomputer Marketplace”, BYTE, 1983. október 1., 132. oldal (Hozzáférés: 2015. január 30.) 
  7. ↑ GIT commit 002a6339b1fe8f83f4808022a17e1aa379756d99. [2017. december 4-i dátummal az eredetiből archiválva]. (Hozzáférés: 2017. november 22.)
  8. ↑ GIT commit 84bde8d8a9a357bd372793d25746ac6b49480525. [2018. szeptember 5-i dátummal az eredetiből archiválva]. (Hozzáférés: 2017. november 22.)
  9. ↑ GIT commit b225d9e76fbb0a6a4539c0992fba88c83f0bd37e. [2020. november 9-i dátummal az eredetiből archiválva]. (Hozzáférés: 2018. szeptember 25.)
  10. ↑ "Why does man print "gimme gimme gimme" at 00:30?". [2017. november 21-i dátummal az eredetiből archiválva]. (Hozzáférés: 2017. november 22.)
  11. ↑ A 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.
  12. ↑ WoMan: Browse Unix Manual Pages "W.O. (without) Man". GNU. [2020. november 11-i dátummal az eredetiből archiválva]. (Hozzáférés: 2020. augusztus 3.)
  13. ↑ FreeBSD Quarterly Status Report, January-March 2013. FreeBSD, 2013. május 12. [2014. december 22-i dátummal az eredetiből archiválva]. (Hozzáférés: 2014. december 25.)
  14. ↑ Murenin, Constantine A. (19 February 2013), "announcing mdoc.su, short manual page URLs"
  15. ↑ Murenin, Constantine A.: mdoc.su — Short manual page URLs for FreeBSD, OpenBSD, NetBSD and DragonFly BSD, 2013. február 23. [2014. december 17-i dátummal az eredetiből archiválva]. (Hozzáférés: 2014. december 25.)
  16. ↑ Linux man pages online. man7.org . [2020. május 7-i dátummal az eredetiből archiválva]. (Hozzáférés: 2020. május 5.)
  17. ↑ About. ManKier . [2020. április 25-i dátummal az eredetiből archiválva]. (Hozzáférés: 2020. május 5.)
  18. ↑ 18,0 18,1 18,2 man(1) – FreeBSD General Commands Manual
  19. ↑ man(1) – Linux General Commands Manual
  20. ↑ Manual Pages for Research Unix Eighth Edition. man.cat-v.org . [2020. június 30-i dátummal az eredetiből archiválva]. (Hozzáférés: 2020. május 6.)
  21. ↑ 21,0 21,1 Unix Programmer's Manual - Introduction. www.bell-labs.com , 1971. november 3. [2020. június 1-i dátummal az eredetiből archiválva]. (Hozzáférés: 2020. május 6.)
  22. ↑ System V release 4 manuals. bitsavers.trailing-edge.com . [2020. augusztus 3-i dátummal az eredetiből archiválva]. (Hozzáférés: 2020. május 6.)
  23. ↑ lapack (l) - Linux Man Pages. www.systutorials.com . [2023. március 11-i dátummal az eredetiből archiválva]. (Hozzáférés: 2021. május 29.)
  24. ↑ 24,0 24,1 man(7) – Linux Miscellanea Manual
  25. ↑ groff_tmac(5) – Linux File Formats Manual
  26. ↑ mdoc(7) – FreeBSD Miscellaneous Information Manual
  27. ↑ Groff Mission Statement - 2014. www.gnu.org . [2020. december 3-i dátummal az eredetiből archiválva]. (Hozzáférés: 2021. január 2.) „Concurrent with work on man(7), mdoc(7) will be actively supported and its use promoted.”
  28. ↑ man. The GNU Troff Manual . [2019. december 24-i dátummal az eredetiből archiválva]. (Hozzáférés: 2019. december 31.)
  29. ↑ Italics and colour in manual pages on a nosh user-space virtual terminal. jdebp.eu . [2021. január 28-i dátummal az eredetiből archiválva]. (Hozzáférés: 2021. január 21.)
  30. ↑ mandoc(1) – FreeBSD General Commands Manual. "Font styles are applied by using back-spaced encoding..."
  31. ↑ help2man Reference Manual. [2023. március 6-i dátummal az eredetiből archiválva]. (Hozzáférés: 2023. március 5.)
  32. ↑ Man Pages (GNU Coding Standards). www.gnu.org . [2023. március 5-i dátummal az eredetiből archiválva]. (Hozzáférés: 2023. március 5.)
  33. ↑ Ingo Schwarze: New mandoc -mdoc -T markdown converter. undeadly.org . [2023. március 5-i dátummal az eredetiből archiválva]. (Hozzáférés: 2023. március 5.) – for specific complaints by the author, see Ingo Schwarze (28 February 2014), "Re: Groff man pages (tangential to Future Redux)"
  34. ↑ command line - Linux man pages in different languages. Ask Ubuntu . [2023. március 11-i dátummal az eredetiből archiválva]. (Hozzáférés: 2020. május 5.)
  35. ↑ TLDR pages. tldr.sh . [2020. április 27-i dátummal az eredetiből archiválva]. (Hozzáférés: 2020. május 5.)
  36. ↑ Raymond, Eric S., "Re: [Groff man pages (tangential to Future Redux)"]

További információk

Fordítás

  • Ez a szócikk részben vagy egészben a man page című angol Wikipédia-szócikk fordításán alapul. Az eredeti cikk szerkesztőit annak laptörténete sorolja fel. Ez a jelzés csupán a megfogalmazás eredetét és a szerzői jogokat jelzi, nem szolgál a cikkben szereplő információk forrásmegjelöléseként.

A lap eredeti címe: „https://hungaropedia.org/index.php?title=Kézikönyv-lapok&oldid=100438”