miniatura|Pagina de manual pentru utilitarul sed, așa cum se vede în diverse distribuții Linux
O pagină de manual (man page), prescurtare de la manual page, este o formă de documentație software găsită pe sistemele de operare Unix și de tip Unix. Subiectele abordate includ programe, biblioteci de sistem, apeluri de sistem și uneori detalii despre sistemul local. Administratorii gazdei locale pot crea și instala pagini de manual asociate cu gazda specifică. Un utilizator final care dorește documentația poate invoca o pagină de documentație prin executarea comenzii man urmată de numele elementului pentru care dorește documentația. Aceste pagini de manual sunt de obicei solicitate de utilizatorii finali, programatori și administratori care lucrează în timp real, dar pot fi formatate și pentru imprimare.
În mod implicit, man folosește de obicei un program de formatare, cum ar fi nroff cu un pachet de macro-uri sau mandoc, precum și un program de paginare de terminal, cum ar fi more or less pentru a afișa rezultatul pe ecranul utilizatorului.
Paginile de manual sunt adesea denumite o formă online de documentație software, chiar dacă comanda man nu necesită acces la internet, deoarece paginile de manual sunt disponibile dintr-o interfață de linie de comandă cu comanda man sau dintr-o interfață grafică cu utilizatorul cu un vizualizator de pagini de manual, în loc să fie lizibile doar în format tipărit. Variabila de mediu MANPATH specifică adesea o listă de căi de directoare pentru a căuta diverse pagini de documentație. Paginile de manual datează din perioada în care documentația tipărită era norma.
Istorie miniatura|xman, o aplicație X11 timpurie pentru vizualizarea paginilor de manual miniatura|Pagina de manual introductivă a secțiunii 8 de pe OpenBSD, afișată într-o consolă text Încă din 1987, în cazul unor programe software, documentația era reprezentată de pagini tipărite, disponibile utilizatorilor la fața locului. În unele locații, acestea erau organizate în dosare de oțel, blocate împreună într-un suport de citire monolitic din oțel, prinse cu șuruburi pe o masă sau un blat, cu pagini organizate pentru actualizări modulare ale informațiilor, înlocuiri, erori și completări. Manualele populare despre microcomputere erau promovate ca fiind de vânzare în dosare cu pagini detașabile, cu actualizări regulate.
În primii doi ani ai istoriei Unix, nu exista nicio documentație. Unix Programmer's Manual (Manualul programatorului Unix) a fost publicat pentru prima dată pe 3 noiembrie 1971. Primele pagini de manual propriu-zise au fost scrise de Dennis Ritchie și Ken Thompson la insistențele managerului lor, Doug McIlroy, în 1971. Pe lângă paginile de manual, Manualul Programatorului a acumulat și un set de lucrări scurte, unele dintre ele tutoriale (de exemplu, pentru utilizarea generală a Unix, limbajul de programare C și instrumente precum Yacc), și altele descrieri mai detaliate ale caracteristicilor sistemului de operare. Versiunea tipărită a manualului a încăput inițial într-un singur dosar, dar începând cu PWB/UNIX și a 7-a ediție a Research Unix, a fost împărțită în două volume, paginile de manual tipărite formând Volumul 1. Originally published in Microsystems 5(11), November 1984.
Versiunile ulterioare ale documentației au imitat concizia primelor pagini de manual. Ritchie a adăugat o secțiune „How to get started” („Cum să începeți”) la introducerea ediției a treia, iar Lorinda Cherry a furnizat referința de buzunar „Purple Card” pentru edițiile a șasea și a șaptea. Versiunile software-ului au fost numite după revizuirea manualului; a șaptea ediție a Manualului programatorului Unix, de exemplu, a venit odată cu ediția a 7-a sau versiunea 7 a Unix.
Pentru a patra ediție, paginile de manual au fost formatate folosind pachetul de tipărire troff și setul său de macrocomenzi -man (care au fost complet revizuite între a șasea și a șaptea ediție a Manualului, Originally published in Microsystems 5(11), November 1984. dar de atunci nu s-au schimbat drastic). La acea vreme, disponibilitatea documentației online prin intermediul sistemului de pagini de manual era considerată un mare progres. Până în prezent, practic fiecare aplicație de linie de comandă Unix vine cu o pagină de manual, iar mulți utilizatori Unix percep lipsa paginilor de manual ale unui program ca un semn de calitate scăzută sau incompletitudine. Într-adevăr, unele proiecte, cum ar fi Debian, fac tot posibilul să scrie pagini de manual pentru programele cărora le lipsește una. Descendenții moderni ai versiunii 4.4BSD distribuie, de asemenea, pagini de manual ca una dintre principalele forme de documentație a sistemului (înlocuind vechile macrocomenzi -man cu noul -mdoc ).
În versiunea man-db a comenzii man exista un Easter egg ascuns care făcea ca comanda să returneze „gimme gimme gimme” atunci când era executată la 00:30 (o referință la piesa ABBA Gimme! Gimme! Gimme! (A Man After Midnight)). A fost introdus în 2011, dar mai întâi restricționat și apoi eliminat în 2017 după ce a fost în sfârșit găsit.
Formatare miniatura|Parte a man(1) din sistemul de operare FreeBSD, tipărită în format PDF Formatul implicit al paginilor de manual este troff, fie cu pachetul macro man (orientat spre aspect), fie cu mdoc (orientat spre semantic). Acest lucru face posibilă tipărirea unei pagini de manual în PostScript, PDF și diverse alte formate pentru vizualizare sau imprimare.
Unele sisteme Unix au un pachet pentru comanda man2html, care permite utilizatorilor să răsfoiască paginile lor man folosind un browser HTML. Sistemele cu groff și man-db ar trebui să utilizeze ieșirea HTML nativă de calitate superioară (man --html). Programul GNU Emacs WoMan (de la „WithOut man”) permite navigarea prin paginile de manual din editor.
În 2010, OpenBSD a depreciat troff pentru formatarea paginilor de manual în favoarea mandoc, un compilator/formatator specializat pentru pagini de manual cu suport nativ pentru ieșire în PostScript,HTML, XHTML și terminal. Acesta este menit să suporte doar un subset de troff utilizat în paginile de manual, în special cele care utilizează macrocomenzi mdoc.
Servicii online Destul de multe site-uri web oferă acces online la pagini de manual din diverse sisteme de tip Unix.
În februarie 2013, comunitatea BSD a văzut lansarea unui nou serviciu open source mdoc.su, care a unificat și scurtat accesul la scripturile man.cgi ale principalelor proiecte BSD moderne prin intermediul unui serviciu unic determinist de scurtare a URL-urilor bazat pe nginx pentru paginile man BSD.
Pentru Linux, a fost configurat un serviciu man7.org care să ofere manuale specifice sistemului. Un serviciu ManKier oferă o selecție mai largă și integrează și paginile TLDR.
Utilizarea comenzilor
Pentru a citi o pagină de manual pentru o comandă Unix, un utilizator poate tasta:man <command_name>În mod tradițional, paginile sunt denumite folosind notația „nume(secțiune)”: de exemplu, ftp(1). Secțiunea se referă la diferite moduri în care subiectul poate fi referențiat - de exemplu, ca apel de sistem, comandă sau pachet shell (linie de comandă), fișier de configurare al unui pachet sau construcție/antet de codare.
Același nume de pagină poate apărea în mai multe secțiuni ale manualului cum ar fi atunci când numele apelurilor de sistem, ale comenzilor utilizator sau ale pachetelor macro coincid. Exemple sunt man(1) și man(7) sau exit(2) și exit(3). Sintaxa pentru accesarea secțiunii non-implicite a manualului variază între diferitele implementări man.
Pe Solaris și illumos, de exemplu, sintaxa pentru citirea printf(3C) este:man -s 3c printfPe Linux și derivatele BSD, aceeași invocare ar fi:<syntaxhighlight lang="bash"> man 3 printf care caută comanda printf în secțiunea 3 a paginilor de manual. Numele real al fișierului include probabil secțiunea. Continuând acest exemplu, printf.3.gz ar fi un fișier de pagină de manual comprimat în secțiunea 3 pentru printf .
Secțiuni manuale Manualul este în general împărțit în opt secțiuni numerotate. Majoritatea sistemelor de astăzi (de exemplu, BSD, macOS, Linux, și Solaris 11.4) moștenesc schema de numerotare utilizată de Research Unix, în timp ce System V folosește o ordine diferită: Comun Sistemul V Descriere 1 1 Comenzi generale 2 2 Apeluri de sistem 3 3 Funcții de bibliotecă, acoperind în special biblioteca standard C 4 7 Fișiere speciale (de obicei dispozitive, cele găsite în /dev) și drivere 5 4 Formate și convenții de fișiere 6 6 Jocuri și screensavere 7 5 Diverse 8 1M Comenzi și daemoni de administrare a sistemului API-urile POSIX sunt prezente atât în secțiunea 2, cât și în secțiunea 3, unde secțiunea 2 conține API-uri implementate ca apeluri de sistem, iar secțiunea 3 conține API-uri implementate ca rutine de bibliotecă.
Pe unele sisteme, pot fi incluse secțiuni suplimentare, cum ar fi: Secțiune Descriere 0 Fișiere antet bibliotecă C (Unix v6) 9 Rutine de kernel (nucleu) (FreeBSD, SVR4, Linux) l Funcțiile bibliotecii LAPACK n Comenzi Tcl / Tk x Sistemul X Window Unele secțiuni sunt subdivizate în continuare prin intermediul unui sufix; de exemplu, în unele sisteme, secțiunea 3C este pentru apelurile bibliotecii C, 3M este pentru biblioteca matematică și așa mai departe. O consecință a acestui fapt este că secțiunea 8 (comenzi de administrare a sistemului) este uneori retrogradată în subsecțiunea 1M a secțiunii comenzilor principale. Unele sufixe ale subsecțiunilor au o semnificație generală în toate secțiunile: Subsecțiune Descriere p Specificații POSIX x Documentația sistemului X Window (Secțiunea 3 tinde să fie excepția, cu multe sufixe pentru diferite limbi.)
Unele versiuni de man stochează în cache versiunile formatate ale ultimelor pagini vizualizate. O formă este pagina cat, pur și simplu transmisă prin pipe către pager pentru afișare.
Aspect Toate paginile de manual urmează un aspect comun, optimizat pentru prezentarea pe un afișaj text ASCII simplu, posibil fără nicio formă de evidențiere sau control al fonturilor. Secțiunile prezente pot include:
NAME (NUME) Numele comenzii sau funcției, urmat de o descriere pe o linie a ceea ce face aceasta. SYNOPSIS (REZUMAT) În cazul unei comenzi, o descriere formală a modului de rulare și ce opțiuni din linia de comandă acceptă. Pentru funcțiile de program, o listă a parametrilor pe care îi acceptă funcția și fișierul antet care conține declarația acesteia. DESCRIPTION (DESCRIERE) O descriere textuală a funcționării comenzii sau funcției. Pentru programe, această secțiune include adesea explicații ale opțiunilor disponibile în linia de comandă. EXAMPLES (EXEMPLE) Câteva exemple de utilizare comună. SEE ALSO (VEZI ȘI) O listă de comenzi sau funcții conexe.
Pot fi prezente și alte secțiuni, dar acestea nu sunt bine standardizate în paginile de manual. Exemple comune includ: OPȚIUNI, STAREA DE IEȘIRE, VALOAREA RETURNATĂ, MEDIU, EROARE, FIȘIERE, AUTOR, RAPORTARE EROARE, ISTORIC și DREPTURI DE AUTOR.
Creare Paginile de manual pot fi scrise fie cu vechile macrocomenzi man, fie cu noile macrocomenzi doc. Setul de macrocomenzi man oferă funcții minimale de text îmbogățit, cu directive pentru linia de titlu, anteturile secțiunilor, fonturile (bold, mici sau italice), paragrafele și adăugarea/reducerea indentării. Noul limbaj mdoc este de natură mai semantică și conține macrocomenzi specializate pentru majoritatea secțiunilor standard, cum ar fi numele programului, sinopsisul, numele funcțiilor și numele autorilor. Aceste informații pot fi utilizate pentru a implementa o căutare semantică a manualelor prin programe precum mandoc . Deși include și directive pentru controlul direct al stilizării, este de așteptat ca macrocomenzile specializate să acopere majoritatea cazurilor de utilizare. Atât proiectul mandoc, cât și proiectul groff consideră mdoc formatul preferat pentru documentele noi.